After a deploy, a Laravel Reverb server keeps running old code; why, and how do reverb:restart and a process manager fix it?

## Why a deploy does not reach Reverb PHP-FPM builds the application from scratch on every request, so new code takes effect as soon as the files change. Reverb is different: `php artisan reverb:start` boots Laravel **once** and then runs a ReactPHP event loop for as long as it lives. Everything loaded at boot stays in memory: - the application's classes and any code Reverb calls, such as its internal event listeners - the configuration, including `config/reverb.php` values like `allowed_origins` and app credentials - the environment it was started with So a deploy that changes any of these has no effect on a running Reverb server until the process is replaced. This is the same rule that applies to queue workers. ## What reverb:restart actually does `php artisan reverb:restart` is a **signal**, not a kill: 1. It stores the current timestamp in the cache under the key `laravel:reverb:restart`, forever. 2. Each Reverb server remembered the key's value when it started and checks it on a **five-second** timer. 3. When the value differs, the server **gracefully disconnects** every connection it holds and stops listening, and the process exits. 4. A process manager notices the exit and starts `reverb:start` again, which boots the new code. Browsers running Echo see their connection close and reconnect automatically, landing on the fresh process. ## What has to be true for it to work | Requirement | What goes wrong otherwise | |---|---| | A process manager with auto-restart | the server stops and stays down | | A cache store shared by every Reverb server | servers that read a different store never see the signal | | The command runs against the same cache as the servers | a deploy script with another `CACHE_STORE` signals nobody | | The deploy finishes before the signal | servers restart onto half-deployed code | The Laravel 13 skeleton's `CACHE_STORE=database` is shared by every host that uses the same database, so it works across servers. A `file` store on each host, or the `array` store, breaks the signal between machines. ## Running it under Supervisor A minimal Supervisor program for the whiteboard's Reverb server: - `command=php /var/www/whiteboard/artisan reverb:start` - `autorestart=true`, so the exit after a restart signal is followed by a new start - a `user` other than root, and a raised `minfds` in `[supervisord]` for high connection counts - a `stopwaitsecs` long enough for graceful disconnects when Supervisor itself stops the program ## The deploy sequence 1. Put the new release in place and build assets. 2. Run migrations and cache configuration as your deploy normally does. 3. Run `php artisan reverb:restart`, alongside `queue:restart` for the queue workers. 4. Watch that Reverb servers come back and clients reconnect. ## What a restart costs A restart disconnects every whiteboard user at once, and they reconnect within seconds. That is harmless for a small app but can produce a reconnect burst on a large one, and any state only held in the browser (a stroke in flight) must survive a reconnect. Presence channels will show members leaving and rejoining. Restarting servers one by one behind a load balancer spreads the burst, at the cost of a slower rollout. ## Stopping by signal Reverb also handles `SIGINT` and `SIGTERM`: stopping the process from the terminal or from the process manager triggers the same graceful disconnect before exit, so a plain Supervisor restart is also safe; `reverb:restart` is the convenient way to reach every server at once without shell access to each.