Deploying

Processes and release commands

Run a queue worker, a scheduler or any other long-running command beside an app's web replicas, from the same image, and a release command (migrations, say) once before each deploy rolls out.

Processes

Besides its web replicas, an app can run processes: a queue worker, a scheduler, anything long-running from the same image. Each has a name (lowercase letters, digits and dashes, not web), a command and replicas (0 to 64; 0 stops it at the next deploy). GET/PUT /api/apps/{id}/processes reads and replaces them, with the release command; like the image, changes apply at the next deploy.

A process's replicas get the app's image, variables, database links and volume mounts, but no port, domains or route. They count as up while they keep running (after a few seconds), and are restarted if they exit. The image's own health check is turned off for them, since it checks the web process, which they don't run.

The command is split like a shell would split it and handed to the image's entrypoint, like Compose's command:, so the entrypoint's setup still runs. For pipes or &&, write sh -c '…'.

A process can also serve requests: with a port and paths, requests to the app's domains under those paths go to it, WebSockets included (Laravel Reverb at /app and /apps), ahead of the app's web replicas for those paths. Such a process runs beside every web replica, one per server, rather than on replicas servers; without domains it runs unrouted.

A deploy places the web replicas and every process's in one batch, so the batch page and rollbacks cover them all. A retry redeploys that replica on its server; a rollback puts the earlier image on the web replicas and every process.

Release command

Runs once per deploy, before anything is replaced: sh -c in a one-shot container with the new image and the app's variables, able to reach the app's databases, for up to 15 minutes. The deploy's replicas wait meanwhile.

  • It succeeds: the deploy rolls out.
  • It fails (non-zero exit, timeout, the server disconnecting): every replica of the deploy is marked failed with the error line of its output, and nothing is replaced; what ran before keeps running. The deploy's page shows the output. Retrying replicas there is offered only when the release command didn't fail, since a retry skips it.

Each run is kept with its deploy (GET /api/apps/{id}/releases), with its exit code and the last 64 KiB of output.

Retries and rollbacks don't run it. A rollback's older code then runs on the schema the newer one migrated, so keep migrations additive (as Laravel's should be) and the older version keeps working.

Laravel

The Laravel template builds the app from your repo (Builds) with the laravel build template, unless the repo has a Dockerfile. It always makes:

  • the web replicas, and the release command php artisan migrate --force;
  • APP_KEY (random, kept);
  • DB_* from the database link, with DB_CONNECTION from the engine picked (MySQL mysql, PostgreSQL pgsql);
  • with Redis linked, REDIS_* and the cache, sessions and queue in it (without, Laravel's defaults keep them in the database).

A domain, if given, is added to the app and is its APP_URL. A volume at storage/app (uploads and the public disk, linked at public/storage) is optional.

Object storage is optional too: linked (an existing store, or a new one), the app gets a bucket and key of its own and Laravel's s3 disk is set up and made the default: FILESYSTEM_DISK=s3, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_BUCKET, AWS_ENDPOINT, AWS_USE_PATH_STYLE_ENDPOINT=true, and AWS_URL for Storage::url(): the bucket on the store's public domain once it's published (until then its internal address, which browsers can't reach). The app needs league/flysystem-aws-s3-v3. Without the link, none of these are set.

Options, chosen in the New app form:

Option Choices What it does
Web server Nginx · Octane Nginx: nginx and PHP-FPM 8.5 in one container (any other command, like a process's, runs as it is). Octane: the laravel-octane build template, FrankenPHP (PHP 8.5) running octane:start on port 8000, OCTANE_HTTPS so URLs are https behind the proxy. The app needs laravel/octane; the build stops with that message if it hasn't.
Queue Worker · Horizon · None Worker: queue:work. Horizon: php artisan horizon (needs Redis, and laravel/horizon). None: QUEUE_CONNECTION=sync.
Scheduler On · Off schedule:work, one replica.
Reverb Off · On reverb:start on 8080, routed at /app and /apps on the domain beside every web replica; BROADCAST_CONNECTION=reverb, REVERB_* (random id, key and secret; the domain on 443 over https) and VITE_REVERB_* for Echo. Needs the domain, laravel/reverb, and with more than one replica Redis (REVERB_SCALING_ENABLED).

Some choices need a database linked (Horizon needs Redis; Reverb needs it with more than one replica) or an input given (Reverb needs the domain); the form and the API say what's missing. Variables may name each other (${{NAME}}), and chains are followed: VITE_REVERB_HOST → REVERB_HOST → APP_DOMAIN.

Vite bakes VITE_* variables into the assets at build time, so a build gets the app's VITE_* variables (and PUBLIC_* and NEXT_PUBLIC_*, for Astro and Next.js): they're written to .env.production.local in the build context (the file vite build and next build read) and passed as build arguments.

nginx passes HTTPS on to PHP from the proxy; logs go to stderr, where the Logs tab reads them (Logs). A template app is built first; it deploys once built and, if it waits for new databases, once they're linked, whichever comes last.