After deploying new code to a Laravel Octane server, why do you run octane:reload, and when do you need a full restart instead?

## Why a deploy needs a reload With **Laravel Octane**, each worker boots the application once and keeps it in memory: the service providers have run, the configuration is loaded, the route table is built and PHP's own compiled code is loaded. When a deploy puts new files on disk, the running workers do not notice. They keep answering with the code they booted with until they restart. So the last step of rolling code out under Octane is always to **replace the workers**. (Which other deploy steps come before it - caching config and routes, migrations - is a deployment topic.) ## `octane:reload`: new workers, same server `php artisan octane:reload` reads the running server's state file (`storage/logs/octane-server-state.json` by default) and asks the server to restart its workers. If no server is running it prints "Octane server is not running." and exits 1. Each driver does the restart its own way: | Server | What `octane:reload` does | |---|---| | Swoole / Open Swoole | sends `SIGUSR1` to the master process, Swoole's signal for a graceful worker restart | | RoadRunner | runs the `rr` binary's `reset` command against the RPC address recorded at start | | FrankenPHP | reads the `frankenphp` app config from Caddy's admin API and PATCHes it back, which restarts the workers | In all three cases the **server process stays up**: the listening socket, the port, the pool size and other options given at start are unchanged. New workers boot the new code and serve subsequent requests. That is why the docs describe reload as the step to run "after deployment". ## When a reload is not enough Anything the server received when it started survives a reload. Plan a full stop and start when you change: - the **port or host** Octane binds to; - `--workers` (and, on Swoole, `--task-workers`) or `--max-requests`; - `max_execution_time` in `config/octane.php` - Octane's docs say explicitly that changing it requires restarting the server; - the **server driver** itself, for example moving from RoadRunner to FrankenPHP; - the server binary or PHP extension (a new FrankenPHP or `rr` binary, a Swoole upgrade). ## `octane:stop` and how a restart really happens `php artisan octane:stop` also reads the state file and stops the server, deleting the state file afterwards: 1. **Swoole**: sends `SIGKILL` to the master, the manager and every worker process it finds, so in-flight requests are cut off. 2. **RoadRunner**: sends `SIGTERM` to the `rr` master process. 3. **FrankenPHP**: POSTs to the admin API's `/stop` endpoint. In production Octane runs under a **process monitor**; Octane's docs show a Supervisor program whose command is `php artisan octane:start ...`. `octane:start` stays in the foreground and handles `SIGINT`, `SIGTERM` and `SIGHUP` by calling `octane:stop` for its server. So the usual full restart is "restart the monitored program": the monitor signals `octane:start`, Octane stops the server, and the monitor starts it again with the current options. Running `octane:stop` by hand under a monitor with auto-restart simply leads to the monitor starting it again. ## `octane:status` in scripts `php artisan octane:status` prints "Octane server is running." or "Octane server is not running." and returns exit code **0 when running, 1 when not**, so a deploy script can guard a reload with it. Like the other commands, it uses `--server` or `config('octane.server')`, which must match the server actually running. ## The state file Every Octane command finds the running server through a JSON **state file** written at start: the master process ID (and, on Swoole, the manager ID), the host and port, the RPC or admin port, and a copy of the Octane config. Its path is `config('octane.state_file')`, which reads `OCTANE_STATE_FILE` and defaults to `storage/logs/octane-server-state.json`. Two consequences follow. Two Octane servers from one codebase on one host need different state files, or their commands will act on each other. And a release process that replaces the `storage` directory loses the file, after which `octane:reload` reports that the server is not running even though it is. ## A deploy sequence - finish putting the release in place (dependencies, cached config and routes); - `php artisan octane:status` to confirm the server is up; - `php artisan octane:reload` for a code-only release; - restart the monitored program instead when the release changes server options, the driver or the binary. ## Mistakes worth avoiding - Deploying and never reloading, then wondering why the old code still answers. - Expecting a reload to apply a new worker count or time limit. - Running `octane:stop` on Swoole during traffic as if it were graceful. - Calling these commands with a different `OCTANE_SERVER` than the running server, which makes them inspect the wrong state.