The platform hands every container its settings as environment variables,
under the names Laravel already reads: DB_CONNECTION, DB_HOST, DB_PORT,
DB_DATABASE, DB_USERNAME and DB_PASSWORD. When the stack runs Valkey or
Redis, it adds REDIS_HOST and REDIS_PORT.
What you set yourself
A committed .env applies to every environment the code is deployed to, so
do not commit one. Commit .env.example as usual.
The platform does not set two variables, and Laravel will not start without the first:
-
APP_KEY. Set it on the environment as a secret variable under Variables. Or derive it inconfig/app.phpfromVALLIC_ENTROPY, which is generated once per environment and never changes:'key' => env('APP_KEY') ?: (getenv('VALLIC_ENTROPY') ? 'base64:' . base64_encode(substr(hash('sha256', getenv('VALLIC_ENTROPY'), true), 0, 32)) : null), -
APP_URL. The environment's own address isPROJECT_BASE_URL, so'url' => env('APP_URL', env('PROJECT_BASE_URL', 'http://localhost'))inconfig/app.phpsaves setting it twice.
Bootstrap: two things to add
Add these lines to bootstrap/app.php, before Application::configure():
// The platform's variables, where env() can see them. Laravel reads $_ENV and
// $_SERVER, and PHP's command line leaves both empty of the environment — so
// without this a deploy step or a cron job sees no DB_HOST at all, and
// `artisan migrate` quietly falls back to Laravel's defaults.
foreach (getenv() as $name => $value) {
$_ENV[$name] ??= $value;
$_SERVER[$name] ??= $value;
}
// Compiled config and routes somewhere writable. The release is mounted
// read-only, so bootstrap/cache cannot be written and `config:cache` fails.
// Per release, so a rollback does not run the configuration of the release
// it rolled back from.
$compiled = (getenv('VALLIC_PRIVATE_DIR') ?: dirname(__DIR__) . '/private')
. '/bootstrap/' . basename(dirname(__DIR__));
if (!is_dir($compiled)) {
@mkdir($compiled, 0775, true);
}
foreach ([
'APP_CONFIG_CACHE' => 'config.php',
'APP_ROUTES_CACHE' => 'routes.php',
'APP_EVENTS_CACHE' => 'events.php',
'APP_SERVICES_CACHE' => 'services.php',
] as $variable => $file) {
$_ENV[$variable] = $_SERVER[$variable] = $compiled . '/' . $file;
putenv($variable . '=' . $compiled . '/' . $file);
}
The packages manifest stays in bootstrap/cache: composer install writes it
during the build.
The manifest
version: 1
type: laravel
runtime:
php: '8.4'
services:
- mariadb: '11.8'
- valkey: '8'
# Only for the asset build below; nothing of it runs beside the site.
- node: '24'
build:
# Composer's and npm's downloads are cached for you. What Composer installs,
# and Vite's own cache, are not.
cache:
- vendor
- node_modules/.vite
steps:
- composer install --no-dev --optimize-autoloader
# The PHP image has no npm, so the assets build in the Node image.
- name: Assets
image: node
run: npm ci && npm run build
deploy:
steps:
# storage/framework is kept outside the release and starts empty, so the
# directories your repository ships there are not the ones Laravel sees.
- 'mkdir -p storage/framework/cache/data storage/framework/sessions storage/framework/views'
- 'php artisan migrate --force'
- 'php artisan config:cache'
- 'php artisan route:cache'
- 'php artisan view:cache'
on_failure: rollback
health:
path: /up
workers:
- name: queue
command: 'php artisan queue:work --sleep=1 --tries=3'
replicas: 2
cron:
- name: scheduler
schedule: '* * * * *'
command: 'php artisan schedule:run'
A database cannot be added or changed from a commit. The database named
under services has to be the one the environment was created with, or the
deploy refuses. A service such as Valkey or Node is started by the next deploy
if the environment does not run it yet.
Each name needs a version after it. The environment runs that version from the next deploy, so read Service upgrade before you change one that keeps data.
The scheduler
With no cron declared, the platform runs schedule:run every five minutes.
On that default an everyMinute() task runs every five minutes. A task at a
minute that is not a multiple of five, such as dailyAt('13:32'), never runs.
If you need either, declare the scheduler every minute, as in the manifest
above. Declaring any cron replaces the platform's job.
The schedule runs on one machine only, however many web servers the environment has, so a task is never started twice.
If you run the scheduler as a worker instead, with
php artisan schedule:work, the platform adds no cron for it. Each copy of
the scheduler starts every task, so do that only where one machine runs your
workers. On the dedicated shape, every web server, or every worker machine,
runs each worker: see Workers.
Where migrations run
Run php artisan migrate --force in deploy.steps. Keep --force: Laravel
refuses to migrate in production without it.
It runs on the machine, after the release is live: a build has no database. Nothing runs here unless you list it. On more than one web server the steps run once, on one of them.
The caching commands go after the migration, in the manifest's order:
config:cache first.
A committed config cache freezes the wrong environment's values: never cache config locally and commit the result.
/up is the health route Laravel ships. With health set, a deploy waits for
it to answer before it counts as done. on_failure: rollback puts the
previous release back if it never answers.
After a backup is restored, the platform runs php artisan optimize:clear, so
nothing cached from the replaced database is served. That clears the config
and route caches too; the next deploy builds them again.
The queue
Run queue:work, not queue:listen. Run it as a worker, not as cron: the
platform keeps a worker running and restarts it if it stops. Cron would start
a new one every minute on top of the last.
Workers are restarted on deploy, so you do not need queue:restart.
Sessions, cache and storage
Set CACHE_STORE and SESSION_DRIVER to redis on the environment, under
Variables. The stack's Valkey answers on REDIS_HOST and
REDIS_PORT, the names config/database.php already reads. Without Valkey,
SESSION_DRIVER=database works as well.
A restart signs everybody out and drops queued jobs, because Valkey keeps
nothing on disk by default. With sessions or a queue in it, set
VALKEY_PERSISTENCE: store on the service in vallic.yaml: see
Keeping its data.
With more than one web server, keep sessions in Valkey. Laravel's default,
file, keeps them in storage/framework, which the platform shares between
machines over the network. On every machine but one, each request then reads
and writes its session over the network.
Four paths inside your code are linked out of the release, so they survive every deploy:
| In your code | Kept as |
|---|---|
public/storage |
VALLIC_PUBLIC_DIR — served |
storage/app |
VALLIC_PRIVATE_DIR — never served |
storage/logs |
a directory under the private one |
storage/framework |
a directory under the private one |
Everything else in the release is read-only while the site runs.
public/storage is already linked, so you do not need storage:link.
Laravel's public disk writes to storage/app/public by default, which is
inside the private directory and not served. Point it at the public one:
// config/filesystems.php
'public' => [
'driver' => 'local',
'root' => env('VALLIC_PUBLIC_DIR', storage_path('app/public')),
'url' => env('APP_URL').'/storage',
'visibility' => 'public',
],
Logging
Laravel's daily channel writes to storage/logs. That directory survives
deploys, but nothing collects it: its lines never reach the console's logs or
a destination you forward to.
Point it at VALLIC_LOG_DIR instead. The variable is set in every container,
and its directory survives every release:
// config/logging.php
'daily' => [
'driver' => 'daily',
'path' => env('VALLIC_LOG_DIR', '/var/log/app') . '/laravel.log',
'level' => env('LOG_LEVEL', 'debug'),
// Rotate, and the platform's limit never comes up.
'days' => 7,
],
The fallback in env() lets the same config work on your laptop, where the
variable does not exist.
Then set LOG_CHANNEL=daily on the environment, under
Variables.
Anything in that directory is collected with the rest of your logs and kept on the machine for a week. It is forwarded if you have set up a destination. There is a size limit: see Logs.
Next
Thank you. Good to know it helped.
Thanks — tell us what was missing. Open a ticket from Support in the console, and we answer on the ticket. Open the console