Run Laravel with Octane

Laravel Octane keeps the application in memory between requests. Ingot serves Laravel with FrankenPHP’s standard mode, which loads the framework, the configuration and the service providers again for every request; Octane runs FrankenPHP in worker mode, where each worker loads them once and then handles request after request. On Sevalla, you install Octane, add a Caddyfile that trusts Sevalla’s proxy, and set the web process’s start command: the image Ingot builds is the same.

At a glance

What this guide changes in the application from Deploy a Laravel application:


Start command	`php artisan optimize && exec php artisan octane:start --server=frankenphp --host=0.0.0.0 --port=$PORT --caddyfile=Caddyfile.octane --workers=2`, the web process’s custom start command
Health check	`GET /up` returns `200` (readiness probe), unchanged
Size	H1 or larger; set `--workers` for the size as in Choose the number of workers

Environment variables

This guide adds no environment variables. The deploy guide lists the application’s variables.

Before you begin

A Laravel application deployed on Sevalla, as in Deploy Laravel.

Install Octane

Install Octane 2 and set it up for FrankenPHP:

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

octane:install writes config/octane.php and downloads a FrankenPHP binary to the project’s root for local development, which it adds to .gitignore together with public/frankenphp-worker.php, the worker script Octane writes when it starts. Neither goes into the repository: Ingot’s image already has FrankenPHP in /usr/local/bin (version 1.13.4; Octane needs 1.13.0 or later), and Octane writes the worker script on its first start.

Trust the Sevalla proxy

Octane starts FrankenPHP with its own Caddyfile, not Ingot’s. That Caddyfile doesn’t trust Sevalla’s proxy, which ends HTTPS before the request reaches the application, so behind it Laravel sees every request as plain HTTP from the proxy:

Laravel builds http:// URLs, and browsers block the Vite stylesheet and scripts on the https:// page as mixed content.
$request->ip() returns the proxy’s private address, such as 10.244.19.190, for every visitor, so rate limits by IP count all visitors together.

Copy Octane’s Caddyfile to Caddyfile.octane in the project’s root and add three things, which Ingot’s Caddyfile has too:

Caddyfile.octane

{
	{$CADDY_GLOBAL_OPTIONS}

	admin {$CADDY_SERVER_ADMIN_HOST}:{$CADDY_SERVER_ADMIN_PORT}

	frankenphp {
		worker {
			file "{$APP_PUBLIC_PATH}/frankenphp-worker.php"
			{$CADDY_SERVER_WORKER_DIRECTIVE}
			{$CADDY_SERVER_WATCH_DIRECTIVES}
		}
	}

	servers {
		trusted_proxies static private_ranges
		client_ip_headers CF-Connecting-IP X-Forwarded-For
	}
}

{$CADDY_EXTRA_CONFIG}

{$CADDY_SERVER_SERVER_NAME} {
	log {
		level {$CADDY_SERVER_LOG_LEVEL}

		format filter {
			wrap {$CADDY_SERVER_LOGGER}
			fields {
				request>uri query {
					replace authorization REDACTED
				}
			}
		}
	}

	@forwarded_https {
		remote_ip private_ranges
		header X-Forwarded-Proto https
	}
	vars @forwarded_https https on

	@compressible not path /.well-known/mercure

	route {
		root * "{$APP_PUBLIC_PATH}"
		encode @compressible zstd br gzip

		{$CADDY_SERVER_EXTRA_DIRECTIVES}

		php_server {
			index frankenphp-worker.php
			try_files {path} frankenphp-worker.php
			resolve_root_symlink
			env HTTPS {vars.https}
			env REMOTE_ADDR {client_ip}
		}
	}
}

Addition	What it does
`servers` block	Trusts the `X-Forwarded-For` header from private addresses, Sevalla’s proxy, and takes the visitor’s address from `CF-Connecting-IP`, which Cloudflare sets and a visitor can’t.
`@forwarded_https` and `vars`	Marks a request as HTTPS when Sevalla’s proxy says it arrived over HTTPS.
`env HTTPS` and `env REMOTE_ADDR`	Pass both to Laravel, which then builds `https://` URLs and returns the visitor’s address from `$request->ip()`, with no trusted proxy settings in Laravel.

The {$...} placeholders are the values Octane fills in when it starts, as in its own Caddyfile in vendor/laravel/octane/src/Commands/stubs/Caddyfile. When you update Octane, compare that file with yours.

Show which server answers

Add a route that reports whether Octane serves it, and how many requests the worker that answers has handled. The count lives in a static property, which is what makes it useful: PHP resets it after every request in the standard mode, and keeps it for the worker’s lifetime under Octane:

