Skip to main content
Open console

Laravel

The manifest, where migrations run, and the few lines Laravel needs to read the environment.

7 min read

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 in config/app.php from VALLIC_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 is PROJECT_BASE_URL, so 'url' => env('APP_URL', env('PROJECT_BASE_URL', 'http://localhost')) in config/app.php saves 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

  • Logs — where your output goes and how to send a copy on
  • Variables — everything available to read
  • Storage — what survives a deploy, and what does not