Typical Container Boot & Connection Error (PHP / Laravel Octane + Reverb)
When depends_on lacks condition: service_healthy or internal service hostnames are misconfigured in .env, container logs typically surface this error during startup:
SQLSTATE[08006] [7] connection to server at "postgres" (172.20.0.2), port 5432 failed: Connection refused
Container Boot Ordering, Bridge DNS & Persistence for PHP / Laravel Octane + Reverb
Pairing Laravel Octane (FrankenPHP or Swoole on port 8000), PostgreSQL 16, Redis 7, and a dedicated Laravel Reverb WebSocket container (port 8080) inside Docker Compose creates an ultra-low-latency PHP stack; while keeping every process isolated in its own container. Because Octane keeps your Laravel application booted in memory across requests, database connection pooling and startup healthchecks are even more important than in traditional PHP-FPM setups.
If the Octane container boots before PostgreSQL 16 finishes initializing its cluster or before Redis opens port 6379, service providers that resolve database configs or cache stores during boot crash immediately with SQLSTATE[08006] [7] Connection refused. Attaching pg_isready and redis-cli ping healthchecks with condition: service_healthy guarantees that Octane, Reverb, and your queue workers only start once PostgreSQL and Redis are fully ready.
Running Nginx as a lightweight gateway container inside the same Compose stack lets a single HTTPS entrypoint route regular HTTP requests to http://octane:8000 and WebSocket upgrades (/app) to http://reverb:8080 over the internal app_network bridge. Keeping PostgreSQL and Redis unexposed externally with expose: ensures zero accidental public database ports on Linux VPS hosts.
Because Laravel Octane workers persist objects in RAM, remember to run php artisan octane:reload inside the octane container after releasing updated PHP code or configuration changes, while letting Redis drive shared sessions, locks, and Reverb horizontal pub/sub scaling cleanly across containers.
Finally, configure Laravel's .env with DB_HOST=postgres, REDIS_HOST=redis, and REVERB_SERVER_HOST=0.0.0.0 inside the Reverb container so sibling Nginx and Octane containers can reach Reverb over internal Docker DNS without localhost loopback failures.
When operating Laravel Octane, PostgreSQL 16, Redis 7, and Reverb inside Docker Compose, pair container restart policies (unless-stopped) with explicit stop_grace_period settings so long-running queue jobs and WebSocket broadcasts drain gracefully during deploys. Monitoring docker compose ps health states alongside Nginx upstream logs verifies zero dropped connections across both port 8000 (Octane) and port 8080 (Reverb).
Step-by-Step PHP / Laravel Octane + Reverb 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.
1Add a Dedicated Reverb Service Sharing the Built Laravel Image
docker-compose.yml (reverb service snippet)Alongside the generated octane, worker, postgres, redis, and nginx services, add a reverb service executing php artisan reverb:start bound to 0.0.0.0:8080 on app_network.
docker-compose.yml (reverb service snippet)yamlreverb: build: context: . dockerfile: Dockerfile command: php artisan reverb:start --host=0.0.0.0 --port=8080 restart: unless-stopped env_file: - .env expose: - "8080" depends_on: redis: condition: service_healthy networks: - app_network2Configure PostgreSQL, Redis, and Internal Reverb Hostnames in .env
.envUse internal Docker Compose service hostnames for backend-to-backend broadcasts (REVERB_HOST=reverb for server pushes or public WSS domain for browser Echo clients).
.envdotenvDB_CONNECTION=pgsql DB_HOST=postgres DB_PORT=5432 DB_DATABASE=app_db DB_USERNAME=app DB_PASSWORD=change_me_strong BROADCAST_CONNECTION=reverb CACHE_STORE=redis QUEUE_CONNECTION=redis REDIS_HOST=redis REVERB_SERVER_HOST=0.0.0.0 REVERB_SERVER_PORT=8080 REVERB_SCALING_ENABLED=true3Proxy Octane (8000) and Reverb (8080) Through the Nginx Container
nginx/default.confUse Docker's embedded resolver 127.0.0.11 inside the Nginx container so restarting Octane or Reverb never causes stale-IP 502 Bad Gateway errors.
nginx/default.confnginxlocation / { resolver 127.0.0.11 valid=30s ipv6=off; set $octane_upstream http://octane:8000; proxy_pass $octane_upstream; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; } location /app { resolver 127.0.0.11 valid=30s ipv6=off; set $reverb_upstream http://reverb:8080; proxy_pass $reverb_upstream; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 3600s; }4Boot the Stack and Run PostgreSQL Migrations Safely
terminalStart all containers, verify postgres and redis are healthy, and execute Laravel migrations once on the octane container.
terminalbashdocker compose up -d --build docker compose exec octane php artisan migrate --force docker compose ps
Common PHP / Laravel Octane + Reverb Docker Compose Pitfalls
Avoid these three container orchestration mistakes before deploying your Compose stack onto staging or production servers.
Binding Octane or Reverb to 127.0.0.1 Inside Their Own Containers
Running php artisan octane:start --host=127.0.0.1 inside Docker makes Octane unreachable from the Nginx container. Inside containers, always bind --host=0.0.0.0 and restrict external access via Compose expose: or 127.0.0.1 port publishing.
Stale PostgreSQL Connections Inside Long-Lived Octane Workers
If PostgreSQL restarts while Octane stays alive, cached PDO handles can throw "server closed the connection unexpectedly." Laravel Octane automatically flushes connections cleanly when configured with standard database config and listeners.
Forgetting TrustProxies in Laravel Behind the Nginx Container
Because Nginx connects over the Docker bridge subnet (e.g., 172.x.0.x), Laravel ignores X-Forwarded-Proto unless bootstrap/app.php trusts the Docker bridge proxy.
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 Laravel Sanctum SPA .env settings locally. Fix 419 CSRF mismatch and 401 cookie failures by aligning APP_URL, FRONTEND_URL, and SESSION_DOMAIN.
Configure Nginx reverse proxy for Laravel Octane (FrankenPHP/Swoole) on port 8000 and Laravel Reverb WebSockets on port 8080 with SSL and 3600s timeouts.
Debug CORS between Laravel 11/12 APIs and Next.js App Router on port 3000. Separate Server Component fetches from Client Component browser preflights.
Frequently Asked Questions
- Why does Laravel Octane fail with SQLSTATE[08006] when Postgres is in docker-compose.yml?
- PostgreSQL takes several seconds to initialize on first launch. Adding a pg_isready healthcheck and depends_on condition: service_healthy holds Octane until Postgres is actively accepting TCP connections.
- Can Reverb use Redis to scale across multiple Reverb containers?
- Yes. Setting REVERB_SCALING_ENABLED=true in .env instructs Reverb to coordinate broadcast channels via your Redis 7 container automatically.
- Should I mount my local source code volume into Octane in production?
- No. Bind-mounting host directories slows down PHP filesystem checks and introduces permission mismatches. Copy application files into an immutable Docker image during docker compose build.
- How do I reload Octane without killing active Reverb WebSocket users?
- Because Octane and Reverb run in separate Compose services, running docker compose up -d --no-deps --build octane replaces only the Octane container while Reverb keeps every WebSocket client connected.
Related Docker Compose Stack Guides
Browse all 10 Compose stacks →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 Laravel + PostgreSQL 16 + Meilisearch + Redis Stack Guide
Generate a full-stack Docker Compose setup for Laravel Scout with PostgreSQL 16, Redis 7, and Meilisearch using native healthchecks and persistent volumes.
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 ASP.NET Core 8/9 + PostgreSQL 16 + Redis Cache Guide
Generate a Docker Compose config for ASP.NET Core 8/9 Web API, PostgreSQL 16 (Npgsql), and Redis distributed cache with pg_isready and redis-cli healthchecks.