Quickstart

1. Prepare an isolated source copy#

You need the submitted source folder, Docker with Compose v2, Python 3 for configuration, free Docker disk space, internet for images/packages, and free port 8501. Once you have the source, this workflow does not need the archived dump or university data access.

cd cita_traffic_platform
export COMPOSE_PROJECT_NAME=cita-docs-review
python3 - <<'PY'
from pathlib import Path
import secrets
path = Path('.env')
if path.exists():
    raise SystemExit('Existing .env: use a fresh source copy or review it first.')
password = secrets.token_hex(20)
path.write_text(
    'POSTGRES_DB=cita\nPOSTGRES_USER=cita\n'
    + 'POSTGRES_PASSWORD=' + password + '\n'
    + 'DATABASE_URL=postgresql://cita:' + password + '@postgres:5432/cita\n'
)
PY
docker compose config --quiet

Expected: The configuration check exits successfully without printing resolved credentials. The helper creates matching credentials for the internal hostname postgres; the project name separates review containers and volumes from other installations.

2. Build and migrate#

docker compose build
docker compose up -d --wait postgres
docker compose run --rm collector python -m database.migrate
docker compose run --rm collector python -m database.migrate
docker compose exec -T postgres psql -U cita -d cita -c \
  "SELECT version FROM schema_migrations ORDER BY version;"

Expected: First migration: Applied: 001_lossless_collection.sql. Second: Applied: database already current. The query returns that one migration filename. The base schema initializes compatibility/operational tables; the migration adds snapshots and detailed domain tables.

Local check: images built; these migration outcomes were verified on temporary memory-backed PostgreSQL 17. A normal persistent-volume startup was blocked by local Docker disk exhaustion. See storage diagnostics.

3. Seed and verify the bundled A1 XML#

Download the fixture helper as seed-fixture.py beside compose.yaml. It substitutes the HTTP response with the bundled XML, then runs the actual archive, registration, parser, and database code twice. No CITA request is made.

docker compose run --rm -T \
  -v "$PWD/xml-files:/fixtures:ro" \
  -v "$PWD/seed-fixture.py:/app/seed-fixture.py:ro" \
  collector python /app/seed-fixture.py
docker compose exec -T postgres psql -U cita -d cita -c \
  "SELECT count(*) FROM measurements WHERE road='A1';"
docker compose exec -T postgres psql -U cita -d cita -c \
  "SELECT outcome,count(*) FROM feed_fetch_observations GROUP BY outcome ORDER BY outcome;"

Expected: On a new database: PASS, 37 A1 measurement rows, one archived fetch, one duplicate fetch, and one shared raw snapshot. This is a historical fixture, not live traffic or the evaluation sample. The helper intentionally asserts a fresh import; on an already-seeded database inspect the SQL instead of repeating that assertion.

4. Open the dashboard#

docker compose up -d --wait dashboard
curl -fsS http://127.0.0.1:8501/_stcore/health
docker compose ps

Expected: Health returns ok. Open http://127.0.0.1:8501/, select A1, and use History with a range containing the fixture (for example, Entire dataset). It can be stale in live views. No collector scheduler has been started.

5. Optionally collect current feeds#

docker compose run --rm collector python -m collector.collector
# Inspect the summary before enabling continuous collection.
docker compose up -d collector
docker compose logs --tail=60 collector

Expected: The one-pass summary lists archived snapshots, duplicates, warnings, and failed feeds. Exit status alone does not prove all feeds succeeded: inspect the failed count and feed metadata. The scheduler uses individual feed intervals, not a single global five-minute pass.

6. Stop the review stack#

docker compose down

Expected: The review project’s containers and network stop. Named volumes remain; do not add --volumes if you need the data. Memory-backed storage, if used as a workaround, disappears when its container stops.