From 739703b5b9ad70eddd6694c89983ea46517d1acd Mon Sep 17 00:00:00 2001 From: Caio Fonseca Date: Tue, 14 Jul 2026 21:59:34 +0100 Subject: [PATCH 1/4] Add sample database page to getting started docs --- .../getting-started/sample-database.rst | 67 +++++++++++++++++++ docs/source/getting-started/toc.rst | 1 + 2 files changed, 68 insertions(+) create mode 100644 docs/source/getting-started/sample-database.rst diff --git a/docs/source/getting-started/sample-database.rst b/docs/source/getting-started/sample-database.rst new file mode 100644 index 000000000..fbeb3f581 --- /dev/null +++ b/docs/source/getting-started/sample-database.rst @@ -0,0 +1,67 @@ +Sample Database +=============== + +A ready-to-use PostgreSQL database, pre-loaded with real project data collected by CollectOSS, +so you can run `8Knot `_ — or explore the data from a +notebook — **locally, without access to a remote CollectOSS instance**. + +It ships as a published container image, so there is nothing to build and no data +file to supply. ``docker compose up`` pulls it and it should be ready in seconds. + +Image: ``ghcr.io/oss-aspen/sample-collected-data:latest`` + +Quick start with 8Knot +---------------------- + +1. In your 8Knot checkout, point 8Knot at the local database by setting these values in your ``.env``: + +.. code:: shell + + AUGUR_HOST=sample-collected-data + AUGUR_PORT=5432 + AUGUR_DATABASE=sample_collected_data + AUGUR_USERNAME=sample_user + AUGUR_PASSWORD=sample_password + AUGUR_SCHEMA=data,augur_data + +2. Start the stack from the top level of the 8Knot repository: + +.. code:: shell + + podman compose up --build + +8Knot is at http://localhost:8080 and reads from the sample database. The +``sample-collected-data`` service pulls the image and starts instantly (the data +is baked in, so there is no import step). + +Connecting directly (psql, DBeaver, notebooks) +---------------------------------------------- + +The database is also exposed on **host port 5433** (mapped from the container's +5432, so it won't clash with a local PostgreSQL): + +======== ========================= +Setting Value +======== ========================= +Host ``localhost`` +Port ``5433`` +Database ``sample_collected_data`` +User ``sample_user`` +Password ``sample_password`` +======== ========================= + +.. code:: shell + + psql -h localhost -p 5433 -U sample_user -d sample_collected_data + +Tables live in the ``data`` schema (the CollectOSS schema name), so qualify +queries — for example ``data.repo``, ``data.commits``, ``data.pull_requests``. + +Notes +----- + +- **Self-contained** — no CollectOSS credentials, API keys, or dump files required. +- **Data only** — the image contains just the ``data`` schema. The operations + schema (user accounts, tokens, API keys) is deliberately **not** included. +- **Sample, not live** — the data is a fixed snapshot for local development and + demos, not a continuously updated instance. diff --git a/docs/source/getting-started/toc.rst b/docs/source/getting-started/toc.rst index ac71ead49..58a41a5e0 100644 --- a/docs/source/getting-started/toc.rst +++ b/docs/source/getting-started/toc.rst @@ -25,5 +25,6 @@ Happy hacking! :maxdepth: 1 database + sample-database collecting-data command-line-interface/toc From 03caa0ac82e62417b334c242c40b5458161a0100 Mon Sep 17 00:00:00 2001 From: Caio Fonseca <141309898+EngCaioFonseca@users.noreply.github.com> Date: Wed, 15 Jul 2026 21:14:07 +0100 Subject: [PATCH 2/4] Apply suggestion from @MoralCode Co-authored-by: Adrian Edwards <17362949+MoralCode@users.noreply.github.com> Signed-off-by: Caio Fonseca <141309898+EngCaioFonseca@users.noreply.github.com> --- docs/source/getting-started/sample-database.rst | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/source/getting-started/sample-database.rst b/docs/source/getting-started/sample-database.rst index fbeb3f581..0c3c3edfb 100644 --- a/docs/source/getting-started/sample-database.rst +++ b/docs/source/getting-started/sample-database.rst @@ -1,12 +1,7 @@ Sample Database =============== -A ready-to-use PostgreSQL database, pre-loaded with real project data collected by CollectOSS, -so you can run `8Knot `_ — or explore the data from a -notebook — **locally, without access to a remote CollectOSS instance**. - -It ships as a published container image, so there is nothing to build and no data -file to supply. ``docker compose up`` pulls it and it should be ready in seconds. +We have a ready-to-use PostgreSQL database that acts as a structurally-correct sample dataset. This is a postgres container image pre-loaded with data collected by CollectOSS that can be used to help you get started quickly with your downstream project that relies on CollectOSS data, whether thats running `8Knot `_, using jupyter notebooks for research, or building your own dashboard. Image: ``ghcr.io/oss-aspen/sample-collected-data:latest`` From 1dc3d75b96e0fb4b7b0e312ee258147a904d8659 Mon Sep 17 00:00:00 2001 From: Caio Fonseca Date: Wed, 15 Jul 2026 21:16:13 +0100 Subject: [PATCH 3/4] removing notes from readme --- docs/source/getting-started/sample-database.rst | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/source/getting-started/sample-database.rst b/docs/source/getting-started/sample-database.rst index 0c3c3edfb..8564b791d 100644 --- a/docs/source/getting-started/sample-database.rst +++ b/docs/source/getting-started/sample-database.rst @@ -52,11 +52,4 @@ Password ``sample_password`` Tables live in the ``data`` schema (the CollectOSS schema name), so qualify queries — for example ``data.repo``, ``data.commits``, ``data.pull_requests``. -Notes ------ - -- **Self-contained** — no CollectOSS credentials, API keys, or dump files required. -- **Data only** — the image contains just the ``data`` schema. The operations - schema (user accounts, tokens, API keys) is deliberately **not** included. -- **Sample, not live** — the data is a fixed snapshot for local development and - demos, not a continuously updated instance. + From 31dcd27997d99c7f70eaa8a77c546ec31f981ed5 Mon Sep 17 00:00:00 2001 From: Caio Fonseca Date: Wed, 15 Jul 2026 21:25:27 +0100 Subject: [PATCH 4/4] removing bits of info related to 8Knot to be able to transfer it to 8knot docs --- .../getting-started/sample-database.rst | 23 ------------------- 1 file changed, 23 deletions(-) diff --git a/docs/source/getting-started/sample-database.rst b/docs/source/getting-started/sample-database.rst index 8564b791d..b1e50ae6f 100644 --- a/docs/source/getting-started/sample-database.rst +++ b/docs/source/getting-started/sample-database.rst @@ -5,29 +5,6 @@ We have a ready-to-use PostgreSQL database that acts as a structurally-correct s Image: ``ghcr.io/oss-aspen/sample-collected-data:latest`` -Quick start with 8Knot ----------------------- - -1. In your 8Knot checkout, point 8Knot at the local database by setting these values in your ``.env``: - -.. code:: shell - - AUGUR_HOST=sample-collected-data - AUGUR_PORT=5432 - AUGUR_DATABASE=sample_collected_data - AUGUR_USERNAME=sample_user - AUGUR_PASSWORD=sample_password - AUGUR_SCHEMA=data,augur_data - -2. Start the stack from the top level of the 8Knot repository: - -.. code:: shell - - podman compose up --build - -8Knot is at http://localhost:8080 and reads from the sample database. The -``sample-collected-data`` service pulls the image and starts instantly (the data -is baked in, so there is no import step). Connecting directly (psql, DBeaver, notebooks) ----------------------------------------------