Deploy Laravel to a VPS with a queue and scheduler

To deploy Laravel to a VPS with ox, add the ox.toml below to your repo, set APP_KEY and the other variables, and deploy. ox installs PHP and Composer from Ubuntu's packages and builds your assets with Vite. Each deploy takes a database snapshot, then runs php artisan migrate --force. The queue worker and the scheduler run beside the app. ox's real-server tests deploy a plain PHP app this way, but no Laravel app yet.

What ox detects in a Laravel repo

A Laravel repo always needs an ox.toml with [storage] keep, because Laravel writes to storage while it runs. Without one, ox check stops with Laravel writes storage/ at runtime, which is read-only in a release. ox knows a repo is Laravel when it has artisan and a composer.json that requires laravel/framework.

Inside your ox.toml, ox fills in what you leave out:

• PHP, Composer and the extensions your composer.json and composer.lock require, from Ubuntu's packages.
• The install composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader, followed by your lockfile's npm ci --include=dev.
• Your build script.
• The migrate step php artisan migrate --force.
• The health page your bootstrap/app.php names with health:. That is /up in Laravel 11 and later.

With no [app] start, ox proposes one that serves public with FrankenPHP. No real-server test covers that yet. The ox.toml below lists PHP's packages and runs your app with PHP's built-in web server, the same one php artisan serve uses. If you set a start and packages has no PHP, ox check says so.

The ox.toml for Laravel

Put this file at the root of your repo, next to artisan. Change the domain to yours.

domains  = ["example.com"]
packages = ["php-cli", "php-mbstring", "php-xml", "php-curl", "php-zip", "php-intl", "php-bcmath", "php-pgsql", "unzip", "composer"]

[app]
start  = "cd public && exec php -S 127.0.0.1:$PORT ../vendor/laravel/framework/src/Illuminate/Foundation/resources/server.php"
health = "/up"

[build]
install  = "composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader && npm ci --include=dev"
commands = ["npm run build", "php artisan config:cache", "php artisan route:cache"]
migrate  = "php artisan migrate --force"

[workers]
queue = "php artisan queue:work --tries=3"

[cron]
scheduler = { schedule = "* * * * *", run = "php artisan schedule:run" }

[services]
postgres = {}

[storage]
keep = ["storage"]

[tools]
node = "24"

What each key does:

• domains is the name Caddy serves your app on, with HTTPS.
• packages installs PHP, the extensions Laravel needs, and Composer from Ubuntu.
• [app] start runs PHP's built-in web server from public, on the port ox gives it.
• [app] health is Laravel's built-in /up page, which must answer before your app gets traffic.
• [build] install installs your PHP and JavaScript packages.
• [build] commands builds your CSS and JavaScript, then caches the config and routes.
• [build] migrate runs your migrations after ox takes a snapshot of the database.
• [workers] queue runs the queue worker as its own process next to the app ([workers]).
• [cron] scheduler runs Laravel's scheduler every minute ([cron]).
• [services] postgres gives your app its own PostgreSQL database.
• [storage] keep makes storage writable and keeps it across deploys, because a PHP release's own files are read-only while it runs. Each deploy copies in any folder or file your repo ships under storage that the kept folder does not have yet, such as storage/framework/views. It never overwrites what your app wrote.
• [tools] node installs Node.js for the Vite build.

When the repo has storage/app/public, ox's detected build links it to public/storage, as php artisan storage:link does. Files on Laravel's public disk are then served at /storage. A [build] commands list in your ox.toml replaces the detected build steps, this link included. If your app uses the public disk, add ln -sfn ../storage/app/public public/storage to the list.

PHP's built-in server answers one request at a time. Set the variable PHP_CLI_SERVER_WORKERS (for example to 4) to run more at once.

PostgreSQL, MySQL and Redis for Laravel

postgres = {} gives your app DATABASE_URL. Laravel reads its database from DB_CONNECTION and DB_URL instead. When your config/database.php shows the app reads them, ox sets both from the service. Your own value for either one wins.

