Octane

Laravel Octane supercharges your application's performance by keeping it loaded in memory and serving requests at incredible speeds. The FrankenPHP variation of our images provides native Octane support with worker mode built in, and you can run Octane's other servers from our CLI image.

What is Laravel Octane?

Laravel Octane boots your Laravel application once and keeps it in memory, then processes thousands of requests without reloading. This dramatically improves performance compared to traditional PHP execution.

Traditional PHP: Bootstrap → Handle Request → Teardown → Repeat for every request

With Octane: Bootstrap once → Handle unlimited requests

Choosing an Octane Server

Octane runs on four different application servers. One of them is built into our images, and the rest need some assembly:

We recommend FrankenPHP for almost everyone. It is the only server where the image does the hard part for you: the Caddyfile we ship handles asset caching, security headers, trusted proxies, SSL, the health check endpoint, and log redaction, and it switches itself into worker mode when Octane starts it. Everywhere else, those concerns become your job.

Quick Start with FrankenPHP

Let's use this example project to get started.

Classic Mode

By default, FrankenPHP runs in classic mode. Your compose file might look something like this:

services:
  php:
    image: serversideup/php:8.5-frankenphp
    ports:
      - "80:8080"
    volumes:
      - .:/var/www/html/

We'll expand upon this classic mode file and modify it to run Laravel Octane (which uses FrankenPHP's worker mode).

Install Laravel Octane

First, install Octane in your Laravel application and tell it to use FrankenPHP. These are the same steps from the official Laravel documentation:

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

The install command publishes config/octane.php, sets OCTANE_SERVER=frankenphp in your .env file, and creates a PHP file in your /public directory. This is the script FrankenPHP keeps running in memory, and Octane needs it to work.

<?php

// Set a default for the application base path and public path if they are missing...
$_SERVER['APP_BASE_PATH'] = $_ENV['APP_BASE_PATH'] ?? $_SERVER['APP_BASE_PATH'] ?? __DIR__.'/..';
$_SERVER['APP_PUBLIC_PATH'] = $_ENV['APP_PUBLIC_PATH'] ?? $_SERVER['APP_PUBLIC_PATH'] ?? __DIR__;

require __DIR__.'/../vendor/laravel/octane/bin/frankenphp-worker.php';

Configure Worker Mode

We now want to update the compose file to start Octane instead of FrankenPHP's classic mode.

services:
  php:
    image: serversideup/php:8.5-frankenphp
    ports:
      - "80:8080"
    volumes:
      - .:/var/www/html/
    # Start Octane in worker mode with our production-ready Caddyfile
    command: ["php", "artisan", "octane:start", "--server=frankenphp", "--port=8080", "--caddyfile=/etc/frankenphp/Caddyfile"]

The command does three things:

1. octane:start --server=frankenphp starts FrankenPHP in worker mode through Octane, exactly as the official Laravel documentation describes.
2. --port=8080 matches CADDY_HTTP_PORT, which defaults to 8080. Our Caddyfile listens on CADDY_HTTP_PORT, so if you change that variable, change --port to match. The port is written out because Docker's exec form (the JSON array syntax) does not perform variable substitution.
3. --caddyfile=/etc/frankenphp/Caddyfile tells Octane to use the Caddyfile that ships with this image instead of its own. Laravel documents this option under Custom Caddyfile Configuration. Octane's own Caddyfile is a minimal configuration, so without this flag you lose our trusted proxy support, security headers, asset caching, SSL modes, health check endpoint, and most of the CADDY_* environment variables.

Octane sets LARAVEL_OCTANE=1 in FrankenPHP's environment when it starts the server. Our Caddyfile detects this and switches on the settings Octane expects: the worker script, routing every request to frankenphp-worker.php instead of index.php, and the Caddy admin API that octane:status and octane:reload rely on. Everything else in the Caddyfile stays the same as classic mode, including logs on stderr, which is the only stream Octane relays.

Testing Locally

