hoopscout/docs/runtime-consistency-checklist.md

Runtime Consistency Checklist (v2)

Use this checklist when runtime/docs changes are made.

Compose and Runtime

• docker-compose.yml contains only v2 default runtime services:
  • web, nginx, postgres
  • optional scheduler profile service
• docker-compose.dev.yml is mutable (source bind mounts allowed for dev only).
• docker-compose.release.yml is settings-focused and keeps release runtime immutable.

Image/Registry Strategy

• web image: registry.younerd.org/hoopscout/web:${APP_IMAGE_TAG:-latest}
• nginx image: registry.younerd.org/hoopscout/nginx:${NGINX_IMAGE_TAG:-latest}
• optional scheduler image: registry.younerd.org/hoopscout/scheduler:${APP_IMAGE_TAG:-latest}

Entrypoints

• entrypoint.sh:
  • waits for PostgreSQL
  • creates snapshot directories
  • optionally runs migrate and collectstatic when booting gunicorn
• scripts/scheduler.sh:
  • runs run_daily_orchestration loop
  • idle-sleeps when SCHEDULER_ENABLED=0

Snapshot Lifecycle

1. Extractor writes snapshots to incoming.
2. import_snapshots validates + upserts into PostgreSQL.
3. Success => file moved to archive.
4. Failure => file moved to failed.

Source Identity Rule

Raw IDs are not global. Imported identities are namespaced by source:

• Competition: (source_name, source_uid)
• Team: (source_name, source_uid)
• Player: (source_name, source_uid)

Legacy Isolation

• LEGACY_PROVIDER_STACK_ENABLED=0 by default.
• With default setting:
  • apps.providers is not installed
  • /providers/ routes are not mounted
  • legacy provider settings are not required

Verification Commands

docker compose -f docker-compose.yml -f docker-compose.release.yml config
./scripts/verify_release_topology.sh
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm web sh -lc "export PYTHONUSERBASE=/tmp/pyuser && python -m pip install --user -r requirements/dev.txt && python -m pytest -q"