Operations

Routine checks

docker compose ps
docker compose logs --tail=100 api
docker compose logs --tail=100 worker
docker compose logs --tail=100 db
curl --fail http://127.0.0.1:8000/api/health

Adapt the host URL if the API is bound differently. Health reports API version and maintenance state; it does not test every upstream or prove the worker is running. Check Data sync for latest successful runs and failures.

Monitor available disk space, database/image growth, memory pressure, API response time and backup completion. The repository does not ship a general Prometheus metrics endpoint or a complete external monitoring stack in this revision. HTTP health checks and log collection can be integrated with the operator's monitoring system.

Restart versus recreate

Use docker compose restart api for a process restart with the current container environment. After editing .env or Compose settings, use docker compose up -d api worker so containers are recreated when configuration differs.

Do not print or publish docker compose config output without review: interpolation can include secrets. Inspect it locally when diagnosing merged ports, environment values and mounts.

Worker health

A healthy web UI with old data often indicates a stopped/blocked worker. UI jobs remain queued without it. Inspect worker logs, upstream failures, quotas and database connectivity. Automatic jobs are sequential in the reviewed loop, so a long game import can delay later work.

Avoid starting multiple ad-hoc sync commands to compensate for a long import; they can conflict with existing work.

Logs and incident reports

Capture the failing component, version, time zone, action and HTTP status. Include relevant job IDs and the last useful log lines. Remove credentials, tokens, cookies, authorization headers and personal collection details before sharing publicly.

Backend unexpected exceptions return a generic “Internal server error”; the traceback is logged server-side. A browser toast alone cannot identify the underlying exception.

Capacity and traffic

Select only needed automatic catalogs/languages when resource-constrained. Full Magic bulk data and individual Asian-card fetches can dominate initialization. Keep source caches to avoid rebuilding them under quotas. Large image caches consume disk independently of PostgreSQL.

There is no measured sizing guarantee in this documentation. Benchmark the selected catalogs on the target host before inviting additional users.

Scheduled maintenance

Take a backup, record image tags/source SHA, notify your users outside the application as appropriate, stop mutation-producing services for a consistent data copy when needed, perform the change, then check health, sign-in, a card page, the collection and a small targeted sync.

Administrator recovery

Enable local login if necessary, recreate the API, then use the interactive command:

docker compose exec api zukan create-admin recovery-admin

A reset of an existing username changes its password, role/disabled state and sessions. It does not recover a deleted collection. See Backup and restore.

Implementation references

• docker-compose.yml
• backend/app/worker.py
• backend/app/main.py