Run your application locally to test Octane:

docker compose up

Your Laravel application will be available at http://localhost with Octane running in worker mode.

Health Checks

The image's built-in health check keeps working in Octane mode, because our Caddyfile still serves the /healthcheck endpoint. No changes are required.

If you would rather use Octane's own status check, the image also ships a healthcheck-octane command. It runs php artisan octane:status, which asks the Caddy admin API whether the server Octane started is still running:

services:
  php:
    # ...
    healthcheck:
      test: ["CMD", "healthcheck-octane"]
      start_period: 10s

Logging

Octane relays FrankenPHP's log output to your console, but it only reads stderr and it only understands JSON. Our Caddyfile satisfies both without any settings. The FrankenPHP variation writes to stderr by default, which is Caddy's default, and Caddy writes JSON whenever stderr is not a terminal, which is always the case when Octane starts FrankenPHP. Read more about how we approach logging.

Here is what you will see:

• In the local environment, Octane prints one line per request with the method, path, status code, and duration. This is the same output you get with Octane's own Caddyfile.
• In every other environment, Octane prints Caddy's warnings and errors and drops the request lines.
• With --log-level, Octane passes Caddy's JSON through untouched. Laravel documents this option as the switch to FrankenPHP's native logger that "will produce structured JSON logs", and that is exactly what you get.

Octane also decides the log level. It sets CADDY_SERVER_LOG_LEVEL to INFO when APP_ENV is local and to WARN everywhere else, which takes precedence over LOG_OUTPUT_LEVEL. Caddy writes request logs at the INFO level, so at WARN successful requests no longer appear in your logs.

The request log redacts the authorization query parameter, so the JWT that Mercure 0.x subscribers pass in the URL never lands in your logs. This is the same filter that FrankenPHP's own Caddyfile recommends.

PHP Settings Still Apply

Octane does not change how PHP loads its configuration. FrankenPHP reads the same php.ini files from /usr/local/etc/php/conf.d/ in every mode, so all of the PHP_* environment variables (like PHP_MEMORY_LIMIT and PHP_OPCACHE_ENABLE) work exactly as they do in classic mode. Any custom .ini files you mount into that directory apply as well.

Octane Options

Octane passes its command line options to FrankenPHP through environment variables. Here is how they behave with our Caddyfile:

The max_execution_time setting in config/octane.php works as documented by Laravel, because Octane passes it to the worker script rather than to the Caddyfile.

Octane also sets CADDY_GLOBAL_OPTIONS and CADDY_SERVER_EXTRA_DIRECTIVES for its own use, so any value you set for those variables is replaced when Octane starts FrankenPHP:

• CADDY_SERVER_EXTRA_DIRECTIVES carries the mercure array from config/octane.php. Use the MERCURE_* variables instead. See Mercure. For your own directives, like headers or redirects, mount a .caddyfile into /etc/frankenphp/caddyfile-server.d/. See Adding your own Caddyfile rules.
• CADDY_GLOBAL_OPTIONS is not applied in Octane mode, because Octane sets it to auto_https disable_redirects, which would conflict with CADDY_AUTO_HTTPS. If you need additional global options, mount a .caddyfile into /etc/frankenphp/caddyfile-global.d/.

Octane's own Caddyfile asks for JSON logs through CADDY_SERVER_LOGGER. Our Caddyfile does not read that variable, because Caddy already writes JSON when Octane starts it. See Logging.

'caddy' => [
    'env' => [
        'CADDY_SERVER_LOG_LEVEL' => 'INFO',
    ],
],

Octane sets APP_PUBLIC_PATH to your application's public directory, but our Caddyfile looks for frankenphp-worker.php in CADDY_SERVER_ROOT instead. This keeps the worker script and the document root in the same place. If you changed APP_BASE_DIR, set CADDY_SERVER_ROOT to match, just like classic mode.

Mercure

Turn on FrankenPHP's Mercure hub with the MERCURE_* environment variables, the same as classic mode, and leave the mercure array out of config/octane.php. Read how to set up Mercure →

