Use the Laravel panel for the scheduler, queues, Octane and maintenance mode

Laravel applications often need a handful of supporting processes: a cron entry for the scheduler, Horizon for queues, Octane for a long-lived server, Reverb for WebSockets, an Inertia server-side rendering process. SrvYard reads your application's composer.lock and offers each of them as a switch on the Laravel card of the site overview. Behind each switch SrvYard creates the Supervisor process or cron job, adds the matching line to the deploy script and, for Octane and Reverb, wires Nginx to the right port.

This article walks through the card, what every switch does and how to undo it, and how maintenance mode works. It applies to Laravel sites only; other site types do not show the card.

Before you begin#

• A Laravel site that has been deployed at least once. SrvYard detects features from the deployed composer.lock. Before the first deployment the card says "Deploy the site once to detect Horizon, Octane and the rest."
• The package in composer.lock. A switch is greyed out, with a note such as "laravel/horizon is not in this app's composer.lock", until the package is installed and deployed. The scheduler and maintenance mode need no package.
• The right permission. Switching features needs the permission to manage integrations; owners and admins have it.
• A decision about zero downtime. Octane keeps the application in memory and cannot follow a release switch. It can only be enabled on a site that deploys in place. See the Octane section below.

1. Find the Laravel card#

Open the site. The Overview tab shows the site facts, the domains, a Quick links card and the Laravel card.

1. Quick links. Shortcuts to Logs, Run a command, Settings and the Server.
2. The Laravel card. Detected features and their switches.

The card is loaded separately from the page. If SrvYard cannot read the application (the server is unreachable, for instance) it shows "Could not read the application" with the reason and the switches stay unavailable until it can.

2. Read the switches#

1. Detect again. The refresh button next to the title re-reads composer.lock from the server. Use it after a deployment that added or removed a package. Without it SrvYard shows what it detected earlier.
2. Scheduler. "Runs php artisan schedule:run every minute." Needs no package.
3. Horizon, Octane, Reverb and Inertia SSR. Each switch is enabled only when its package (laravel/horizon, laravel/octane, laravel/reverb, inertiajs/inertia-laravel) is in the lock file.
4. Maintenance mode. "Shows a 503 page to visitors (artisan down)."

While a switch is working it shows a busy state and cannot be pressed again. Turn a feature off with the same switch: SrvYard removes the process, the proxy and the deploy-script line it added.

The scheduler#

Turning it on adds one scheduled job that runs php artisan schedule:run every minute as the site user, in the application folder, using the site's PHP version. The Laravel scheduler then decides which of your scheduled tasks are due. See Queue workers and the Laravel scheduler for the details and how to see the job.

1. Every minute. The frequency of the job. It appears on the site's Processes tab under Scheduled jobs, and in the server's own scheduler list.

Horizon#

Creates a background process that runs php artisan horizon (with 3,600 seconds allowed to stop gracefully) and adds php artisan horizon:terminate to the deploy script so Horizon restarts on new code. If you use plain queue workers instead, use Queue workers and the Laravel scheduler; do not run both on the same queue.

Octane#

Enabling Octane opens a dialog with four fields:

• Server. Swoole, RoadRunner or FrankenPHP, whichever your composer.lock supports. SrvYard suggests one.
• Port. The local port Octane listens on, default 8000. Reserved ports (databases, Redis, PHP-FPM and similar) are refused, and so is a port another site already uses.
• Workers. auto or a number.
• Max requests. How many requests a worker serves before it is recycled, default 500.

SrvYard starts php artisan octane:start on 127.0.0.1 as a background process, points Nginx at that port and adds php artisan octane:reload to the deploy script.

Reverb#

Asks only for a Port (default 8080). SrvYard runs php artisan reverb:start on 127.0.0.1, lets Nginx forward /app and /apps to it so clients connect through the site's own HTTPS, and adds php artisan reverb:restart to the deploy script. Nothing needs opening in the firewall. Set REVERB_PORT=443 and REVERB_SCHEME=https in the .env for browsers.

Inertia SSR#

Creates a process that runs php artisan inertia:start-ssr. The dialog has one switch, Stop SSR on every deployment, which adds php artisan inertia:stop-ssr to the deploy script so the new bundle is loaded.

3. Use maintenance mode#

Maintenance mode runs php artisan down on the server, so visitors get Laravel's 503 page until you bring the site back.

1. Secret (optional). Letters, digits, - and _, up to 64 characters. When set, you can open https://your-site.example/your-secret once to get a cookie that lets you keep using the site while everyone else sees the 503 page.
2. Generate. Fills the field with a random secret.

Press Go into maintenance to confirm. The switch then shows the state, and if a secret is set the card shows the bypass path. Turn the switch off to run php artisan up. Both actions are queued and take a few seconds.

Troubleshooting#

• Everything is disabled and the card says "Could not read the application". SrvYard could not reach the server or read composer.lock. Check the server's state on its page, then press Detect again.
• "laravel/horizon is not in this app's composer.lock" although you installed it. The deployed code does not have it yet, or the card is showing older data. Deploy, then press Detect again.
• "Deploy the site once to detect Horizon, Octane and the rest." There is no deployed composer.lock to read. Run a deployment.
• Octane is refused on a zero-downtime site. This is by design. Create the site with the in-place strategy if you need Octane.
• "Port N belongs to another service" or "is already used by ...". Pick another port for Octane or Reverb, between 1024 and 65535. Ports used by databases, Redis and PHP-FPM (3306, 5432, 6379, 9000 and a few more) are never accepted, and neither is a port another feature of a site on the server uses.
• The scheduled tasks do not run. Check the scheduler switch is on and the job is Installed under Scheduled jobs on the Processes tab. Add a heartbeat on the Observe tab to be told when the minute tick stops.
• Horizon or a worker keeps using old code after a deploy. The restart line may have been removed from the deploy script. Turn the feature off and on again to put it back.

Related#

• Queue workers and the Laravel scheduler: plain queue workers and the cron job in detail.
• Background processes for a site: start, stop and read the logs of what the switches create.
• Write and test a deploy script: where the restart lines are added.
• Edit environment variables: set the Reverb and queue values.