Laravel Octane en VPS: FrankenPHP, Docker y Traefik

PHP-FPM vs Laravel Octane — lo que realmente cambia

Seis diferencias estructurales a conocer

• Ciclo de vida compartido — el contenedor IoC de Laravel, los providers y los singletons se instancian una vez y persisten entre todas las peticiones de un worker. Un valor escrito en un singleton en la petición N sigue ahí en la petición N+1.
• Ganancia de rendimiento documentada — los benchmarks de la documentación oficial de Laravel Octane muestran 4× a 6× más peticiones/segundo frente a PHP-FPM 8.3 en endpoints típicos, al eliminar el bootstrap de PHP en cada petición.
• Variables estáticas = fugas garantizadas — cualquier propiedad static escrita durante una petición contamina las siguientes. Las Facades de Laravel ocultan referencias estáticas; algunas las limpia Octane, otras no.
• Archivos estáticos servidos por FrankenPHP — el binario incluye un servidor HTTP completo. En un VPS, no se necesita nginx delante de PHP: FrankenPHP maneja TLS, HTTP/2 y HTTP/3 de forma nativa.
• Memoria RSS estable ≠ memoria filtrada — la memoria del proceso sube al arrancar y luego se estabiliza. Una fuga real se detecta por crecimiento continuo a lo largo de miles de peticiones, no por el nivel inicial.
• Workers y concurrencia — Octane arranca --workers=N procesos. Cada worker mantiene su propio estado; no hay memoria compartida entre workers, pero un mismo worker procesa sus peticiones secuencialmente.
• Compatibilidad Laravel 10 y 11 — Octane 2.x soporta Laravel 10+. FrankenPHP como driver está disponible desde laravel/octane 2.3. PHP 8.2 mínimo, PHP 8.3 recomendado.

Prerrequisitos antes de empezar

Desplegar Laravel Octane + FrankenPHP + Traefik en Docker Compose

1. 01

   Instalar laravel/octane y publicar la configuración

   En tu proyecto Laravel:

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

   Esto publica config/octane.php y añade las variables de entorno en .env.example. Verifica que OCTANE_SERVER=frankenphp esté definido.

2. 02

   Escribir el Dockerfile para FrankenPHP

   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"]

   La opción --max-requests=500 reinicia el worker después de 500 peticiones: una red de seguridad contra fugas de memoria residuales.

3. 03

   Escribir el docker-compose.yml completo

   services:
     app:
       build: .
       restart: unless-stopped
       environment:
         APP_ENV: production
         APP_KEY: ${APP_KEY}
         DB_HOST: db
         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"]
       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"]
       networks:
         - internal
   
     db:
       image: mysql:8.0
       restart: unless-stopped
       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

   Desplegar Traefik con certificados automáticos

   docker network create traefik
   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

   Preparar el archivo .env de producción

   Variables críticas a definir en el VPS:

   APP_ENV=production
   APP_DEBUG=false
   APP_KEY=base64:...  # generado con php artisan key:generate
   DOMAIN=tu-dominio.com
   DB_DATABASE=laravel
   DB_USERNAME=laravel
   DB_PASSWORD=contraseña_fuerte
   DB_ROOT_PASSWORD=root_contraseña
   OCTANE_SERVER=frankenphp
   CACHE_DRIVER=redis
   SESSION_DRIVER=redis
   QUEUE_CONNECTION=redis

   Nunca hagas commit de .env en git. En el VPS, gestiónalo con scp o un gestor de secretos.

6. 06

   Ejecutar las migraciones sin downtime

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

   Para un despliegue zero-downtime, usa el flag --step en migraciones que añaden columnas NOT NULL.

7. 07

   Arrancar el stack y verificar el healthcheck

   docker compose up -d --build
   docker compose ps

   Espera a que db y redis alcancen el estado healthy antes de que app arranque.

8. 08

   Verificar el estado con octane:status

   docker compose exec app php artisan octane:status

   Este comando muestra el servidor activo (frankenphp), el número de workers en ejecución y el estado global. Una respuesta running confirma que los workers responden.

9. 09

   Configurar recarga en caliente para despliegues

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

   Para recargar workers sin cortar conexiones activas:

   docker compose exec app php artisan octane:reload

Lista de compatibilidad antes de pasar a producción

8 puntos a verificar obligatoriamente

• Singletons con estado mutable — cualquier servicio registrado con $this->app->singleton() que almacene datos específicos de una petición debe reiniciarse en un OctaneServiceProvider. Auditoría: grep -r 'singleton' app/Providers.
• Sesiones — con SESSION_DRIVER=redis las sesiones sobreviven correctamente. El driver file puede crear condiciones de carrera con múltiples workers. Migra a redis o database antes de cambiar a Octane.
• Conexiones de base de datos — Octane mantiene conexiones DB persistentes por worker. Verifica que MySQL acepte max_connections ≥ workers × replicas.
• Variables estáticas en modelos o servicios — static $cache = [] en un modelo Eloquent persiste entre peticiones. Reemplaza con inyección de dependencia con alcance de petición.
• Event listeners no idempotentes — un listener registrado en boot() se registra solo una vez, pero se ejecuta en cada petición que dispara el evento. Problema solo si acumula estado global.
• Jobs y colas — los Jobs no corren en el proceso principal de Octane sino en el contenedor worker separado. No se requieren adaptaciones para el código de los Jobs.
• Archivos subidos y almacenamiento — monta un volumen para /app/storage para que los archivos persistan entre reconstrucciones de imagen.
• Paquetes de terceros — verifica la compatibilidad con Octane de cada paquete. Desactiva Debugbar y Telescope en producción.

FrankenPHP vs Swoole vs RoadRunner: elegir tu driver Octane

Desplace la tabla

Resolución de problemas: errores frecuentes en producción

Próximos pasos