FrankenPHP's Laravel docs configure the hub through that array instead. Octane passes it to our Caddyfile in CADDY_SERVER_EXTRA_DIRECTIVES, which lands in every site block. With SSL_MODE=mixed or full your app is served from more than one site block, so the array creates more than one hub, and Mercure 1.0 refuses to start with more than one unnamed hub. The environment variables name the hub, so every site shares it.

Running Octane Without FrankenPHP

Swoole, Open Swoole, and RoadRunner all run from the cli image. It already ships what Octane needs on the PHP side: the pcntl extension, Composer, install-php-extensions, our entrypoint scripts (including the Laravel automations), and an unprivileged www-data user.

What it does not ship is a web server, and that is the whole tradeoff. Read What You Give Up first.

What You Give Up

Our frankenphp variation hardens your application in the Caddyfile that ships inside the image. Swoole has no equivalent: its HTTP server is the PHP process itself, configured from your application's config/octane.php, with no place to express caching rules, header policies, or path matching. RoadRunner has a configuration file, but nothing in our images populates it for you.

Here is what moves from the image back onto your plate:

Everything below the HTTP layer still works exactly as it does everywhere else. All of the PHP_* environment variables, the AUTORUN_* Laravel automations, the unprivileged user, and the file permission handling are part of the cli image, not the web server.

Running Octane on Swoole

Swoole is a PHP extension, so install it in your own Dockerfile:

FROM serversideup/php:8.5-cli

USER root
RUN install-php-extensions swoole
USER www-data

For Open Swoole, use install-php-extensions openswoole instead. Everything else is identical.

Install Octane and point it at Swoole:

docker compose run php composer require laravel/octane
docker compose run php php artisan octane:install --server=swoole

Then start it from your compose file:

services:
  php:
    build:
      context: .
    ports:
      - "80:8000"
    volumes:
      - .:/var/www/html/
    # --host=0.0.0.0 is required so the port is reachable outside the container
    command: ["php", "artisan", "octane:start", "--server=swoole", "--host=0.0.0.0", "--port=8000"]
    healthcheck:
      test: ["CMD", "healthcheck-octane"]
      start_period: 10s

Port 8000 is Octane's default and is above 1024, so the unprivileged www-data user can bind it without any changes.

Running Octane on RoadRunner

RoadRunner needs the sockets extension, which is not in the cli image, plus the RoadRunner binary itself:

FROM serversideup/php:8.5-cli

USER root
RUN install-php-extensions sockets

# Install the RoadRunner binary. TARGETARCH is provided by BuildKit,
# so this works on both amd64 and arm64.
ARG TARGETARCH
ARG ROADRUNNER_VERSION=2025.1.15
RUN docker-php-serversideup-download \
      "https://github.com/roadrunner-server/roadrunner/releases/download/v${ROADRUNNER_VERSION}/roadrunner-${ROADRUNNER_VERSION}-linux-${TARGETARCH}.tar.gz" \
      /tmp/roadrunner.tar.gz && \
    tar -xzf /tmp/roadrunner.tar.gz -C /tmp && \
    mv "/tmp/roadrunner-${ROADRUNNER_VERSION}-linux-${TARGETARCH}/rr" /usr/local/bin/rr && \
    chmod +x /usr/local/bin/rr && \
    rm -rf /tmp/roadrunner*

USER www-data

Then add the PHP side and start the server:

docker compose run php composer require laravel/octane spiral/roadrunner-http

services:
  php:
    build:
      context: .
    ports:
      - "80:8000"
    volumes:
      - .:/var/www/html/
    # --rr-config points RoadRunner at the hardened config below
    command: ["php", "artisan", "octane:start", "--server=roadrunner", "--host=0.0.0.0", "--port=8000", "--rpc-port=6001", "--rr-config=/var/www/html/.rr.yaml"]
    healthcheck:
      test: ["CMD", "healthcheck-octane"]
      start_period: 10s

