scaling.yml sits at the root of your repository and says how your stack starts: what to install, which background services it needs, which processes to run, and how to tell that each one is up.
The file is checked before anything acts on it.
A problem is reported with the key as you wrote it, the line, and what is wrong, for example processes.web.port on line 12.
A complete file
This is a monorepo with a web application and an API over one Postgres database.Rules that apply to the whole file
- A key the file does not have is an error, not something that is ignored. A misspelled key would otherwise look like it worked.
- YAML aliases (
&nameand*name) are not allowed. Write the value out. - The file can be at most 64 KiB.
- Names of services and processes are lowercase letters, digits and dashes, starting with a letter, up to 32 characters.
- A command can be at most 2000 characters. Wherever a list of commands is accepted, it can hold at most 32.
version
Required.
The only value is 1.
image
Optional.
The base image the stack boots from.
One of node:22, node:24, node:26, python:3.14, ubuntu or universal.
When it is left out, node:24 is used.
install
Required.
The command, or list of commands, that installs your dependencies.
services
Optional.
Background processes your stack needs before it can start, such as a database.
There can be at most 16.
Each service has:
A service cannot have the same name as a process.
setup
Optional.
A command, or list of commands, that runs once your services are up and before your processes start.
This is where migrations and seed data go.
Write these so they are safe to run more than once.
processes
Optional.
The applications that make up your stack.
There can be at most 16.
Each process has:
Your process must listen on
0.0.0.0, not 127.0.0.1.
test
Optional.
The command that runs your tests.
env
Optional.
Environment shared by every service and process.
A value set on a service or process wins over the same name here.
Names are letters, digits and underscores, and do not start with a digit.
Values are strings, numbers or true and false, at most 4096 characters.
Referring to another process
A value can name the address of one of your processes as${processes.<name>.url}.
Use it wherever one process needs to find another.
${...} is an error.