feat: Centralised configuration utility

.env.example

@@ -0,0 +1,5 @@
+# Copy to .env and edit to override defaults. All vars below are optional;
+# docker-compose uses the shown defaults when .env is absent.
+OMOP_CDM_DB_USER=omop
+OMOP_CDM_DB_PASSWORD=omop
+OMOP_CDM_DB_NAME=omop_cdm

Dockerfile

@@ -0,0 +1,3 @@
+FROM python:3.12-slim
+RUN pip install --no-cache-dir ".[postgres,emb,pgvector,faiss-cpu]"
+WORKDIR /workspace

README.md

@@ -114,3 +114,41 @@ omop_graph/
 ├── api.py          # stable public API surface
 └── db/             # session helpers
 ```
+
+---
+
+## Configuration
+
+omop-graph reads database connection settings from
+[oa-configurator](https://github.com/AustralianCancerDataNetwork/oa-configurator).
+It requires the CDM database configured by omop-alchemy.
+
+Run once after installation:
+
+```bash
+omop-config init
+omop-config configure omop_alchemy
+omop-config configure omop_graph
+```
+
+See [Configuration](docs/getting-started/configuration.md) for full details.
+
+---
+
+## Docker Compose
+
+The included `docker-compose.yaml` provides a PostgreSQL CDM database and a Python
+container with all optional backends pre-installed (`[postgres,emb,pgvector,faiss-cpu]`).
+Default credentials work out of the box:
+
+```bash
+docker compose up
+```
+
+The `python-graph` service runs `omop-config configure` at startup. To override
+credentials:
+
+```bash
+cp .env.example .env
+docker compose up
+```

docker-compose.yaml

@@ -2,23 +2,62 @@ services:
   omop-cdm-db:
     image: postgres:16-alpine
     restart: always
-    env_file: .env
     environment:
-      - POSTGRES_USER=${OMOP_CDM_DB_USER:-omop}
-      - POSTGRES_PASSWORD=${OMOP_CDM_DB_PASSWORD:-omop}
-      - POSTGRES_DB=${OMOP_CDM_DB_NAME:-omop}
-      - PGDATA=/var/lib/postgresql/data/pgdata
+      POSTGRES_USER: ${OMOP_CDM_DB_USER:-omop}
+      POSTGRES_PASSWORD: ${OMOP_CDM_DB_PASSWORD:-omop}
+      POSTGRES_DB: ${OMOP_CDM_DB_NAME:-omop_cdm}
+      PGDATA: /var/lib/postgresql/data/pgdata
     volumes:
       - db_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
     networks:
       - omop-net
+    command: >
+      postgres
+      -c shared_buffers=512MB
+      -c effective_cache_size=1GB
+      -c work_mem=128MB
+      -c maintenance_work_mem=512MB
+      -c max_wal_size=4GB
+      -c min_wal_size=512MB
+      -c wal_buffers=16MB
+      -c wal_compression=zstd
+      -c full_page_writes=off
+      -c checkpoint_timeout=30min
+      -c synchronous_commit=off
+      -c max_parallel_workers_per_gather=2
+      -c max_worker_processes=4
+      -c max_parallel_maintenance_workers=2
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${OMOP_CDM_DB_USER:-omop} -d ${OMOP_CDM_DB_NAME:-omop}"]
+      test: ["CMD-SHELL", "pg_isready -U ${OMOP_CDM_DB_USER:-omop}"]
       interval: 5s
       timeout: 5s
       retries: 5
-    ports:
-      - "5432:5432"
+
+  python-graph:
+    build: .
+    restart: unless-stopped
+    depends_on:
+      omop-cdm-db:
+        condition: service_healthy
+    volumes:
+      - ${HOME}/.config/omop:/root/.config/omop
+    networks:
+      - omop-net
+    command: >
+      bash -c "
+        omop-config configure omop_alchemy
+          --database cdm --dialect postgresql+psycopg
+          --host omop-cdm-db --port 5432
+          --user ${OMOP_CDM_DB_USER:-omop}
+          --password ${OMOP_CDM_DB_PASSWORD:-omop}
+          --database-name ${OMOP_CDM_DB_NAME:-omop_cdm}
+          --cdm-schema omop &&
+        omop-config configure orm_loader &&
+        omop-config configure omop_graph &&
+        sleep infinity
+      "
 
 networks:
   omop-net:

docs/getting-started/configuration.md

@@ -0,0 +1,82 @@
+# Configuration
+
+omop-graph reads all database connection and schema settings from
+[oa-configurator](https://github.com/AustralianCancerDataNetwork/oa-configurator).
+No environment variables are needed for the Python package itself.
+
+## Quick start
+
+omop-graph requires the CDM database configured by omop-alchemy. If you have not
+already done so, configure omop-alchemy first:
+
+```bash
+omop-config init          # creates ~/.config/omop/config.toml if absent
+omop-config configure omop_alchemy
+omop-config configure omop_graph
+```
+
+## What gets configured
+
+omop-graph does not own any database resources. It reads from the `cdm_db` resource
+configured by omop-alchemy and stores any package-specific settings (traversal depth,
+path limits) under `[tools.omop_graph]` in `config.toml`.
+
+## Verify
+
+```bash
+omop-config verify
+```
+
+## Docker Compose
+
+The included `docker-compose.yaml` spins up a PostgreSQL CDM database and a
+`python-graph` container. Default credentials work out of the box:
+
+```bash
+docker compose up
+```
+
+The `python-graph` container runs `omop-config configure` for both `omop_alchemy` and
+`omop_graph` at startup. Your `~/.config/omop/config.toml` on the host is written on
+safe to re-run on subsequent starts: connection flags always apply, and any values already stored in `config.toml` are preserved for fields not explicitly provided.
+
+### Overriding default values
+
+The compose file uses built-in defaults for all database credentials. To use different
+values, create a `.env` file in this directory with any of the following variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `OMOP_CDM_DB_USER` | `omop` | CDM database username |
+| `OMOP_CDM_DB_PASSWORD` | `omop` | CDM database password |
+| `OMOP_CDM_DB_NAME` | `omop_cdm` | CDM database name |
+
+Copy the example and edit as needed:
+
+```bash
+cp .env.example .env
+# edit .env
+docker compose up
+```
+
+The `.env` file is only read by Docker Compose for variable substitution — it is not
+loaded by omop-graph at runtime.
+
+## Multiple instances
+
+omop-graph reads from the `cdm_db` resource owned by omop-alchemy. To point
+it at a second CDM database (e.g. for production), configure omop-alchemy with
+a second resource:
+
+```bash
+omop-config configure omop_alchemy --resource-name cdm_db_prod
+```
+
+Configure automatically prompts you to choose the default at the end of the same
+run — no second invocation needed.
+
+See the [oa-configurator integration guide](https://AustralianCancerDataNetwork.github.io/oa-configurator/integration/#multiple-environments) for the full multi-environment guide.
+
+## Further reading
+
+- [oa-configurator integration guide](https://AustralianCancerDataNetwork.github.io/oa-configurator/integration/) — full config reference, profiles, multi-package setups

docs/usage/cli.md

@@ -2,6 +2,17 @@
 
 The OMOP CDM instantiation tool provides a streamlined way to bootstrap a local OHDSI Common Data Model (CDM) database using Athena vocabulary files and synthetic test data.
 
+!!! note "Verbosity flag placement"
+    The `--verbose` / `-v` flag is a **global option** and must appear **before** the
+    subcommand name, not after it:
+
+    ```
+    omop-graph -v relationship-classification ...   # ✓ correct
+    omop-graph relationship-classification -v ...   # ✗ flag is ignored
+    ```
+
+    Use `-v` for INFO level and `-vv` for DEBUG level.
+
 ---
 
 ## `omop-cdm`

mkdocs.yml

@@ -31,6 +31,7 @@ nav:
   - Home: index.md
   - Getting Started:
       - Installation: usage/installation.md
+      - Configuration: getting-started/configuration.md
       - "CLI Reference": usage/cli.md
       - Testing: usage/testing.md
   - Core Components: