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'
scheduleis 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,jantodecandsuntosatby name, ranges (mon-fri), lists (1,15) and a step after*or a range (*/15,0-30/10). Not@reboot.commandis 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 |
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