Add sample database page to getting started docs#444
Open
EngCaioFonseca wants to merge 4 commits into
Open
Conversation
MoralCode
requested changes
Jul 15, 2026
MoralCode
left a comment
MoralCode
left a comment
Contributor
There was a problem hiding this comment.
added some comments.
in addition to this feedback this cant merge until the commits are signed off per CHAOSS/LF policy. See CONTRIBUTING.md if you'd like details on this process
Comment on lines
+13
to
+36
| 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). | ||
|
|
Contributor
There was a problem hiding this comment.
I think it may make sense for this piece to be moved to the 8Knot readme where we can then have collectOSS link to 8knot (for 8knot specific instructions) and 8knot can link to collectOSS for general info about this database/data structure
that way the information is maintained as close to the thing it talks about as possible
Contributor
There was a problem hiding this comment.
id like to maybe replace this with the contents of the sample docker compose file
Comment on lines
+60
to
+67
| 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. |
Contributor
There was a problem hiding this comment.
This section seems unnecessary
Co-authored-by: Adrian Edwards <17362949+MoralCode@users.noreply.github.com> Signed-off-by: Caio Fonseca <141309898+EngCaioFonseca@users.noreply.github.com>
MoralCode
requested changes
Jul 16, 2026
| 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 <https://github.com/oss-aspen/8Knot>`_, using jupyter notebooks for research, or building your own dashboard. | ||
|
|
||
| Image: ``ghcr.io/oss-aspen/sample-collected-data:latest`` | ||
|
|
Contributor
There was a problem hiding this comment.
Suggested change
| Using the image | |
| --------------- | |
| The easiest way to use the image is to create a `docker-compose.yml` file in a new directory with the following contents: | |
| ```yaml | |
| services: | |
| sample-collected-data: | |
| image: ghcr.io/oss-aspen/sample-collected-data:latest | |
| ports: | |
| - "5433:5432" # exposed on 5433 to avoid clashing with a local postgres | |
| environment: | |
| POSTGRES_DB: sample_collected_data | |
| POSTGRES_USER: sample_user | |
| POSTGRES_PASSWORD: sample_password | |
| healthcheck: | |
| test: ["CMD-SHELL", "pg_isready -U sample_user -d sample_collected_data"] | |
| interval: 5s | |
| timeout: 5s | |
| retries: 10 | |
| ``` | |
| Once this file exists, running `docker compose up` from this directory will bring the database up and allow you to connect as explained in the next section. |
| Connecting directly (psql, DBeaver, notebooks) | ||
| ---------------------------------------------- | ||
|
|
||
| The database is also exposed on **host port 5433** (mapped from the container's |
Contributor
There was a problem hiding this comment.
Suggested change
| The database is also exposed on **host port 5433** (mapped from the container's | |
| If you are using the compose file above, the database will be exposed on port 5433 on your machine (mapped from the container's |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The PR introduces the readme doc explaining how the users would be able to use the minim viable DB we made available in CollectOSS.
This PR fixes #
Notes for Reviewers
Signed commits
Generative AI disclosure
Please select one option:
If AI tools were used, please provide details below:
- What tools were used? Claude
- How were these tools used? Draft.
- Did you review these outputs before submitting this PR? Yes.