Configuration File

Every key portico.yaml accepts. Unknown keys are errors.

Top Level

Key	Default	Description
runtime	auto	Container runtime: auto (Docker, else Podman), docker or podman.
proxy		The proxy in front of the services (see below).
services		The services, by name.

Proxy

Key	Default	Description
port	4400	Port Portico listens on.
host	0.0.0.0	Address Portico listens on.
base	/	Prefix mounted in front of every route. Must start with /.
engine	builtin	builtin, or nginx for production parity.
image	nginx	Image for the nginx engine, when nginx isn't installed.
tag	1.30.5-alpine	Tag for the nginx engine's image.
cors	["*"]	Origins allowed to call Portico cross-origin; [] leaves CORS to your app.

A cors entry is *, an http or https origin, or an origin with a leading *. in the host to match any subdomain.

Services

Key	Kinds	Description
run	run	Shell command to start; {port} becomes the port, also set as PORT.
dir	run	Directory to run the command in, relative to portico.yaml.
image	image	Container image to run.
tag	image	Image tag.
compose	compose	Compose file to bring up, relative to portico.yaml.
service	compose	The single compose service to start and route.
routes	compose	Paths for individual compose services; not with service. Each starts with /.
port	all	The port it listens on; none for a run service that serves nothing.
route	all	Path to mount it at (default: /<name>). Must start with /.
strip	all	Remove the route prefix before forwarding (default: true).
host	all	preserve forwards the browser's Host instead of localhost:<port>.
quiet	all	Keep its output off the screen (default: false).
log	all	Write its output to .portico/logs/<name>.log (default: true).

A service sets at most one of run, image and compose; with none, it's a service you start yourself.

Rules

• port is required for image services and for services you start yourself.
• port: none is only valid with run, and a service without a port can't have a route.
• With compose, port needs service, and must be a port that compose service publishes.
• A key outside its kinds is an error, such as dir on an image service.
• Service names start with a letter or digit, use a-z, 0-9, _, . and -, and can't be portico or nginx.