Laravel Octane sur VPS : FrankenPHP, Docker et Traefik

PHP-FPM vs Laravel Octane — ce qui change vraiment

Les six différences structurelles à connaître

• Cycle de vie partagé — le conteneur IoC de Laravel, les providers et les singletons sont instanciés une fois et persistent entre toutes les requêtes d'un worker. Une valeur écrite dans un singleton en requête N est encore là en requête N+1.
• Gain de performance documenté — les benchmarks de la documentation officielle Laravel Octane indiquent 4× à 6× plus de requêtes/seconde face à PHP-FPM 8.3 sur des endpoints typiques, grâce à l'élimination du bootstrap PHP à chaque requête.
• Variables statiques = fuites garanties — toute propriété static écrite pendant une requête pollue les suivantes. Les Facades Laravel cachent des références statiques ; certaines sont nettoyées par Octane, d'autres non.
• Fichiers statiques servis par FrankenPHP — le binaire intègre un serveur HTTP complet. Sur un VPS, plus besoin de nginx devant PHP : FrankenPHP gère TLS, HTTP/2 et HTTP/3 nativement, mais derrière Traefik on lui délègue uniquement HTTP en clair sur le réseau Docker interne.
• Mémoire RSS stable ≠ mémoire fuitée — la mémoire du process monte au démarrage (chargement du framework) puis se stabilise. Une vraie fuite se détecte par une croissance continue sur des milliers de requêtes, pas par le niveau initial.
• Workers et concurrence — Octane démarre --workers=N processus (FrankenPHP utilise des threads Zend Engine). Chaque worker garde son propre état ; pas de partage mémoire entre workers, mais un même worker traite ses requêtes séquentiellement.
• Compatibilité Laravel 10 et 11 — Octane 2.x supporte Laravel 10+. FrankenPHP comme driver est disponible depuis laravel/octane 2.3. PHP 8.2 minimum, PHP 8.3 recommandé.

Prérequis avant de démarrer

Déployer Laravel Octane + FrankenPHP + Traefik en Docker Compose

1. 01

   Installer laravel/octane et publier la configuration

   Dans votre projet Laravel :

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

   Cela publie config/octane.php et ajoute les variables d'environnement dans .env.example. Vérifiez que OCTANE_SERVER=frankenphp est bien défini.

2. 02

   Écrire le Dockerfile 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"]

   L'option --max-requests=500 redémarre le worker après 500 requêtes : un filet de sécurité contre les fuites mémoire résiduelles. Réduisez à 100 en rodage, puis augmentez si la mémoire reste stable.

3. 03

   Écrire le docker-compose.yml complet

   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

   Déployer Traefik avec certificats automatiques

   Créez un réseau Docker partagé puis démarrez 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

   Préparer le fichier .env de production

   Variables critiques à définir sur le VPS :

   APP_ENV=production
   APP_DEBUG=false
   APP_KEY=base64:...  # généré avec php artisan key:generate
   DOMAIN=votre-domaine.com
   DB_DATABASE=laravel
   DB_USERNAME=laravel
   DB_PASSWORD=mot_de_passe_fort
   DB_ROOT_PASSWORD=root_mot_de_passe
   OCTANE_SERVER=frankenphp
   CACHE_DRIVER=redis
   SESSION_DRIVER=redis
   QUEUE_CONNECTION=redis

   Ne committez jamais .env dans git. Sur le VPS, gérez-le avec scp ou un secret manager.

6. 06

   Exécuter les migrations sans interruption

   Avant de basculer vers la nouvelle version, exécutez les migrations depuis un conteneur éphémère qui partage le réseau interne :

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

   Pour un déploiement zero-downtime, utilisez le flag --step sur les migrations qui ajoutent des colonnes NOT NULL — ajoutez d'abord la colonne nullable, déployez l'app, puis ajoutez la contrainte dans une seconde migration.

7. 07

   Démarrer la stack et vérifier le healthcheck

   docker compose up -d --build
   docker compose ps

   Attendez que db et redis passent au statut healthy avant qu'app démarre (géré par depends_on: condition: service_healthy).

   Vérifiez les logs Octane :

   docker compose logs -f app

   La sortie normale ressemble à :

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

8. 08

   Vérifier l'état avec octane:status

   docker compose exec app php artisan octane:status

   Cette commande affiche le serveur actif (frankenphp), le nombre de workers en cours d'exécution et le statut global. Un retour running confirme que les workers répondent. En cas de blocage, octane:reload redémarre les workers sans couper le serveur.

9. 09

   Configurer le rechargement à chaud pour les déploiements

   Lors d'un nouveau déploiement, reconstruisez l'image et rechargez sans downtime :

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

   Dockerfile en place, cette séquence remplace les conteneurs un par un. Pour Octane, le signal de rechargement (SIGUSR1) recharge les workers sans fermer les connexions actives. Docker Compose gère l'envoi du signal automatiquement via restart: unless-stopped.

Checklist de compatibilité avant de basculer en production

8 points à vérifier impérativement

• Singletons avec état mutable — tout service enregistré avec $this->app->singleton() qui stocke des données spécifiques à une requête (utilisateur courant, locale, tenant ID) doit être réinitialisé dans un OctaneServiceProvider via Octane::tick() ou en implémentant un listener RequestReceived. Audit : grep -r 'singleton' app/Providers.
• Sessions — avec SESSION_DRIVER=redis, les sessions survivent correctement entre requêtes. Le driver file peut créer des race conditions si plusieurs workers écrivent simultanément. Migration vers redis ou database recommandée avant le passage à Octane.
• Connexions base de données — Octane maintient des connexions DB persistantes par worker. Configurez DB_POOL_MIN et DB_POOL_MAX dans config/database.php si vous utilisez un pool custom. Vérifiez que MySQL accepte max_connections ≥ workers × replicas.
• Variables statiques dans les modèles ou services — static $cache = [] dans un Eloquent model ou un repository persiste entre requêtes. Remplacez par une injection de dépendance avec scope requête, ou videz explicitement dans le listener RequestTerminated.
• Event listeners non idempotents — un listener enregistré dans boot() d'un ServiceProvider n'est enregistré qu'une fois, mais s'exécute à chaque requête qui déclenche l'événement. Pas de problème en soi, sauf si le listener accumule un état global (compteur, tableau statique).
• Jobs et queues — les Jobs ne tournent pas dans le process Octane principal mais dans le conteneur worker séparé. Ils gardent le cycle PHP-FPM classique. Aucune adaptation requise pour le code des Jobs eux-mêmes.
• Fichiers uploadés et stockage — Storage::disk('local') fonctionne normalement. Attention au chemin storage_path() dans un conteneur Docker : montez un volume pour /app/storage afin que les fichiers persistent entre les rebuilds d'image.
• Packages tiers — certains packages Laravel (Debugbar, Telescope) injectent des middlwares qui accumulent des données en mémoire. Désactivez-les en production avec APP_ENV=production ou via la condition dans config/debugbar.php. Vérifiez la compatibilité Octane sur le dépôt de chaque package.

FrankenPHP vs Swoole vs RoadRunner : choisir son driver Octane

Faites défiler le tableau

Dépannage : erreurs fréquentes en production

Pour aller plus loin