Deploy guide · runtime = "docker"

Deploy Laravel (PHP) on Percher

Laravel is PHP's mature fullstack framework — Eloquent ORM, Blade templates, queues, scheduler, broadcasting. The Percher template ships a minimal PHP 8.3 starter; you can upgrade to full Laravel by running `composer create-project laravel/laravel .` in the project root.

Why Percher fits

PHP-FPM in front of Caddy is a well-trodden pairing — no platform-specific gotchas.
Use an external Postgres (Neon, Supabase, your own) or MySQL via `DATABASE_URL`; for lighter weight, opt into the managed PocketBase sidecar with `[data] mode = "pocketbase"`.

Quick start

bunx percher create my-app --template laravel
cd my-app
bunx percher publish

The first command scaffolds a working Laravel (PHP) project plus a `percher.toml`. Publish builds and deploys it; the live URL prints on completion.

percher.toml

The canonical config for a Laravel (PHP) app on Percher. `bunx percher init` generates this automatically when it detects Laravel (PHP) in your project.

[app]
name = "my-app"
runtime = "docker"
framework = "laravel"

[web]
port = 8080
health = "/"

Common gotchas

Percher doesn't provision a managed Postgres or MySQL today. Set `DATABASE_URL` (or Laravel's individual `DB_*` env vars) via `bunx percher env set` and point at any external provider.
Laravel's `php artisan migrate` should run as part of your container entrypoint, not the build step — it needs `DATABASE_URL` which is set at runtime, not build time.
`storage/` and `bootstrap/cache/` must be writable. Confirm the Dockerfile chowns them to the runtime user.
Set `APP_KEY` via `bunx percher env set APP_KEY=$(php artisan key:generate --show)` before the first deploy.

Related docs

Ready to deploy Laravel (PHP)?

Free plan, no credit card. Live in under a minute.

← Browse all deploy guides