Typical Container Boot & Connection Error (Python / FastAPI + Celery)
When depends_on lacks condition: service_healthy or internal service hostnames are misconfigured in .env, container logs typically surface this error during startup:
sqlalchemy.exc.OperationalError: (psycopg.OperationalError) connection failed: Connection refused — Is the server running on host "postgres" (172.19.0.2) and accepting TCP/IP connections on port 5432?
Container Boot Ordering, Bridge DNS & Persistence for Python / FastAPI + Celery
Combining Python FastAPI (Uvicorn) with PostgreSQL 16, Redis 7, and a Celery background worker is the standard production blueprint for async AI pipelines, document processing, and webhook-driven Python SaaS backends. Because both the FastAPI web process and Celery workers share the same Python codebase, SQLAlchemy models, and Alembic migrations, building one Docker image and overriding only the command: in the worker service keeps builds fast and dependencies identical.
Without explicit Compose healthchecks, FastAPI's lifespan startup hooks (such as creating SQLAlchemy async connection pools or running Alembic migrations) and Celery's Redis broker handshake routinely outrace PostgreSQL 16's initial database creation. The result is an immediate OperationalError or Redis ConnectionError on cold boots, followed by noisy CrashLoop restarts in container logs.
Using PostgreSQL's built-in pg_isready -U app -d app_db probe and Redis's redis-cli ping probe inside Docker Compose healthchecks guarantees deterministic boot ordering. Neither postgres:16-alpine nor redis:7-alpine ships with curl, so calling the native client binaries directly eliminates false unhealthy flags while verifying genuine protocol readiness.
Inside both the FastAPI and Celery containers, always assemble SQLAlchemy's DATABASE_URL and Celery's CELERY_BROKER_URL using Docker Compose service names (postgres:5432 and redis:6379) rather than localhost. Isolating PostgreSQL and Redis on app_network via expose: also protects your data tier from accidental public port binding on cloud VPS deployments.
Before pushing to production, validate your merged YAML with docker compose config so escaped variables (such as $${POSTGRES_USER}) and .env credentials interpolate accurately, and enable Redis appendonly yes on a named redis_data volume so queued Celery tasks survive unexpected container restarts.
In production FastAPI and Celery deployments, keep Uvicorn worker counts and Celery concurrency aligned with available container CPU cores and PostgreSQL max_connections so bursts of async tasks never exhaust your database pool. Combining docker compose logs -f api worker with pg_isready and redis-cli ping healthchecks ensures rapid visibility into cold-boot timing, Alembic schema upgrades, and queue backlog health.
Step-by-Step Python / FastAPI + Celery Docker Compose Setup Guide
Follow each step below to pair the generated Compose file with accurate container DNS variables, safe database migrations, and zero-downtime restarts.
1Configure Async SQLAlchemy & Celery URLs Using Compose Service Names
.envPoint SQLAlchemy (asyncpg or psycopg3) to host "postgres" and Celery's broker and result backend to host "redis" over the shared Docker bridge network.
.envdotenvDB_DATABASE=app_db DB_USERNAME=app DB_PASSWORD=change_me_strong DATABASE_URL=postgresql+asyncpg://app:change_me_strong@postgres:5432/app_db CELERY_BROKER_URL=redis://redis:6379/0 CELERY_RESULT_BACKEND=redis://redis:6379/12Configure Celery Startup Broker Retries Alongside service_healthy
app/worker.pySet broker_connection_retry_on_startup = True in Celery 5.3+ so workers also reconnect gracefully if Redis restarts independently during maintenance.
app/worker.pypythonimport os from celery import Celery celery_app = Celery( "fastapi_worker", broker=os.environ["CELERY_BROKER_URL"], backend=os.environ["CELERY_RESULT_BACKEND"], ) celery_app.conf.broker_connection_retry_on_startup = True celery_app.conf.task_acks_late = True3Run Alembic Database Migrations Cleanly Before Serving Traffic
terminalBring up PostgreSQL and Redis first (waiting for healthy probes), run Alembic once as an ephemeral command, and verify all containers report healthy/running.
terminalbashdocker compose up -d --build docker compose exec api alembic upgrade head docker compose ps4Monitor FastAPI and Celery Worker Logs Together
terminalTail both containers simultaneously to verify FastAPI enqueues tasks and Celery acknowledges them over Redis without DNS or serialization failures.
terminalbashdocker compose logs -f api worker
Common Python / FastAPI + Celery Docker Compose Pitfalls
Avoid these three container orchestration mistakes before deploying your Compose stack onto staging or production servers.
Using pg_isready Without -d and -U Flags Passing Prematurely
Calling bare pg_isready defaults to checking Unix socket / root user and can return exit code 0 during PostgreSQL's temporary initdb phase before POSTGRES_DB is ready for TCP connections. Always specify -U $${POSTGRES_USER} -d $${POSTGRES_DB}.
Running Alembic Migrations Inside Every FastAPI Uvicorn Worker
If your Dockerfile CMD runs alembic upgrade head and you scale to multiple API containers or workers, concurrent migrations collide on alembic_version table locks. Run migrations as a single one-off docker compose exec or dedicated migration job.
Celery Dropping Queued Tasks on Redis Restart Without AOF Persistence
Default Redis containers only snapshot memory periodically. Passing command: redis-server --appendonly yes mounted on a named redis_data volume ensures queued Celery jobs persist cleanly across container restarts.
Pair Your Docker Compose Stack With .env Linting, Nginx TLS & CORS Checks
Validate your .env file for unescaped $$ interpolation or leaked secrets, configure Nginx DNS resolution, and verify cross-origin headers:
Validate Python FastAPI and pydantic-settings .env files in your browser. Fix pydantic_core.ValidationError, nested __ delimiters, unquoted #, and DEBUG leaks.
Build a hardened Nginx reverse proxy config for Python FastAPI and Uvicorn/Gunicorn on port 8000 with --proxy-headers, SSL, WebSockets, and long timeouts.
Fix CORS preflight failures between Python FastAPI (Uvicorn) and Next.js on port 3000. Configure CORSMiddleware order, trailing redirects, and credentials.
Frequently Asked Questions
- Why does FastAPI say "could not translate host name postgres" in Docker Compose?
- That psycopg error means your FastAPI container and Postgres container are not attached to the same user-defined Docker bridge network, or the service name in docker-compose.yml (for example "db") does not match the hostname in DATABASE_URL ("postgres").
- Should Celery run as root inside the Python Docker container?
- No. Celery prints a security warning when running as root. Create a non-root user (such as appuser) in your Dockerfile and drop privileges with USER appuser so both FastAPI and Celery execute safely.
- How do I inspect PostgreSQL from my laptop if ports are kept internal with expose:?
- Use an SSH tunnel (ssh -L 5432:127.0.0.1:5432 user@vps) paired with 127.0.0.1:5432:5432 in Compose, or run psql interactively via docker compose exec postgres psql -U app -d app_db without ever opening port 5432 publicly.
- Can I swap Redis for RabbitMQ as the Celery broker in this Compose generator?
- Yes. Select RabbitMQ in the Cache / Message Broker dropdown above and the engine automatically generates rabbitmq:3.13-management-alpine with rabbitmq-diagnostics -q ping healthchecks and AMQP_URL variables.
Related Docker Compose Stack Guides
Browse all 10 Compose stacks →Docker Compose FastAPI + PostgreSQL + Nginx VPS Production Stack Guide
Deploy FastAPI, PostgreSQL 16, and Nginx on a Linux VPS with Docker Compose using pg_isready healthchecks, 127.0.0.1 firewall safety, and zero-downtime reloads.
Docker Compose Node.js + BullMQ Worker + Redis 7 + PostgreSQL 16 Guide
Generate a Docker Compose config for Node.js APIs, BullMQ background workers, Redis 7, and PostgreSQL 16 with native healthchecks and noeviction Redis safety.
Docker Compose Laravel + MySQL 8 + Redis Queue Stack & Healthcheck Guide
Generate a production Docker Compose file for Laravel 11/12 with MySQL 8, Redis 7, and queue:work using mysqladmin and redis-cli service_healthy probes.
Docker Compose Next.js Standalone + Prisma + PostgreSQL 16 Stack Guide
Generate a Docker Compose config for Next.js App Router standalone output with Prisma ORM and PostgreSQL 16 using pg_isready healthchecks and service DNS.