Troubleshooting

Common installation and runtime issues, in roughly the order people hit them.

Install

docker compose v2 not found

You have legacy docker-compose (Python) but not the v2 plugin. Upgrade Docker Desktop (macOS/Windows) or install the docker-compose-plugin package (Linux). Verify with:

docker compose version

port 80 / 443 is in use

Something else is binding Caddy's ports. Either stop that service (sudo ss -lnpt | grep :80) or set CADDY_HTTP_PORT / CADDY_HTTPS_PORT in .env and rerun docker compose up -d.

less than 4 GB RAM detected

Logto, Bitcart and Postgres together comfortably need 3–4 GB. On smaller VPS, expect random OOM kills. Upgrade the instance or accept the warning.

Installer exited halfway

Re-run it. The script is idempotent: it skips clone if the dir exists, skips .env write if a .env is present, and docker compose up -d is safe to call repeatedly.

Runtime

A service is unhealthy in docker compose ps

docker compose logs <service> --tail 200

Common causes:

• Postgres: wrong POSTGRES_PASSWORD — wipe the volume only if you have a backup (docker compose down && docker volume rm openbitum_postgres_data).
• Logto: DB_URL doesn't resolve. Check that the logto database exists (created by infrastructure/bitcart-config/init-databases.sh on first boot).
• Bitcart: BTC daemon is downloading the chain on first boot; the readiness probe may take 30+ minutes on a fresh node. docker compose logs bitcart-btc shows progress.

Glue /healthz returns 503

The glue can't reach Postgres or Redis. Verify both report healthy and that DATABASE_URL and REDIS_URL in .env use the docker service names (postgres, redis), not localhost.

Webhook signature mismatch

Bitcart and the glue must share the same GLUE_WEBHOOK_SECRET. The installer renders it once into .env; rotating it requires updating Bitcart's webhook config too.

Caddy can't get a certificate

Let's Encrypt needs your domain to resolve to the host's public IP and ports 80/443 open from the public internet. For local dev, set CADDY_TLS_MODE=internal (already done by docker-compose.dev.yml) and trust Caddy's local CA in your browser.

Entitlement stuck in pending

Open the order in the dashboard and click Retry. If it keeps failing:

• GitHub: PAT scope must include repo (private) or public_repo (public).
• Discord: bot must be a guild member with MANAGE_ROLES.
• File: MinIO bucket must exist and the S3 key must resolve.

Resets

Full reset (destroys all data, leaves volumes):

docker compose down

Nuclear reset (destroys data too — only for dev):

docker compose down -v