QuantDingerQuantDingerv5.7.1 Docs Docs home
中文 GitHub
View Markdown source

Installation Troubleshooting

Use this guide for first-time Docker and Compose failures. Run commands from the repository root, next to docker-compose.yml.

中文

First checks

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 env-sync postgres redis redis-jobs kafka kafka-init migration backend

Read the first failing dependency, not only the final backend error. The normal startup order is env-sync, the PostgreSQL/Redis/Kafka state services, migration and kafka-init, then the API and workers.

PostgreSQL password is missing

If Compose reports POSTGRES_PASSWORD is required, do not invent a new value for an existing database. For a source checkout, run this from the repository root:

python3 scripts/bootstrap_env.py

For a manually downloaded GHCR deployment, make sure scripts/bootstrap_env.py was downloaded as described in the cloud guide, then run:

python3 scripts/bootstrap_env.py --compose-file docker-compose.ghcr.yml

The bootstrap command never prints secrets. It generates a random password for a new installation, preserves the value already present in .env, and can recover the original value from a legacy DATABASE_URL or a surviving quantdinger-db container. If an existing .env, legacy environment file, or PostgreSQL volume is present and the password cannot be recovered, the command stops instead of generating a replacement. Restore the original POSTGRES_PASSWORD from an .env or server backup. Do not substitute a new password and do not run docker compose down -v.

Only for a verified new deployment where an empty .env was created manually and no PostgreSQL data exists, use --allow-new-database to permit generation. Never use that flag to repair an upgrade.

Image pull fails

Typical errors mention registry-1.docker.io, failed to resolve reference, timeouts, or a missing Docker Desktop HTTPS proxy.

  1. Confirm that the proxy port is listening on the host.
  2. In Docker Desktop, open Settings → Resources → Proxies.
  3. Configure both HTTP and HTTPS with the working HTTP proxy URL.
  4. Apply the change and fully restart Docker Desktop.
  5. Verify with docker info, then retry docker compose pull.

On Windows, a focused connectivity check is:

curl.exe -x http://127.0.0.1:10808 https://registry-1.docker.io/v2/
docker info | findstr /i proxy

An UNAUTHORIZED response from /v2/ means the registry is reachable; the endpoint expects Docker's authentication flow. A timeout or connection failure means the network path is still blocked.

PostgreSQL is unhealthy after an upgrade

If logs say the data directory was initialized by a different PostgreSQL major version, do not repeatedly restart the container. PostgreSQL data directories cannot be reused across major versions without migration.

For disposable local data only:

docker compose down -v
docker compose up -d

down -v permanently deletes Compose volumes, including the local database. Never use it when the data must be retained.

For retained data, start the original PostgreSQL major version and migrate with pg_dump/pg_restore or pg_upgrade. Back up the data before changing the image or volume.

Migration does not complete

docker compose ps migration
docker compose logs --tail=200 migration
docker compose logs --tail=100 postgres

Do not start schema changes concurrently from API workers. The bundled migration service owns schema upgrades; dependent services wait for it to finish successfully.

Backend exits or health check fails

docker compose logs --tail=200 backend
docker compose exec backend curl -f http://localhost:5000/api/health

Check these first:

  • the project-root .env exists and is mounted as /app/.env;
  • upgrades have synchronized missing keys from the latest .env.example;
  • POSTGRES_PASSWORD, SECRET_KEY, and CREDENTIAL_ENCRYPTION_KEY are not missing or placeholder values;
  • all services use the same PostgreSQL and Redis credentials;
  • the migration service has completed.

For administrator or settings-save issues, use Administrator Credentials and Settings Save Troubleshooting.

Safe recovery commands

# Inspect status and recent logs
docker compose ps
docker compose logs --tail=100 backend kafka trading-worker \
  strategy-dispatcher-worker strategy-evaluator-worker scheduler-worker

# Recreate containers while retaining volumes
docker compose up -d --force-recreate

# Stop containers while retaining volumes
docker compose down

Use destructive volume removal only after confirming that a verified backup exists or the local data is intentionally disposable.