In Laravel Octane, what do octane:install and the OCTANE_SERVER variable decide, and how does octane:start choose which server to launch?

## What Octane adds to a Laravel app **Laravel Octane** (`laravel/octane`, 2.20 at the time of writing) serves a Laravel application through a long-running **application server** instead of a fresh PHP process per request. Octane itself is the glue: Artisan commands to install, start, reload and stop a server, a worker loop that feeds requests into a booted application, and listeners that reset framework state between requests. The server underneath is one of three **drivers**: - `frankenphp` - FrankenPHP, a Go binary built on the Caddy web server. - `roadrunner` - RoadRunner, a Go process manager that talks to PHP worker processes. - `swoole` - the Swoole **or** Open Swoole PHP extension; Octane's Swoole code checks for either extension, so Open Swoole has no driver name of its own. ## What `octane:install` does `php artisan octane:install` is a one-time setup command. It asks which server you want (the prompt preselects `frankenphp`), or takes the answer from `--server=`, and then does server-specific work: | Choice | What the installer prepares | Files it adds to `.gitignore` | |---|---|---| | `frankenphp` | downloads the FrankenPHP binary for your OS, copies `public/frankenphp-worker.php` | `**/caddy`, `frankenphp`, `frankenphp-worker.php` | | `roadrunner` | offers to `composer require spiral/roadrunner-http` and `spiral/roadrunner-cli`, then downloads the `rr` binary | `rr`, `.rr.yaml` | | `swoole` | only checks the extension and warns "The Swoole extension is missing." if it is absent | none | Note what the Swoole row does **not** do: Octane never compiles or installs a PHP extension. You install `swoole` or `openswoole` yourself (typically with PECL, or a Docker image that ships it). When the server-specific step succeeds, the installer: 1. writes `OCTANE_SERVER=<choice>` into `.env`, replacing an existing `OCTANE_SERVER=` line or appending one; 2. publishes `config/octane.php` through `vendor:publish --tag=octane-config` (with `--force`, it overwrites an existing copy). ## How `octane:start` picks the server `php artisan octane:start` is the command you run, locally or under a process monitor. Its resolution order is short: 1. the `--server` option, if you passed one; 2. otherwise `config('octane.server')`, which the published config defines as `env('OCTANE_SERVER', 'roadrunner')`. It then calls a **hidden** per-server command - `octane:frankenphp`, `octane:roadrunner` or `octane:swoole` - forwarding the host, port, worker count and other options. An unknown value ends with "Invalid server: ..." and exit code 1. The config fallback is the trap worth remembering. The installer's prompt suggests FrankenPHP, but the config file's own default is still **RoadRunner**. If the `OCTANE_SERVER` line is lost - a new `.env` on a server, a container that does not pass it through - `octane:start` tries RoadRunner and fails with "RoadRunner not installed. Please execute the `octane:install` Artisan command." when RoadRunner was never set up. ## Defaults that come with the start command - **Host**: `--host`, else `config('octane.host')`, else the `OCTANE_HOST` variable, else `127.0.0.1`. The loopback default means only local clients (for example, a reverse proxy on the same machine) can reach Octane until you bind `0.0.0.0`. - **Port**: `--port`, else `config('octane.port')`, else `OCTANE_PORT`, else `8000`. - **Workers** and **max requests**: `--workers` defaults to `auto` and `--max-requests` to `500`; sizing and recycling are separate topics. - The start command also refuses to launch when the port is already in use, or when the chosen server is already running according to its state file (`storage/logs/octane-server-state.json` by default). ## Where the pieces end up After installing and starting once, the files involved are easy to list: - `config/octane.php` - the published config: `server`, `https`, listeners, `warm`/`flush`, `watch`, `max_execution_time`, `state_file` and per-server sections; - `.env` - the `OCTANE_SERVER` line the installer wrote; - `public/frankenphp-worker.php` - FrankenPHP's worker entry script, copied on install or first start; - `.rr.yaml` - created empty by the RoadRunner start command when you do not pass `--rr-config`, because Octane passes most RoadRunner settings as `-o` overrides; - the `frankenphp` or `rr` binary in the project root, which the start command also offers to download if it is missing or too old. ## Mistakes interviewers listen for - Treating `octane:install` as something you run on every deploy. It is setup; deploys use `octane:reload` or a restart. - Assuming the config falls back to FrankenPHP because the installer recommends it. - Looking for an `openswoole` driver value: Open Swoole runs under `swoole`. - Expecting `php artisan serve` to use Octane. It does not; Octane is started only through `octane:start` (or the hidden per-server commands, which Docker images sometimes call directly).