app/Support/Visits.php

<?php

namespace App\Support;

class Visits
{
    public static int $count = 0;
}

routes/web.php

<?php

use App\Support\Visits;
use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('welcome');
});

Route::get('/server', function () {
    Visits::$count++;

    return [
        'octane' => isset($_SERVER['LARAVEL_OCTANE']),
        'requests_in_this_worker' => Visits::$count,
    ];
});

Octane sets LARAVEL_OCTANE for the server it starts, which is how Laravel itself checks for Octane. Commit and push the changes, composer.json, composer.lock, config/octane.php and Caddyfile.octane included.

Start Octane on Sevalla

These steps build with Ingot. To build from your own Dockerfile instead, see Update the Dockerfile.

Set the start command

On the application’s Processes tab, click ⋯ on the Web process, then click Update process. Enter this Custom start command and click Update process:

php artisan optimize && exec php artisan octane:start --server=frankenphp --host=0.0.0.0 --port=$PORT --caddyfile=Caddyfile.octane --workers=2

Deploy

Click Deploy in the undeployed changes bar at the bottom of the page.

What each part of the command does:

Part	Why
`php artisan optimize`	Caches the configuration, routes, events and views with the deployment’s environment variables, as Ingot’s own start script does. Octane loads the cached files once per worker.
`exec`	Replaces the shell that Sevalla starts the command with, so Octane receives `SIGTERM` when Sevalla stops the instance. See Stop Octane cleanly.
`--host=0.0.0.0 --port=$PORT`	Octane listens on `127.0.0.1:8000` by default, which Sevalla’s proxy can’t reach.
`--caddyfile=Caddyfile.octane`	The Caddyfile from Trust the Sevalla proxy.
`--workers=2`	The number of workers, each a copy of the application in memory. Without it, the instance runs out of memory: see Choose the number of workers.

Until the start command is set, Ingot’s build log warns Laravel Octane is installed, but Ingot runs FrankenPHP's standard mode, and the application runs as before. Sevalla passes the web process’s start command to Ingot, so the build plan’s Start row shows the Octane command, start in ingot.json or INGOT_START_CMD.

Choose the number of workers

Octane’s default, --workers=auto, starts 2 workers for every CPU that FrankenPHP finds. In a Sevalla instance, that’s the CPUs of the machine it runs on, not the size’s share: 16 in the test, so 32 workers on every size. Each worker holds the whole application, so 32 workers used about 220 MB at rest on H1 (0.3 GB) and crossed 0.3 GB under load, when Sevalla stopped the instance for running out of memory (OOMKilled) and started it again. Set --workers for the size instead. A worker handles one request at a time, and requests to a Laravel application mostly use CPU, so 2 workers per vCPU keep the CPU busy without holding more copies of the application than it needs:

Size	vCPU	`--workers`
H1, S1, S2	0.3 to 1	`2`
S3	2	`4`

On S2, 4 workers served the same number of requests as 2 and used about 10 MB more. A worker that waits, for a slow API or a sleep, holds its place: when every worker is busy, new requests queue, and so does the readiness probe on /up. After 3 probes in a row take longer than the probe’s timeout, Sevalla stops sending requests to the instance, and visitors get 503 until a worker is free. Queue slow work for a background worker, or raise --workers and check the memory on the application’s Analytics tab.

Octane compared with the standard mode

Measured on Sevalla with the deploy guide’s application, from the same image with and without the Octane start command, for 30 seconds with k6 and enough concurrent clients to use the whole CPU of the size. /up is Laravel’s health route, which renders a short page without the database; / is the welcome page, which starts a session and saves it in PostgreSQL:

Size	Server	`/up`, requests per second	`/`, requests per second	Memory at rest	Memory under load
H1	Standard mode	90	21	66 MB	211 MB
H1	Octane, 2 workers	203	81	112 MB	189 MB
S1	Standard mode	159	28	65 MB	208 MB
S1	Octane, 2 workers	326	147	112 MB	189 MB
S2	Standard mode	327	27	66 MB	230 MB
S2	Octane, 2 workers	502	295	112 MB	189 MB
S3	Standard mode	712	43	67 MB	Not measured
S3	Octane, 4 workers	1,023	372	125 MB	204 MB

