Troubleshooting
Health Checks
All services include health checks:
| Service | Check | Interval |
|---|---|---|
| PostgreSQL | pg_isready -U orcher -d orcher | 5s |
| PgBouncer | pg_isready -h localhost -p 5432 -U orcher | 5s |
| Redis | redis-cli ping | 5s |
| Orchestrator | curl -f http://localhost:8080/health/live | 30s |
Volumes
Docker Compose creates named volumes for data persistence:
| Volume | Mount Point | Purpose |
|---|---|---|
orcher-postgres-data | /var/lib/postgresql/data | Workflow state, journal, task executions |
orcher-redis-data | /data | Redis AOF persistence |
orcher-prometheus-data | /prometheus | Metrics history (30-day retention) |
orcher-grafana-data | /var/lib/grafana | Dashboard state |
To reset all data:
1cd docker2docker compose down -vTroubleshooting
PgBouncer Connection Refused
PgBouncer waits for PostgreSQL to be healthy before starting. If connections fail:
1# Check service health2docker compose ps34# Check PgBouncer logs5docker compose logs pgbouncer67# Test direct PostgreSQL connection8psql postgresql://orcher:orcher@localhost:5432/orcher -c "SELECT 1"910# Test PgBouncer connection11psql postgresql://orcher:orcher@localhost:6432/orcher -c "SELECT 1"Orchestrator Can't Connect to Database
When running the orchestrator on the host, use localhost ports. When running in a container on orcher-network, use container names:
| Context | PostgreSQL | PgBouncer | Redis |
|---|---|---|---|
| Host | localhost:5432 | localhost:6432 | localhost:6379 |
| Container (orcher-network) | orcher-postgres:5432 | orcher-pgbouncer:5432 | orcher-redis:6379 |
Redis Optional — Fallback to PostgreSQL
If Redis is unavailable, the orchestrator automatically falls back to PostgreSQL-based polling. You'll see the orcher_postgres_fallback_total metric incrementing. This works correctly but with higher dispatch latency: workers find work at their next poll.
Next Steps
- Docker Overview — Quick start and Docker Compose services
- Configuration — Environment variables, CLI flags, and TOML configuration
- Production — Production Dockerfile and full production stack
- Storage — PostgreSQL schema and migration details
- Metrics — Prometheus metrics reference