Docker Compose Builder · PHP / Laravel Octane + Reverb

Docker Compose Laravel Octane + PostgreSQL 16 + Reverb WebSockets Guide

Generate a Compose Specification docker-compose.yml and matching .env.example for PHP / Laravel Octane + Reverb with native binary healthchecks, service_healthy boot ordering, and firewall-safe port bindings.

Written & verified by Chathura Prabashana · Updated November 2026

1. Adjust stack settings or load a test scenario2. Inspect live diagnostics3. Copy generated config
Quick-Test Scenarios:

1. Runtime & Data Services

2. Healthchecks, Workers & Security

# docker-compose.yml — Modern Compose Specification (no obsolete 'version:' attribute)
# Generated by OpsCheck DevTools (Laravel PHP)
name: laravel_octane_stack

services:
  octane:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    env_file:
      - .env
    expose:
      - "8000"
    environment:
      DB_HOST: postgres
      DB_PORT: "5432"
      REDIS_HOST: redis
      REDIS_PORT: "6379"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app_network

  worker:
    build:
      context: .
      dockerfile: Dockerfile
    command: php artisan queue:work --sleep=3 --tries=3 --max-time=3600
    restart: unless-stopped
    env_file:
      - .env
    environment:
      DB_HOST: postgres
      DB_PORT: "5432"
      REDIS_HOST: redis
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app_network

  nginx:
    image: nginx:1.27-alpine
    restart: unless-stopped
    ports:
      - "127.0.0.1:80:80"
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - octane
    networks:
      - app_network

  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${DB_DATABASE:-app_db}
      POSTGRES_USER: ${DB_USERNAME:-app}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-change_me_strong}
    # Kept strictly internal on app_network (prevents Docker iptables UFW bypass)
    expose:
      - "5432"
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-app} -d $${POSTGRES_DB:-app}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    networks:
      - app_network

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    restart: unless-stopped
    expose:
      - "6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    networks:
      - app_network

networks:
  app_network:
    driver: bridge

volumes:
  db_data:
  redis_data:
Service Boot Orderbridge: app_network
postgres(healthy)+redis(healthy)octaneworkernginx

Healthcheck & Security Diagnostics

Compose Spec v2+
  • passStartup Race Condition Prevented (condition: service_healthy)

    octane and worker will wait until postgres and redis pass their native healthchecks before starting.

  • infoInternal Bridge DNS Hostnames (Never Use localhost Inside Containers)

    Connect over the shared app_network using Docker service names: DB_HOST=postgres (port 5432), REDIS_HOST=redis (port 6379). Inside the "octane" container, 127.0.0.1/localhost points only to "octane" itself and always refuses DB/broker connections.

  • passFirewall-Safe Port Exposure Enabled (127.0.0.1 / Internal expose:)

    Database and broker ports stay strictly isolated on app_network via expose:, and app ports bind to 127.0.0.1 so Docker never bypasses host UFW/nftables rules.

  • passNative Probe Binaries Used (pg_isready & redis-cli ping)

    Generated healthchecks invoke built-in service binaries rather than curl or wget, avoiding false "unhealthy" states in minimal Alpine and slim official images.

  • passPersistent Named Volumes Declared (db_data, redis_data)

    Top-level named volumes preserve database tables and broker queues across container rebuilds and "docker compose down" (data is only removed if you pass -v).

Runs locally in your browser. Compose YAML and environment templates are generated client-side.

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:

docker compose logs (Startup Failure)

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.

  1. 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)yaml
      reverb:
        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_network
  2. 2Configure PostgreSQL, Redis, and Internal Reverb Hostnames in .env

    .env

    Use internal Docker Compose service hostnames for backend-to-backend broadcasts (REVERB_HOST=reverb for server pushes or public WSS domain for browser Echo clients).

    .envdotenv
    DB_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=true
  3. 3Proxy Octane (8000) and Reverb (8080) Through the Nginx Container

    nginx/default.conf

    Use 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.confnginx
    location / {
        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;
    }
  4. 4Boot the Stack and Run PostgreSQL Migrations Safely

    terminal

    Start all containers, verify postgres and redis are healthy, and execute Laravel migrations once on the octane container.

    terminalbash
    docker 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.

Pitfall 1

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.

Pitfall 2

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.

Pitfall 3

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.

Related Tools

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:

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.
Browse all 10 Compose stacks →