Octane served more requests on every size, because a worker skips loading the framework for each request: 1.4 to 2.3 times as many on /up, and 4 to 11 times as many on /. In the standard mode, / stopped at about 30 requests per second from S1 up, with the application’s CPU less than half used; it opens a new database connection for every request, while an Octane worker keeps its own. On S3, the standard mode’s slow answers on / made the readiness probe time out, and 38% of the requests failed while Sevalla took the instance out of service. On S2 and S3, Octane didn’t use the whole CPU with the clients the test had, so it can serve more than the table shows. Octane holds more memory at rest, one copy of the application per worker, and about the same under load: the standard mode loads a copy for each request in progress.

Stop Octane cleanly

Sevalla runs the start command with /bin/sh -l -c. exec replaces that shell with Octane’s PHP process, so Octane receives the SIGTERM that Sevalla sends when it stops an instance during a deployment, and stops FrankenPHP, which finishes the requests in progress before it exits. Octane handles the signal with the pcntl extension, which Ingot installs for Laravel. In a test with 12-second requests arriving every 2 seconds during a deployment, every request returned 200. Without exec, the shell receives the signal and ignores it, and Sevalla stops the instance 30 seconds after the shutdown began, cutting off the requests in progress.

State that outlives a request

A worker keeps everything that the application creates outside a request for its lifetime: static properties, singletons, and objects that a singleton holds. Request /server a few times: under Octane, requests_in_this_worker grows with each request that the same worker answers, while in the standard mode it’s always 1. The same happens to data you didn’t mean to keep:

Static properties and arrays. A static array that a request adds to grows with every request and is visible to the next visitor that the worker serves. Keep per-request data in the request, the session or the cache.
Singletons built from the request. A singleton that receives the request, the configuration or the container in its constructor keeps the first request’s values. Resolve them where you use them, or pass them to the method that needs them.
Memory that grows. Octane restarts a worker after 500 requests (--max-requests, 500 by default), which returns memory that a leak holds. Lower it if a worker’s memory keeps growing.
Database connections. Each worker keeps its connection to the database open between requests, where the standard mode opens one for every request. With 4 workers, PostgreSQL listed 5 connections from the application: one per worker and one from the command that counted them. Count workers times instances against the database’s connection limit.

Octane resets Laravel’s own state between requests: the request, the session, the authenticated user, queued cookies, the locale, the configuration and the array cache store. See Laravel’s Octane documentation for what else to watch.

Update the Dockerfile

If the application builds from the Dockerfile in the deploy guide, the same start command runs Octane from your image too. Make three changes:

Install the pcntl extension, which Octane needs to stop FrankenPHP when the instance gets SIGTERM. Change the first RUN line:
Dockerfile
RUN install-php-extensions pdo_pgsql pcntl \

Write Octane’s worker script into the image. Your image’s files belong to root, so Octane can’t write it when it starts. Add a line to the RUN line that installs the Composer packages:

Dockerfile

RUN composer install --no-dev --no-interaction --no-progress --optimize-autoloader \
    && php artisan optimize --except=config \
    && cp vendor/laravel/octane/src/Commands/stubs/frankenphp-worker.php public/

Keep the FrankenPHP binary that octane:install downloaded for your computer out of the image. Git ignores it, so Sevalla’s builds never see it, but a docker build on your computer would copy it into the image, which grew from 77 MB to 172 MB in a test. Add a line to .dockerignore:
.dockerignore
frankenphp

Without the second change, the web process fails to start with copy(/app/public/frankenphp-worker.php): Failed to open stream: Permission denied. The image’s CMD still starts FrankenPHP’s standard mode with the deploy guide’s Caddyfile; the web process’s start command replaces it.

Verify

When the deployment’s status is Deployed, click the Logs tab. The web process’s runtime logs show php artisan optimize caching the configuration, then Octane’s start:
Runtime logs
INFO Server running…. Local: http://0.0.0.0:8080 Press Ctrl+C to stop the server
Open /server on the application’s domain, for example https://storefront-x7k2m.sevalla.app/server. It shows "octane":true.
Open the welcome page. Its styles load, which shows that Laravel builds https:// URLs behind Sevalla’s proxy.

Check from a terminal

These checks need no dashboard. Use your application’s domain:

Octane answers:

curl -s https://storefront-x7k2m.sevalla.app/server | jq .octane

true

The stylesheet link uses https://:

curl -s https://storefront-x7k2m.sevalla.app | grep -o '<link rel="stylesheet"[^>]*>'

<link rel="stylesheet" href="https://storefront-x7k2m.sevalla.app/build/assets/app-6jSCucsl.css" />

The health route that the readiness probe requests:

curl -s -o /dev/null -w '%{http_code}\n' https://storefront-x7k2m.sevalla.app/up

