Laravel Octane on VPS: FrankenPHP, Docker and Traefik

PHP-FPM vs Laravel Octane — what really changes

Six structural differences to understand

• Shared lifecycle — Laravel's IoC container, providers and singletons are instantiated once and persist across all requests of a worker. A value written to a singleton in request N is still there in request N+1.
• Documented performance gain — official Laravel Octane documentation benchmarks show 4× to 6× more requests/second versus PHP-FPM 8.3 on typical endpoints, by eliminating PHP bootstrap on every request.
• Static variables = guaranteed leaks — any static property written during a request pollutes subsequent ones. Laravel Facades hide static references; some are cleaned by Octane, others are not.
• Static files served by FrankenPHP — the binary includes a full HTTP server. On a VPS, no nginx in front of PHP is needed: FrankenPHP handles TLS, HTTP/2 and HTTP/3 natively, but behind Traefik it only receives plain HTTP on the internal Docker network.
• Stable RSS memory ≠ leaked memory — process memory rises at startup (framework loading) then stabilizes. A real leak shows as continuous growth over thousands of requests, not the initial level.
• Workers and concurrency — Octane starts --workers=N processes (FrankenPHP uses Zend Engine threads). Each worker keeps its own state; no shared memory between workers, but a single worker processes its requests sequentially.
• Laravel 10 and 11 compatibility — Octane 2.x supports Laravel 10+. FrankenPHP as a driver is available since laravel/octane 2.3. PHP 8.2 minimum, PHP 8.3 recommended.

Prerequisites before starting

Deploy Laravel Octane + FrankenPHP + Traefik in Docker Compose

1. 01

   Install laravel/octane and publish the configuration

   In your Laravel project:

   composer require laravel/octane
   php artisan octane:install --server=frankenphp

   This publishes config/octane.php and adds environment variables to .env.example. Verify that OCTANE_SERVER=frankenphp is set.

2. 02

   Write the FrankenPHP Dockerfile

   FROM dunglas/frankenphp:1-php8.3-alpine
   
   RUN install-php-extensions \
       pdo_mysql \
       redis \
       opcache \
       pcntl \
       zip \
       intl
   
   WORKDIR /app
   
   COPY --chown=www-data:www-data . .
   
   RUN composer install --no-dev --optimize-autoloader --no-interaction \
    && php artisan config:cache \
    && php artisan route:cache \
    && php artisan view:cache
   
   EXPOSE 8000
   
   CMD ["php", "artisan", "octane:frankenphp", "--host=0.0.0.0", "--port=8000", "--workers=4", "--max-requests=500"]

   The --max-requests=500 option restarts a worker after 500 requests: a safety net against residual memory leaks. Reduce to 100 while testing, then increase if memory remains stable.

3. 03

   Write the complete docker-compose.yml

   services:
     app:
       build: .
       restart: unless-stopped
       environment:
         APP_ENV: production
         APP_KEY: ${APP_KEY}
         DB_CONNECTION: mysql
         DB_HOST: db
         DB_DATABASE: ${DB_DATABASE}
         DB_USERNAME: ${DB_USERNAME}
         DB_PASSWORD: ${DB_PASSWORD}
         REDIS_HOST: redis
         CACHE_DRIVER: redis
         SESSION_DRIVER: redis
         QUEUE_CONNECTION: redis
         OCTANE_SERVER: frankenphp
       networks:
         - internal
         - traefik
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.app.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.app.entrypoints=websecure"
         - "traefik.http.routers.app.tls.certresolver=letsencrypt"
         - "traefik.http.services.app.loadbalancer.server.port=8000"
       depends_on:
         db:
           condition: service_healthy
         redis:
           condition: service_healthy
   
     worker:
       build: .
       restart: unless-stopped
       command: ["php", "artisan", "queue:work", "redis", "--sleep=3", "--tries=3", "--max-time=3600"]
       environment:
         APP_ENV: production
         APP_KEY: ${APP_KEY}
         DB_HOST: db
         DB_DATABASE: ${DB_DATABASE}
         DB_USERNAME: ${DB_USERNAME}
         DB_PASSWORD: ${DB_PASSWORD}
         REDIS_HOST: redis
         QUEUE_CONNECTION: redis
       networks:
         - internal
       depends_on:
         db:
           condition: service_healthy
         redis:
           condition: service_healthy
   
     scheduler:
       build: .
       restart: unless-stopped
       command: ["sh", "-c", "while true; do php artisan schedule:run >> /dev/null 2>&1; sleep 60; done"]
       environment:
         APP_ENV: production
         APP_KEY: ${APP_KEY}
         DB_HOST: db
         DB_DATABASE: ${DB_DATABASE}
         DB_USERNAME: ${DB_USERNAME}
         DB_PASSWORD: ${DB_PASSWORD}
         REDIS_HOST: redis
       networks:
         - internal
       depends_on:
         db:
           condition: service_healthy
   
     db:
       image: mysql:8.0
       restart: unless-stopped
       environment:
         MYSQL_DATABASE: ${DB_DATABASE}
         MYSQL_USER: ${DB_USERNAME}
         MYSQL_PASSWORD: ${DB_PASSWORD}
         MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
       volumes:
         - db_data:/var/lib/mysql
       networks:
         - internal
       healthcheck:
         test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
         interval: 10s
         timeout: 5s
         retries: 5
   
     redis:
       image: redis:7-alpine
       restart: unless-stopped
       volumes:
         - redis_data:/data
       networks:
         - internal
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 10s
         timeout: 3s
         retries: 5
   
   volumes:
     db_data:
     redis_data:
   
   networks:
     internal:
     traefik:
       external: true

