The platform runs as four containers and a small set of bind-mounted source trees. Day-2 operations consist of three loops: the API loop, the sync loop, and the dbt loop. This page is a working reference, not a tour.

The container loop

docker compose up -d --build           # start everything (or rebuild after deps change)
docker compose logs -f skygraph-api    # follow API logs
docker compose restart skygraph-api    # after Python changes
docker compose down                    # stop everything

The API and sync services bind their source trees as volumes. Uvicorn runs with --reload, so most Python edits are picked up without a restart. A restart is required after dependency changes (requirements.txt) — those need a rebuild.

The sync loop

The sync service runs the Hermes connectors. It uses Python schedule for per-table intervals defined in sync/config/tables.yml. Edits to that file require a restart of the sync service to take effect.

docker compose restart skygraph-sync                                    # apply table-config edits
docker exec -it skygraph-sync python -c "from main import main; main()" # one-off sync iteration

Watermarks are stored per-table in ClickHouse sync_state. Read with FINAL — the lake's raw tables are ReplacingMergeTree, so a FINAL clause is required on every query that needs deduplicated rows.

The dbt loop

dbt models live under dbt/. The profile is committed alongside the project and points at the local ClickHouse on localhost:8123.

cd dbt
dbt run --profiles-dir .                          # all models
dbt run --select staging.stg_invoices             # one model
dbt test --profiles-dir .                         # data tests

Adding a new staging or mart model is a dbt change only; the ontology references the model by name and reloads.

The ontology hot-reload

The ontology is loaded into the API at startup. The reload endpoint refreshes OBJECT_TYPES and LINK_TYPES without restarting the container:

curl -X POST http://localhost:8100/api/v1/ontology/reload

YAML edits under ontology/ (one file per object type, one per link type) are committed to the repository and applied with the reload above.

Snapshots

Eidolon, the digital-twin module, takes snapshots through the API. The job can also be invoked directly inside the API container:

docker exec -it skygraph-api python snapshot_job.py

After UI changes

The UI is a built artifact baked into the skygraph-ui image. After a merge, rebuild and redeploy:

cd ui && npm run build && cd .. && docker compose up -d --build skygraph-ui

For active development, npm run dev is faster (Vite on :5173, proxies /api/* to :8100).

Logs and health

docker compose logs -f skygraph-api          # the API
docker compose logs -f skygraph-sync         # the sync daemon
curl http://localhost:8100/health            # API liveness
curl http://localhost:8123/ping              # ClickHouse liveness

structlog is the API's logging library. For incident triage, follow the API log and the sync log together in two panes.

Where to read next

The platform's own CLAUDE.md for the contributor's view of the same loop.
Deployment for what is supported today, and what is on the roadmap.

Operations