Deployment

Getting your Leaf app live should be as simple as building it. This guide walks you through setting up your server, configuring URL rewriting, and making sure your app runs well in production, whether you're deploying to shared hosting, a VPS, or a platform like DigitalOcean or Vercel.

Production Checklist

Before deploying your app, make sure you’ve covered the following:

• Environment Variables: Set up your environment variables for production.
• Debug Mode: Turn off debug mode so errors aren't rendered to your users.

These are meant to ensure your app runs smoothly in production, without exposing sensitive information or running unnecessary debugging tools.

URL Rewriting

URL rewriting maps all requests to a single entry point (usually index.php) so Leaf’s router can handle them dynamically. Instead of serving files directly, web servers like Apache and Nginx can be configured to route all traffic through your app, so Leaf can handle every request.

Nginx nginx.conf

try_files $uri /index.php?$query_string;

Apache .htaccess

RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule . index.php [L]

Without this, things like routing, request handling, and error pages won’t work as expected. Make sure to set up URL rewriting correctly on your server to ensure your Leaf app runs smoothly.

One-command deploys

For Fly.io and Render, Leaf CLI prepares (and where possible runs) the whole deployment for you:

php leaf deploy              # deploy to Fly.io
php leaf deploy --to render  # prepare a Render deployment

The command writes a production Dockerfile plus the provider's config into your project. It works for both full Leaf MVC apps and single-file Leaf apps, pointing the web server at the right place for each and keeping your .env, vendor and composer files out of the browser's reach. Because the Dockerfile is provider-agnostic, you can also take it to any other platform that deploys Docker images.

See the guides below for the details of each provider.

Deployment Guides

Okay, now let’s get your app live! 🚀

Provider	Description
Fly.io	One-command deploys with php leaf deploy
Render	Free-plan git-based deploys, prepared by the Leaf CLI
Digital Ocean	Deploying LeafMVC projects to a new Digital Ocean droplet
Heroku	Deploying a base Leaf project to Heroku using the Leaf CLI

Deploying Vite/Inertia Apps

If you’re using Vite and Inertia.js, the process is pretty much the same as deploying a regular Leaf app. However, you’ll need to build your assets before deploying to production. Here’s how you can do that:

NPM

npm run build

Yarn

yarn build

PNPM

pnpm run build

Build before you deploy

If you don't build your assets before deploying, you will either have a fully broken app or a CORS error in the case of Inertia.js, so make sure to build your assets before deploying or add it to your deployment script.

Deploying Queues/Workers

When deploying your application with queues, Leaf takes care of setting up the necessary files and commands based on your chosen queue driver. However, once deployed, you’ll need to set up your server to keep your workers running continuously.

For smaller applications, you can keep the queue worker running in the background with:

php leaf queue:work &

This command will set up your queue and start a worker to process jobs. Leaf includes safeguards to prevent excessive memory usage, long-running processes, or crashes from failed jobs.

However, for larger applications, this setup may not be enough. In such cases, using a process manager like Supervisor is recommended to ensure your workers run smoothly and restart automatically if needed:

sudo apt update && sudo apt install supervisor -y

Create a new configuration file for your Leaf queue worker:

sudo nano /etc/supervisor/conf.d/leaf-queue.conf

Add your Supervisor configuration:

[program:leaf-queue]
process_name=%(program_name)s_%(process_num)02d
command=php leaf queue:work
autostart=true
autorestart=true
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/leaf-queue.log

Save and exit, then update Supervisor and start the worker:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start leaf-queue

This will start a worker that will process jobs in the queue. You can check the status of the worker using the following command:

sudo supervisorctl status leaf-queue

And that's it! Your worker is now running and processing jobs in the queue.