Skip to main content
Open console

Configuration

Every key vallic.yaml takes, what each one does, and what a deploy refuses.

15 min read

vallic.yaml sits at the root of your repository. It is required: a deploy without one fails, naming the file.

A complete example

version: 1
type: drupal

runtime:
  php: '8.4'
  memory_limit: 256M

services:
  - mariadb: '11.8'
  - valkey: '8'
  - solr:
      version: '9'
      environment:
        SOLR_HEAP: 1g

build:
  steps:
    - composer install --no-dev --optimize-autoloader
  cache:
    - vendor
    - web/core
    - web/modules/contrib
    - web/themes/contrib

mounts:
  - private/exports

cron:
  - name: nightly-import
    schedule: '0 3 * * *'
    command: 'drush queue:run import'

workers:
  - name: queue
    command: 'while true; do drush queue:run heavy --time-limit=300; sleep 30; done'
    replicas: 2

deploy:
  steps:
    - 'drush deploy'
  on_failure: rollback

health:
  path: /health
  timeout: 120

env:
  required:
    - SENDGRID_API_KEY

What goes here, and what does not

Application facts live here. Build steps, cron, the health path, the PHP version. They change with your code, in the same commit, and roll back with it.

Infrastructure is chosen in the console. How big a machine is, which region it sits in, which services are provisioned.

Services are declared here and started for you. Name a cache, a search engine or a queue under services and the next deploy starts it.

env.required provisions nothing. It names variables you cannot start without, and the values live in the console.

Every key

Key What it is
version The manifest format. 1.
type What the application is: drupal, wordpress, laravel, symfony, php, nodejs (or node), golang (or go), python (or flask, fastapi), django, ruby (or rails, sinatra, hanami), rust, static (or html). It has to agree with the language your project runs; see below.
runtime Which language version to run, and its settings.
start The command that serves. Node, Go, Python, Ruby and Rust only: PHP-FPM is the process for every PHP framework, and nginx for a static site. Required for Go; Node falls back to npm start, Bun to bun run start, Python to python -m gunicorn, Ruby to bundle exec puma, Rust to bin/server.
port What that command listens on. Defaults to 3000 for Node and Ruby, 8080 for Go and Rust, and 8000 for Python. Setting it moves both the PORT handed to your app and the port the platform reaches. Not read for PHP or a static site.
services What runs beside the application.
build steps to make the artifact, and cache to carry between builds.
deploy steps to run once the release is live, and on_failure.
workers Long-running processes the platform keeps up.
cron Scheduled commands.
mounts Directories that outlive a release.
backup exclude: paths to leave out of the files backup.
health How the platform decides the site is answering.
env Variables the deploy refuses without.
frontend A Node.js or Bun application beside your backend, in beta. See Multi app.

Any other key is refused: a typo fails the deploy, which says so.

services

Every service you depend on, with the version your code was written against. The version is required, and it is the version that runs from the next deploy, matched to its current build the way a runtime version is.

A service that keeps data does not always survive a version change: a database, a search engine, the queue. Read Service upgrade first.

services:
  - mariadb: '11.8'          # a bare value is the version
  - solr:
      version: '9'
      environment:
        SOLR_HEAP: 1g

Under a service name only version and environment are understood. Anything else is reported by name when the file is read.

Name only services this platform runs, and only ones that fit your application's runtime. The service names are the ids in Software stacks: mariadb, mysql, postgres, valkey, redis, memcached, solr, meilisearch, influxdb, rabbitmq, vinyl (Vinyl Cache, formerly Varnish), node (Node.js for builds), and the web bundle's own php, nginx and opensmtpd when you want to give them settings, or a static site's static. Named by a Node.js, Go, Python, Ruby or Rust project, nginx is put in front of the application, which has none otherwise: see Nginx.

Which variables you may set is per image, and most images allow none. Each service's page says what it allows: see Software stacks.

A service you name is started on the next deploy, and the deploy waits for it. Naming one you already run changes nothing. Deleting a line does not delete a container.

Naming a different cache or search engine replaces the one running. What is lost is an index that reindexes or a cache that warms up.

A deploy switches your database only while nothing is in it. Until the environment's first release, with nothing restored or synced into it, a deploy switches to the database the file names. The old one's files stay on the machine, unused. After that, a file naming a different database refuses the deploy and tells you to contact support: moving one is a migration. A deploy never switches between MariaDB and MySQL, which keep their files in the same place. A deploy does not add a database to an environment created without one.

The console's Resources tab on each environment shows what is running, which version, and which of them your vallic.yaml asked for.

type, and the project it runs in

type does not pick your stack. The project type you chose in the console does that, and decides the Nginx configuration, the default cron and the directories kept between releases.

type is checked for the language. A nodejs repository on a project whose machines run PHP has no npm to run its build steps. The platform refuses that build, and says so on the project page before you push.