4. 04

   Deploy Traefik with automatic certificates

   Create a shared Docker network then start Traefik:

   docker network create traefik

   traefik.yml:

   entryPoints:
     web:
       address: ":80"
       http:
         redirections:
           entryPoint:
             to: websecure
             scheme: https
     websecure:
       address: ":443"
   
   certificatesResolvers:
     letsencrypt:
       acme:
         email: [email protected]
         storage: /letsencrypt/acme.json
         httpChallenge:
           entryPoint: web
   
   providers:
     docker:
       exposedByDefault: false
       network: traefik
   
   api:
     dashboard: false

   mkdir -p /opt/traefik/letsencrypt
   touch /opt/traefik/letsencrypt/acme.json
   chmod 600 /opt/traefik/letsencrypt/acme.json
   docker compose -f /opt/traefik/docker-compose.yml up -d

5. 05

   Prepare the production .env file

   Critical variables to set on the VPS:

   APP_ENV=production
   APP_DEBUG=false
   APP_KEY=base64:...  # generated with php artisan key:generate
   DOMAIN=your-domain.com
   DB_DATABASE=laravel
   DB_USERNAME=laravel
   DB_PASSWORD=strong_password
   DB_ROOT_PASSWORD=root_strong_password
   OCTANE_SERVER=frankenphp
   CACHE_DRIVER=redis
   SESSION_DRIVER=redis
   QUEUE_CONNECTION=redis

   Never commit .env to git. On the VPS, manage it with scp or a secret manager.

6. 06

   Run migrations without downtime

   Before switching to the new version, run migrations from an ephemeral container sharing the internal network:

   docker compose run --rm app php artisan migrate --force

   For zero-downtime deployment, use the --step flag on migrations that add NOT NULL columns — first add the column as nullable, deploy the app, then add the constraint in a second migration.

7. 07

   Start the stack and verify the healthcheck

   docker compose up -d --build
   docker compose ps

   Wait for db and redis to reach healthy status before app starts (managed by depends_on: condition: service_healthy).

   Check Octane logs:

   docker compose logs -f app

   Normal output looks like:

   INFO  Server running on http://0.0.0.0:8000
   INFO  FrankenPHP workers: 4

8. 08

   Check status with octane:status

   docker compose exec app php artisan octane:status

   This command shows the active server (frankenphp), the number of running workers and global status. A running response confirms workers are responding. If stuck, octane:reload restarts workers without shutting down the server.

9. 09

   Configure hot-reload for deployments

   When deploying a new version, rebuild and reload without downtime:

   docker compose build app worker scheduler
   docker compose up -d --no-deps app worker scheduler

   With the Dockerfile in place, this sequence replaces containers one by one. For Octane, the reload signal (SIGUSR1) reloads workers without dropping active connections. Docker Compose handles signal delivery automatically via restart: unless-stopped.

Compatibility checklist before switching to production

8 points to check carefully

• Singletons with mutable state — any service registered with $this->app->singleton() that stores request-specific data (current user, locale, tenant ID) must be reset in an OctaneServiceProvider via Octane::tick() or by implementing a RequestReceived listener. Audit: grep -r 'singleton' app/Providers.
• Sessions — with SESSION_DRIVER=redis, sessions correctly survive between requests. The file driver can create race conditions if multiple workers write simultaneously. Migrate to redis or database before switching to Octane.
• Database connections — Octane maintains persistent DB connections per worker. Configure DB_POOL_MIN and DB_POOL_MAX in config/database.php if using a custom pool. Verify that MySQL accepts max_connections ≥ workers × replicas.
• Static variables in models or services — static $cache = [] in an Eloquent model or repository persists between requests. Replace with request-scoped dependency injection, or explicitly clear in the RequestTerminated listener.
• Non-idempotent event listeners — a listener registered in a ServiceProvider's boot() is only registered once, but fires on every request that triggers the event. No problem by itself, unless the listener accumulates global state (counter, static array).
• Jobs and queues — Jobs do not run in the main Octane process but in the separate worker container. They retain the classic PHP-FPM lifecycle. No adaptations needed for Job code itself.
• Uploaded files and storage — Storage::disk('local') works normally. Watch storage_path() in a Docker container: mount a volume for /app/storage so files persist between image rebuilds.
• Third-party packages — some Laravel packages (Debugbar, Telescope) inject middlewares that accumulate data in memory. Disable them in production with APP_ENV=production or via conditions in config/debugbar.php. Check Octane compatibility on each package's repository.

FrankenPHP vs Swoole vs RoadRunner: choosing your Octane driver

Scroll the table

Troubleshooting: common production errors

Going further