Locking Down RoadRunner's Static Files

Octane starts RoadRunner with http.static.dir pointed at your public directory and no forbidden extensions. RoadRunner will happily return your .env file, and it serves .php files as plain text rather than refusing them. Create a .rr.yaml in your project root and pass it with --rr-config:

version: "3"

http:
  static:
    # RoadRunner serves everything in the public directory by default,
    # including .php files as plain text. Refuse these outright.
    forbid: [".php", ".env", ".bak", ".log", ".sql", ".ini", ".git"]

With this file in place, /.env, /uploaded.php, and /config.bak all return 404, while your real assets keep working. This is the RoadRunner equivalent of the rules our Caddyfile applies for you, and it is still narrower than what a reverse proxy gives you.

Serving Static Assets and TLS

Laravel recommends running Octane behind NGINX or Apache in production so the web server can serve your static assets and terminate TLS. That reverse proxy is also where the protections from What You Give Up belong.

services:
  php:
    build:
      context: .
    volumes:
      - .:/var/www/html/
    # --host=0.0.0.0 is required so the port is reachable outside the container
    command: ["php", "artisan", "octane:start", "--server=swoole", "--host=0.0.0.0", "--port=8000"]

  web:
    image: nginx:1.29-alpine
    ports:
      - "80:80"
    volumes:
      - .:/var/www/html/:ro
      - ./docker/nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - php

Laravel publishes a reference NGINX configuration for this setup. Point proxy_pass at http://php:8000 instead of http://127.0.0.1:8000, since Octane runs in a separate container here.

Checking the Server Status

There is no /healthcheck endpoint here, because that endpoint lives in our Caddyfile. Your options are to define a health check route in your Laravel application, or to use the healthcheck-octane command that ships in every one of our images:

services:
  php:
    # ...
    healthcheck:
      test: ["CMD", "healthcheck-octane"]
      start_period: 10s

It runs php artisan octane:status, which inspects the server Octane started, whichever server that is.

OPcache and PHP Settings

All of the PHP_* environment variables work the same way they do in every other variation. One detail is different: Octane on Swoole or RoadRunner is a CLI process, so OPcache follows PHP_OPCACHE_ENABLE_CLI rather than PHP_OPCACHE_ENABLE.

Watching for File Changes

The --watch flag needs Node and Chokidar when you are not using FrankenPHP:

npm install --save-dev chokidar

Neither Node nor Chokidar ships in the cli image, so add them to your development image if you want this. FrankenPHP's built-in file watcher is specific to the frankenphp variation.

Swoole-Only Octane Features

These are the features that make Swoole worth the extra work. None of them are available on FrankenPHP or RoadRunner:

• Concurrent tasks run operations in parallel with Octane::concurrently(), using Swoole's task workers. Set how many with --task-workers on octane:start.
• Ticks and intervals invoke a callback every N seconds without a cron entry.
• The Octane cache driver stores data in shared memory at extremely high throughput. The data is flushed whenever the server restarts, so treat it as a cache and nothing more.
• Tables share arbitrary structured data between all workers, with the same restart caveat.

Things to Watch Out For

Since Octane is a whole different way of running Laravel compared to traditional PHP-FPM, there are a few things to watch out for.

Dependency Injection

Be careful with how you inject dependencies into long-lived objects. Injecting the wrong things into constructors can cause requests to "leak" between users. Review Laravel's Dependency Injection and Octane documentation for details.

Memory Leaks

Review Laravel's Octane documentation on memory leaks to understand what to avoid.

Reloading After Deployments

Octane keeps your code in memory, so a deployment needs php artisan octane:reload to pick up new code. In a container this usually means replacing the container instead. If you do reload in place, our Caddyfile exposes the admin API Octane needs, so octane:reload works as expected.

Learn More

• FrankenPHP Variation Documentation
• Laravel Octane Documentation
• FrankenPHP Documentation