The language is chosen when the project is bought. You can change it for as long as nothing has deployed: Configuration → Project → Change, where Application sits beside the name. The containers are rebuilt on the next reconcile, within the minute. Once a release is serving, changing it is a migration: ask support.

build

Commands run when the artifact is made, each in its own container on a build machine. Install dependencies and compile assets here.

build:
  steps:
    - composer install --no-dev --optimize-autoloader
    - npm ci
    - npm run build

The commands go under steps, not directly under build. A list written straight under build: is refused and says so.

A step can also be a mapping, to name it or to run it in a different image:

build:
  steps:
    - name: Dependencies
      run: composer install --no-dev --optimize-autoloader
    - name: Theme
      run: npm ci && npm run build
      image: node

name is what the build log calls the step. image runs it in another service's image: the PHP image has no Node, so a PHP project whose theme needs it asks for node. The image has to be one your environment runs; node is Node.js for builds. A step naming one the environment does not have is refused, listing what it does have.

A build has at most twenty steps, and twenty-five minutes for all of them.

Nothing is inferred. The platform does not look for composer.json and guess. An empty build means "pack the checkout as it is".

A build has no database and no environment of its own: the artifact it produces can be deployed to staging or production. Anything that touches data belongs in deploy.

build.cache

Composer, npm, yarn, Go, uv and pip are already cached, per project, on every build. There is nothing to declare.

That is the download cache. What a tool installs is not kept: vendor/ is unpacked again on every build unless it is listed. List it for a PHP site: the next composer install then touches only what changed.

build:
  cache:
    - vendor
  steps:
    - composer install --no-dev --optimize-autoloader

A Drupal site adds the directories its installers write modules into: see Drupal. build.cache is also for directories your own build writes and wants back next time:

build:
  cache:
    - .cache/turbo
    - node_modules/.vite
  steps:
    - npm ci
    - npm run build

Paths are relative and must be inside the repository. They are restored before the steps run and kept after, and they are per project.

A build must work with an empty cache: the first build after a machine is replaced has one.

deploy

Commands run on the machine, against the release, after its code is live. Deployments covers the whole sequence around them.

deploy:
  steps:
    - 'drush deploy'
  on_failure: rollback

Database updates go here:

Framework Command
Drupal drush deploy
Laravel php artisan migrate --force
Symfony doctrine:migrations:migrate
Django python manage.py migrate --noinput
Rails bin/rails db:prepare

There is a worked manifest for each framework: Drupal, WordPress, Laravel, Symfony, Node, Go and Rust, Python, Django and Rails.

on_failure: rollback puts the previous release back if a step fails. Worth setting: a migration that fails half-way leaves a site running new code against an old schema.

Each step is given twenty minutes.

runtime

Language settings.

runtime:
  php: '8.4'
  memory_limit: 256M

The version key is the language's: php, node, go, python, ruby or rust, whichever your project runs. It picks the image your application runs on and the one your build steps run in. Leave it out and you get the default: see PHP-FPM, Node.js, Go, Python, Ruby and Rust for what is on offer. A static site's is its server's, nginx: '1.31'.

A Node.js project can run on Bun by writing bun in place of node: bun: '1.4'. Bun then runs the application and its build steps, and Node does not run at all; see Bun. The project type stays nodejs, and Bun is never listed under services.

Pin the version, not the build. Name 8.4 and the platform matches it to the current build, so a security rebuild reaches you without anybody editing a repository. A version that is not on offer runs the default instead.

A Drupal project may also say drupal: '10' or drupal: '11', which picks the matching Nginx configuration. Anything else there is ignored.

memory_limit is PHP's, and it is clamped to what your plan was sold, on a fixed ladder:

Plan memory Largest memory_limit
under 1 GB 96M
1 GB 128M
2 GB 256M
4 GB 512M
8 GB 1024M
16 GB and up 2048M

Asking for more gives you the maximum rather than an error. Leaving it out gives you 256M, or your plan's maximum if that is lower. Drush and cron are not held to it. It is measured against your plan and not the machine.

mounts

Directories that survive a release. The platform already keeps what your framework's convention names: Drupal's public files, a private directory, Laravel's storage. mounts is for anything else your application writes to.

mounts:
  - my_files
  - exports/generated

Each becomes that path at the root of your codebase. Names only: letters, digits, hyphens and underscores, with slashes between them. An absolute path, a .. segment, a dot or whitespace is refused.

A mount cannot be inside another mount: exports and exports/generated together are refused. Everything under a mount is kept already, so list the outer one and use the directory within it.

A mount is not extra storage. It lives on the same disk as everything else in the environment and counts against the same allocation. If you need more room, that is a bigger disk, not another mount.

backup

What to leave out of the files backup, beside the caches the platform already leaves out for Drupal, Laravel and Rails. A Drupal site with a mount of its own:

mounts:
  - reports

