Docs menu
Deploying Laravel
Deploy a Laravel app on Primcloud: Procfile shape, required env vars, config caching, migrations, and the framework-specific gotchas.
On this page
Laravel deploys like any other PHP app. The Laravel-specific work is setting the document root and APP_KEY, choosing where migrations run, and using session, cache, and log drivers that don't rely on the local disk.
Starter template#
A new Laravel app needs only a Procfile to deploy. To create one:
composer create-project laravel/laravel my-app
cd my-app
git init -b main
git add .
git commit -m "Initial Laravel scaffold"
Push it to a repo you've connected to Primcloud, then import it as in Getting started with PHP.
Procfile for Laravel on Primcloud#
Laravel serves from public/. The smallest Procfile is one line:
web: heroku-php-nginx public/
Or, if you prefer Apache with PHP-FPM:
web: heroku-php-apache2 public/
If your app runs queued jobs, add a worker:
web: heroku-php-nginx public/
worker: php artisan queue:work --tries=3
Each line becomes its own formation, scaled separately.
Env vars this framework expects#
Set these as secrets before your first deploy:
| Variable | Value | Purpose |
|---|---|---|
APP_KEY |
base64:... from php artisan key:generate --show |
Encryption key for sessions and encrypted casts. Laravel refuses to boot without one. |
APP_ENV |
production |
Enables production optimizations, disables debug pages. |
APP_DEBUG |
false |
Never true on a deployed app; it leaks stack traces and env values. |
APP_URL |
https://your-app.primcloud.app |
Used for absolute URLs in mail, signed URLs, and Sanctum stateful auth. |
LOG_CHANNEL |
stderr |
Ships logs to stdout/stderr so they appear in the Logs page. See below. |
SESSION_DRIVER |
database or redis |
The default file driver writes under storage/framework/sessions, which is ephemeral. |
CACHE_STORE |
database or redis |
The default file cache doesn't survive a deploy or a restart. |
QUEUE_CONNECTION |
database or redis |
Required if you're running the worker process above. |
DB_* |
Your database connection details | Set the full DB_HOST / DB_PORT / DB_DATABASE / DB_USERNAME / DB_PASSWORD group, or a DATABASE_URL if you prefer. |
Generating APP_KEY. Run this locally, then paste the output as the value for APP_KEY:
php artisan key:generate --show
Framework gotchas on Primcloud#
Config, route, and view caches. Build Laravel's caches when your web process starts, before the server:
web: php artisan config:cache && php artisan route:cache && php artisan view:cache && php artisan event:cache && heroku-php-nginx public/
Don't cache them during the build. config:cache stores your secrets' values, and saving a secret redeploys your app without rebuilding it, so a config cached at build time keeps the old values. Cached at startup, it always has the current ones.
Front-end assets. After Composer, Primcloud installs your JavaScript dependencies and runs the build script in package.json (vite build in a new Laravel app), so vendor/ is in place when it runs. Commit the lockfile for your package manager: package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lock. The built files in public/build/ are served with no extra config. See Customizing the build.
Migrations. Don't run php artisan migrate in a Composer script, which runs during the build, before your new code is released, or in the web command, which runs on every start of every copy of web. Run migrations in one of two places.
A release process runs once per deploy, after the build and before the new version takes traffic:
web: php artisan config:cache && php artisan route:cache && php artisan view:cache && php artisan event:cache && heroku-php-nginx public/
release: php artisan migrate --force
worker: php artisan queue:work --tries=3
If it exits non-zero or runs past its time limit, the deploy stops and the new code never goes live. Its output is in the deployment's release log.
Or run the migration as a task:
php artisan migrate --force
A task suits a migration you want to run on your own schedule, like a large backfill or a one-time data fix.
The local disk doesn't persist. Every restart or deploy starts from a fresh copy of your build, so files written to storage/app/, storage/framework/, and storage/logs/ are lost. Use an S3-compatible bucket for uploads (FILESYSTEM_DISK=s3), a database or Redis for sessions and cache, and stderr for logs.
Logging. Set LOG_CHANNEL=stderr, or use a channel that writes to php://stderr, so your logs appear in Logs. Anything written to storage/logs/laravel.log is never shown.
Trusted proxies. Primcloud handles HTTPS in front of your app and passes the original request details in X-Forwarded-* headers. Laravel has to trust them to detect HTTPS and build correct URLs. In app/Http/Middleware/TrustProxies.php (or its equivalent in newer Laravel versions), set:
protected $proxies = '*';
Without this, url() helpers return http:// links even for HTTPS requests.
Troubleshooting#
No application encryption key has been specified.: APP_KEY isn't set. Generate one with php artisan key:generate --show locally and add it as a secret.
SQLSTATE[HY000] [2002] Connection refused right after deploy. The app can't reach its database. Check DB_HOST and DB_PORT, and that your database accepts connections from outside its own network.
Assets 404 in production but load locally. The assets weren't built. Check that package.json has a build script, that its lockfile is committed, and that the build log shows the asset build producing public/build/manifest.json.
Session data disappears between requests. With SESSION_DRIVER=file, sessions live on local disk and are lost on restart, and aren't shared when web runs more than one copy. Switch to database or redis.
Migrations silently didn't run. Nothing migrates your database on its own. Add release: php artisan migrate --force to your Procfile, or run it as a task.
Queued jobs never process. Formations other than web start with Instances at 0. Scale your worker formation to at least 1; see Formations.