Go back to the standard mode

To serve the application with FrankenPHP’s standard mode again, clear the web process’s Custom start command on the Processes tab and deploy with Deploy now, which builds a new image. Ingot writes the start command into the image it builds, so a restart without a build keeps running Octane.

Troubleshoot

Symptom	Cause	Fix
The web process restarts under load, and the instance’s memory reaches the size’s limit	Octane started 2 workers per CPU of the machine, 32 in the test, because the start command has no `--workers`.	Add `--workers=2`, or the number for the size from Choose the number of workers, then deploy.
The page has no styles, the browser reports mixed content, and `$request->ip()` returns a `10.` address	Octane runs with its own Caddyfile, which doesn’t trust Sevalla’s proxy.	Add `--caddyfile=Caddyfile.octane` with the file from Trust the Sevalla proxy.
The web process doesn’t start, and its runtime logs show `copy(/app/public/frankenphp-worker.php): Failed to open stream: Permission denied`	The image built from your Dockerfile has no worker script, and Octane can’t write one to the root-owned `public/` folder.	Copy the worker script during the build, as in Update the Dockerfile.

Deploy with the API

The same steps as Start Octane on Sevalla, as calls to the Sevalla API. APP_ID and WEB_ID are the application and its web process from Deploy with the API in the deploy guide, with API and H set as there. Push the Octane changes first: the deployment builds the branch as it is.

Set the start command

Update process (updateProcessV3) with the start command in entrypoint:

curl -s -X PATCH "$API/applications/$APP_ID/processes/$WEB_ID" -H "$H" -H "Content-Type: application/json" \
  -d '{"entrypoint": "php artisan optimize && exec php artisan octane:start --server=frankenphp --host=0.0.0.0 --port=$PORT --caddyfile=Caddyfile.octane --workers=2"}' \
  | jq -r .entrypoint

php artisan optimize && exec php artisan octane:start --server=frankenphp --host=0.0.0.0 --port=$PORT --caddyfile=Caddyfile.octane --workers=2

CLI:

sevalla apps processes update $WEB_ID --app-id $APP_ID --command 'php artisan optimize && exec php artisan octane:start --server=frankenphp --host=0.0.0.0 --port=$PORT --caddyfile=Caddyfile.octane --workers=2'

. MCP: sevalla_api_update with updateProcessV3 and the same body.

Deploy

Trigger deployment (triggerDeploymentV3):

DEPLOYMENT_ID=$(curl -s -X POST "$API/applications/$APP_ID/deployments" -H "$H" -H "Content-Type: application/json" \
  -d '{}' | jq -r .id)

CLI: sevalla apps deployments trigger $APP_ID. MCP: trigger_deployment.

Wait for the deployment

Poll Get deployment (getDeploymentV3) until the status is final: success, failed, cancelled or skipped. The loop keeps polling through a failed request and stops after 30 minutes:

for i in $(seq 1 120); do
  STATUS=$(curl -s "$API/applications/$APP_ID/deployments/$DEPLOYMENT_ID" -H "$H" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"

success

CLI: sevalla apps deployments get $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment.

Then run the checks in Check from a terminal, with https://$APP_HOST as the domain. To build from the Dockerfile, send {"build_type": "dockerfile", "dockerfile_path": "Dockerfile", "docker_context": "."} to Update application (updateApplicationV3) before you deploy.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java, Kotlin and Scala

.NET

Elixir

Gleam

Swift

Dart

Static site generators

Run Laravel with Octane

At a glance

Environment variables

Before you begin

Install Octane

Trust the Sevalla proxy

Show which server answers

Start Octane on Sevalla

Choose the number of workers

Octane compared with the standard mode

Stop Octane cleanly

State that outlives a request

Update the Dockerfile

Verify

Check from a terminal

Go back to the standard mode

Troubleshoot

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Install Octane

​Trust the Sevalla proxy

​Show which server answers

​Start Octane on Sevalla

​Choose the number of workers

​Octane compared with the standard mode

​Stop Octane cleanly

​State that outlives a request

​Update the Dockerfile

​Verify

​Check from a terminal

​Go back to the standard mode

​Troubleshoot

​Deploy with the API

At a glance

Environment variables

Before you begin

Install Octane

Trust the Sevalla proxy

Show which server answers

Start Octane on Sevalla

Choose the number of workers

Octane compared with the standard mode

Stop Octane cleanly

State that outlives a request

Update the Dockerfile

Verify

Check from a terminal

Go back to the standard mode

Troubleshoot

Deploy with the API