backup:
  exclude:
    - reports/drafts
    - web/sites/default/files/backup_migrate
    - private/**/*.tmp

Each path is as your application sees it, from the root of the repository. It must be inside a directory the platform keeps: the framework's own, private, or a mount. * matches within one name and ** across directories. At most 50.

A leading slash, a . or .. segment, whitespace or a backslash is refused. A path in no kept directory is your code, which no backup holds: it is refused too, with the directories it could have named.

A restore leaves these paths as they are, neither put back nor removed. What is left out, and why the caches are not kept, is on Backups.

cron and workers

cron is scheduled work. Declaring any replaces the framework's default, so if you still want that, include it.

Framework Default job
Drupal drush cron, hourly
Laravel schedule:run, every five minutes. None when a worker runs schedule:work, since that would run every task twice
WordPress wp cron event run --due-now, hourly
Plain PHP, Go, Node.js and Python none

Cron runs on one machine however many the environment has: the first worker machine where there is one, and otherwise the machine holding the site's files.

cron:
  - name: nightly-import
    schedule: '0 3 * * *'
    command: 'drush queue:run import'
  • schedule is five fields (minute, hour, day of the month, month, day of the week) or one of @hourly, @daily, @midnight, @weekly, @monthly, @yearly, @annually. A field takes numbers in its range, jan to dec and sun to sat by name, ranges (mon-fri), lists (1,15) and a step after * or a range (*/15, 0-30/10). Not @reboot.
  • command is one line, run by a shell in your application's container.

A job never runs twice at once. When its time comes and its last run is still going, that time is skipped, and the environment's log says so.

A job that does not fit is refused when the commit is validated, by its name.

workers are processes kept running for as long as the environment is up. They run your application's own image on a different command, so anything in your build works.

workers:
  - name: queue
    command: 'while true; do drush queue:run heavy --time-limit=300; sleep 30; done'
    replicas: 2

A worker's name is lowercase letters, digits and hyphens, starting with a letter. replicas is how many copies run, from 1 to 16; leave it out for one. Every machine that runs workers runs all of them. Each is told which one it is in VALLIC_MACHINE (worker-1, worker-2), for a worker that should do different work on each: see Workers.

One worker per machine that can run one, since a worker competes with your site for the CPU that answers requests. An environment has room for as many different workers as it has worker machines. Without any, it has room for as many as it has web servers, and never fewer than one. Declaring more refuses the deploy: add a worker machine or a web server, or fold the work into a worker you already have. See Shapes.

What a worker runs in, what restarts it and each framework's command are on Workers. Drush's queue:run returns once its queue is empty: run it in a loop, as above.

health

A path on your application that answers when it is ready, asked for after the deploy steps have run. Anything from 200 to 399 is healthy. The deploy waits, retrying, until it answers or the timeout runs out. A timeout that runs out fails the deploy, which is what deploy.on_failure: rollback then acts on.

health:
  path: /health
  timeout: 120

The path must be on this application and start with a slash.

The wait is never shorter than 60 seconds. That is also the default when you name a path and no timeout. A smaller number is raised to the floor. Ask for longer when your deploy steps are long.

Name no path and there is no check: the release is good the moment its stack is up.

env.required

Variable names your application cannot start without. Names only: the values live in the console, not in the repository. See Variables. A deploy refuses if one is missing, naming it.

frontend

A Node.js or Bun application in its own directory, deployed with your backend and reached by its own hostname. In beta. Its keys, and what it is given, are on Multi app.

Files beside it

These live in files under .vallic/, not in the manifest:

File What it holds See
.vallic/commands/sanitization.yml A commands: list of one-line commands, at most fifty, run in your application container in order. Runs after data arrives: copied in from another environment, or restored from a backup. Never on production. Backups
.vallic/varnish/recv.vcl, hash.vcl, backend-response.vcl and deliver.vcl Rules added to Varnish's cache policy, when your stack runs it. Vinyl Cache (Varnish)
.vallic/nginx/server.conf and .vallic/nginx/http.conf Rules added to Nginx, wherever it serves the site: locations of your own in the site's server block, and what Nginx allows only at the http level. Rules of your own

The Varnish and Nginx files take effect with the deploy that carries them.

When a deploy refuses

A deploy that refuses gives every reason at once. The common ones:

Message What to do
no vallic.yaml Add the file
Service "redis" needs a version Write - redis: '8.6'
needs postgres 18, and this environment runs a different database Contact support: something is in it, and changing it is a migration
needs elasticsearch 9, which this platform does not offer Use one it does; the message lists them
requires the SENDGRID_API_KEY variable Set it in the console
declares 2 worker(s) and this environment has room for 1 Add a worker machine or a web server, or fold the work into one worker
which this environment cannot run: it is a php service That service belongs to another language: Nginx beside a Node server, say. Take it out
has no search machine to run it on On a shape where each service has a machine of its own, add one on the environment's Machines tab