• For MySQL, use mysql = {} instead. ox gives you MYSQL_URL, served by MariaDB. It sets DB_CONNECTION=mysql and the URL key your config reads: DB_URL, or DATABASE_URL in a Laravel 10 config. ox adds php-mysql to packages for you, as it adds php-pgsql for postgres = {}.
• For Redis, add redis = {}. ox gives you REDIS_URL, which Laravel reads as is. Add php-redis to packages.

APP_KEY, the .env values and trusted proxies

Set each value on the dashboard's Variables tab, or with ox vars set, which asks for the value so it never lands in your shell history. ox never reads your .env file.

APP_KEY=base64:...            # from php artisan key:generate --show
APP_ENV=production
APP_DEBUG=false
APP_URL=${PUBLIC_URL}
LOG_CHANNEL=stderr

Make the APP_KEY on your own computer with php artisan key:generate --show, then run ox vars set <project> APP_KEY and paste it. ${PUBLIC_URL} points at a value ox provides. LOG_CHANNEL=stderr sends Laravel's log to ox logs.

Every key in your .env.example with an empty value, a secret name or a placeholder needs a value before the first deploy, even an empty one. A key with a real value (APP_DEBUG=false) keeps Laravel's own default.

The config cache is made during the build, so a changed variable needs a new deploy. Save & deploy on the Variables tab does that.

How ox sets the database keys

Laravel 11 never reads DATABASE_URL. So with postgres or mysql in [services], ox sets DB_CONNECTION and the key your config/database.php reads the URL from: DB_URL, or DATABASE_URL in a Laravel 10 config. ox reads that file and skips what it already covers. It skips DB_CONNECTION when the file defaults it to pgsql (or mysql). It skips the URL key when the connection's url falls back to the URL ox provides: env('DATABASE_URL') for postgres, env('MYSQL_URL') for mysql.

If your .env.example lists DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME and DB_PASSWORD, ox sets them from the service too, and ox check lists them under "From postgres". ox asks you for any other key whose value names your own machine, such as localhost.

Trusted proxies

Caddy sits in front of your app. Tell Laravel to trust it, so links and redirects use HTTPS:

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustProxies(at: '127.0.0.1');
})

Check and deploy the Laravel app

Run ox check in the repo. It works offline and lists the plan, then the variables to set, then Ready to deploy. Below are its last lines for ox's own Laravel test app, with the ox.toml above and a stock Laravel 11 config/database.php. Your .env.example decides which keys it asks for. Your config/database.php decides which keys come from postgres.

  Provided by ox: PORT, HOST, OX_ENV, OX_PROJECT, OX_RELEASE, OX_DATA_DIR, PUBLIC_URL, PUBLIC_HOST, PUBLIC_SCHEME, PUBLIC_PORT, DATABASE_URL
  From postgres (a value of yours replaces one): DB_CONNECTION, DB_URL
  Set on the dashboard before the first deploy: APP_KEY (App key: base64: and 32 random bytes, Generate makes it)
  hint: [build] commands replaces the detected build step "ln -sfn ../storage/app/public public/storage" (from artisan); add it to the list if the release still needs it
  hint: the example file's 1 key with a real value (APP_NAME) is not asked and not copied, so the app sees it unset: set on the Variables screen any the app reads with no default of its own

Ready to deploy.

Then ship it and watch the app's log:

ox check
ox deploy <project> --wait
ox logs <project> --follow

If the Laravel deploy fails

• set these before deploying: APP_KEY. A key from .env.example has no value. Set it with ox vars set <project> APP_KEY and deploy again.
• Read-only file system in the app's log for a path under storage. storage is missing from [storage] keep. Add it as in the file above.
• GET http://127.0.0.1:<port>/up did not answer within 120s. The app did not answer on its health page. Laravel 10 and older have no /up page. Add a route that returns a 200, or point health at a page you have.

If an older release is live, it keeps serving while you fix any of these. Troubleshooting explains each message, and the config reference lists every key.

Next steps

• Set APP_KEY and the other variables from the dashboard or the CLI.
• Add your own domain with HTTPS: one A record, and Caddy gets the certificate.
• Read and search the app's logs, live or for a time range.
• Roll back a bad deploy to a kept release without a rebuild.
• See the daily PostgreSQL backups and restore one.