Reference
Manifest reference
An application is described by one manifest file in its directory:
podos.toml, podos.yaml or podos.yml. Exactly one may exist. TOML and
YAML use the same keys and give the same result; this site shows TOML first.
Check a manifest at any time with:
podos manifest validate # all environments
podos manifest validate --env test # one environment
Parsing rules
- Strict. Unknown keys, wrong types and duplicate keys are errors. Each error names the file, the line and the key. All problems are reported together, in file and line order.
- Planned keys are refused. Keys that exist in the design but are not
built yet (
job,volume,share,ingress,backup,node,nodes,routes) get a specific "not supported yet" error. - A leading byte-order mark is ignored, line endings in values become LF, and integers with leading zeros are refused.
- A manifest file may be at most 256 KiB.
Complete example
namespace = "shop"
environments = ["test", "prod"]
[service.web]
image = "ghcr.io/example/shop:1.4.2"
replicas = 2
port = 3000
domains = ["shop.example.com"]
health = "/healthz"
resources = { cpu = 0.5, memory = "256M" }
env.DATABASE_URL = "postgres://app:${secret.DB_PASSWORD}@db.internal:5432/shop"
env.LOG_LEVEL = "${env.LOG_LEVEL}"
[service.worker]
image = "ghcr.io/example/shop:1.4.2"
command = ["bin/worker", "--queue", "default"]
only = ["prod"]
[environment.test.service.web]
replicas = 1
domains = ["test.shop.example.com"]
tls = "self-signed"
namespace: shop
environments: [test, prod]
service:
web:
image: ghcr.io/example/shop:1.4.2
replicas: 2
port: 3000
domains: [shop.example.com]
health: /healthz
resources: { cpu: 0.5, memory: 256M }
env:
DATABASE_URL: "postgres://app:${secret.DB_PASSWORD}@db.internal:5432/shop"
LOG_LEVEL: "${env.LOG_LEVEL}"
worker:
image: ghcr.io/example/shop:1.4.2
command: [bin/worker, --queue, default]
only: [prod]
environment:
test:
service:
web:
replicas: 1
domains: [test.shop.example.com]
tls: self-signed
Available In this example, port, domains, tls and health take effect
at deploy: the proxy serves shop.example.com on HTTPS (the default tls
is auto) and the /healthz check decides when a replica is ready.
Top-level keys
| Key | Type | Required | Meaning |
|---|---|---|---|
namespace |
name | yes | The namespace of the application. |
environments |
list of names | no | The environments, 1 to 20. Default: one environment, prod. |
service.<name> |
table | at least one | A service. See Service keys. At most 200 services. |
environment.<name> |
table | no | Overrides for one declared environment. See Environments and overrides. |
context |
name | no | Only in an override file: the context of that environment. Inline, it is environment.<name>.context. |
A name is 1 to 63 lowercase letters, digits and hyphens, starting with a
letter and ending with a letter or digit. localhost is reserved for
namespaces and services, and podos for namespaces.
Service keys
| Key | Type | Default | Status |
|---|---|---|---|
image |
image reference | Available | |
build |
relative path | Available | |
command |
list of strings | image entrypoint and command | Available |
replicas |
integer 0 to 1000 | 1 | Available |
env |
table of strings | Available | |
resources |
table | no limit | Available |
port |
integer 1 to 65535 | Available | |
domains |
list of strings | Available | |
tls |
string | auto |
Available |
health |
string or table | Available | |
restart |
string | always |
Available |
publish |
list of strings | Available | |
volumes |
table of paths | Available | |
files |
table of paths or tables | Available | |
only |
list of environments | all | Available |
lint_ignore |
list of env names | Available | |
unset |
list of key paths | Available, in overrides only; see unset |
image
The OCI image to run, as you would write it for Docker:
[service.web]
image = "nginx:1.27"
# image = "ghcr.io/example/app:1.2"
# image = "ghcr.io/example/app@sha256:..."
service:
web:
image: nginx:1.27
# image: ghcr.io/example/app:1.2
# image: ghcr.io/example/app@sha256:...
- A name without a registry means Docker Hub; without a tag means
latest. - No URL scheme (
https://), no whitespace, no credentials in the reference. At most 512 characters. - Each service needs exactly one of
imageorbuild. - Images are pulled anonymously. Private registries are planned (milestone not yet scheduled).
- The daemon pulls the image for the server's own platform.
build
Available A directory, relative to the application directory, with a file
named Dockerfile at its root. podos deploy uploads it and the server
builds it with BuildKit; the release then uses the built image. See
Build from source.
[service.web]
build = "."
service:
web:
build: .
Rules for the value:
- It must be relative to the application directory, use
/as separator and stay inside it: no absolute path, no\, no..that leaves the directory. It is not empty and has no control characters. - The path is cleaned:
./services/apibecomesservices/api..is the application directory itself. - A service has exactly one of
buildandimage. Both set, or neither, is an error. In an override file, settingbuildreplaces theimageof the shared part, and the other way round; one override file cannot set both. podos manifest validatechecks the path rules only. It does not look for theDockerfile;podos deploydoes.
The directory must hold a regular file named Dockerfile at its root. The
server needs BuildKit and crun 1.15 or newer, or a release with build is
refused. See Build from source.
command
Replaces the image's entrypoint and command. The first element is the program; there is no shell unless you call one.
[service.worker]
image = "busybox:1.36"
command = ["/bin/sh", "-c", "echo started; sleep infinity"]
service:
worker:
image: busybox:1.36
command: ["/bin/sh", "-c", "echo started; sleep infinity"]
The list must not be empty, its first element must not be empty, and no element may contain a NUL character. At most 100 elements.
replicas
The number of containers, from 0 to 1000. Default 1. With 0, the service is part of the release but no container is started.
env
Environment variables for the containers, as a table of strings:
[service.web]
image = "ghcr.io/example/shop:1.4.2"
env.LOG_LEVEL = "info"
env.API_KEY = "${secret.API_KEY}"
env.GREETING = "hello ${env.WHO}"
service:
web:
image: ghcr.io/example/shop:1.4.2
env:
LOG_LEVEL: info
API_KEY: "${secret.API_KEY}"
GREETING: "hello ${env.WHO}"
In TOML, env.NAME = "…" and env = { NAME = "…" } are the same.
- Names match
[A-Za-z_][A-Za-z0-9_]*, at most 256 characters. Names that start withPODOS_, in any letter case, are reserved. - Values are strings, at most 32 KiB, without NUL characters. Write numbers
and booleans as strings:
env.WORKERS = "4". - At most 1000 variables per service.
${secret.NAME}inserts a secret and${env.NAME}an env value of the environment being deployed.$$is a literal$. Any other$is an error. See Env values and secrets.- Every referenced value must be set in the environment before
podos deploy; otherwise the release is refused with the list of missing names.
resources
Limits for each container of the service:
[service.web]
image = "ghcr.io/example/shop:1.4.2"
resources = { cpu = 0.5, memory = "256M" }
service:
web:
image: ghcr.io/example/shop:1.4.2
resources: { cpu: 0.5, memory: 256M }
| Key | Meaning |
|---|---|
cpu |
CPUs, a number from 0.01 to 1000. 0.5 is half a CPU. |
memory |
Digits followed by K, M or G (binary multiples, upper or lower case), more than zero and at most 1024G. Examples: "256M", "512k", "1g". |
Without resources, a container has no CPU limit. Available A service
without resources.memory gets a memory limit of 512 MiB, with no swap
beyond it. A process that goes over the limit is killed by the kernel and
podos ps shows it as oom-killed. Set resources.memory for databases,
JVMs and build steps.
port
The port the service listens on inside its containers, 1 to 65535. Required
when domains or health is set. Available The proxy sends traffic for the
service's domains to this port, and health checks probe it. Other services
of the same environment reach it at http://<service>:<port>/.
domains
Available The domains that route to the service through the built-in proxy. Each entry is a host name, optionally with a path:
[service.web]
image = "ghcr.io/example/shop:1.4.2"
port = 3000
domains = ["shop.example.com", "www.shop.example.com", "example.com/shop"]
service:
web:
image: ghcr.io/example/shop:1.4.2
port: 3000
domains: [shop.example.com, www.shop.example.com, example.com/shop]
- A host name, not an IP address; no scheme, port, credentials, query or fragment. The host is stored in lowercase.
- A wildcard is allowed only as the whole first label:
*.example.com. - A path is a sequence of segments made of letters, digits and
- . _ ~, without a trailing/. The longest matching path wins. - Two services of the same environment cannot claim the same domain and path. A domain belongs to one environment; the first claim wins across the server, and a release that uses a domain another namespace holds is refused.
portis required.- Domains that are public suffixes or reserved names are refused.
See Domains and HTTPS.
tls
Available How the proxy serves the service's domains. Only allowed when the
service has domains.
| Value | Meaning |
|---|---|
auto |
A certificate from Let's Encrypt (ACME). Needs podos setup --acme-email. |
self-signed |
A certificate from the Podos internal CA. |
off |
Plain HTTP. |
cert:<name> |
A certificate uploaded to the environment under <name> with podos cert set. |
Without tls, the default is auto. A wildcard domain such as
*.example.com cannot use auto; set tls to self-signed or
cert:<name>. HTTP is redirected to HTTPS for every route with TLS.
auto has only been tested against a test ACME server, not yet against the
real Let's Encrypt service.
health
Available The health check that decides when a container is ready and healthy. The short form is an HTTP path; the table form sets the type and the timing:
[service.web]
image = "ghcr.io/example/shop:1.4.2"
port = 3000
health = { path = "/healthz", interval = "10s", timeout = "2s" }
service:
web:
image: ghcr.io/example/shop:1.4.2
port: 3000
health:
path: /healthz
interval: 10s
timeout: 2s
| Key | Default | Range |
|---|---|---|
type |
http when path is set, otherwise tcp |
"http" or "tcp" |
path |
(required for http) |
Starts with /, no whitespace or fragment. Not allowed for tcp. |
interval |
10s |
1s to 5m |
timeout |
2s, or interval if that is shorter |
100ms to 5m, not longer than interval |
start_period |
10s |
0s to 10m. Failures in this time after the start are not counted. |
retries |
3 |
1 to 10. Consecutive failures that make a container unhealthy. |
success_threshold |
1 |
1 to 10. Consecutive successes that make a container ready. |
Durations are written like "500ms", "10s" or "1m". port is required.
An http check succeeds on a status code from 200 to 399 (redirects are not
followed). A tcp check only connects to the service port:
[service.db]
image = "postgres:17"
port = 5432
health = { type = "tcp", interval = "5s", retries = 5 }
service:
db:
image: postgres:17
port: 5432
health: { type: tcp, interval: 5s, retries: 5 }
A container is ready when its check has passed success_threshold times in
a row. Without a health key a container is ready after it has run for 3
seconds. An unhealthy container is stopped and, depending on
restart, replaced. A check never runs a command inside the
container: type = "exec" and a command key are refused as not available
yet.
restart
Available What happens when a container stops by itself:
| Value | Meaning |
|---|---|
always |
Start a new container whatever the exit code. The default. |
on-failure |
Start a new container only after a failure (a non-zero exit code, or a stop because the health check failed). |
never |
Do not start a new one; podos ps shows the exit code. |
[service.worker]
image = "ghcr.io/example/shop:1.4.2"
restart = "on-failure"
service:
worker:
image: ghcr.io/example/shop:1.4.2
restart: on-failure
A restart waits first. The delay doubles from 1 second up to 5 minutes and
starts over after a container has run for 10 minutes. podos ps shows the
number of consecutive failures in RESTARTS. After a reboot of the server,
the containers of the active releases are started again.
publish
Available Opens a host port to the service, for traffic that does not go through the HTTP proxy (a database, DNS, a game server). Each entry is a port and a protocol:
[service.db]
image = "postgres:17"
publish = ["5432/tcp"]
service:
db:
image: postgres:17
publish: [5432/tcp]
The port is 1 to 65535, the protocol tcp or udp. Duplicates are refused.
- The same port number is used on the server and in the container.
- A service with
publishmust have one replica (replicas = 1), because a host port forwards to a single container. - One environment per port on the server. A port the server already listens on (SSH, the proxy, the API or another program) is refused.
- The port is reachable from other machines, not from the server itself.
See Published ports.
volumes
Available Persistent directories, as a table from a volume name to a path inside the container:
[service.db]
image = "postgres:17"
volumes = { data = "/var/lib/postgresql/data" }
service:
db:
image: postgres:17
volumes:
data: /var/lib/postgresql/data
- The name follows the name rule; the path is absolute and clean (no
..,.,//or trailing/), not/, and not inside/proc,/sysor/dev. - Two volumes of one service cannot use the same or nested paths.
- The data survives redeploys and
podos down; an environment of the same name finds it again.podos down --delete-volumesor deleting the namespace removes it.
See Volumes.
files
Available Files from the environment, mounted into the containers. Each
key is the name of a file stored with podos file set; the value is the path
inside the container, or a table:
[service.web]
image = "ghcr.io/example/shop:1.4.2"
files.APP_CONFIG = "/etc/shop/app.toml"
files.TLS_KEY = { path = "/etc/shop/tls.key", mode = "0440" }
files.SHOP_CONF = { path = "/etc/shop/shop.conf", mode = "0444", template = true }
service:
web:
image: ghcr.io/example/shop:1.4.2
files:
APP_CONFIG: /etc/shop/app.toml
TLS_KEY: { path: /etc/shop/tls.key, mode: "0440" }
SHOP_CONF: { path: /etc/shop/shop.conf, mode: "0444", template: true }
| Key | Default | Meaning |
|---|---|---|
path |
(required in the table form) | Absolute, clean path inside the container. |
mode |
"0400" |
Octal permission string in quotes, three or four digits, at most "0777". Setuid, setgid and sticky bits are refused. |
template |
false |
Replace ${env.NAME} and ${secret.NAME} in the file when a container is created. |
- Names follow the rule of env names:
[A-Za-z_][A-Za-z0-9_]*, at most 256 characters, not starting withPODOS_. The name is the one given topodos file set; the file must be set in the environment beforepodos deploy, or the release is refused. - The file belongs to the user the container runs as and is mounted read-only.
- At most 16 files per service.
- These paths are refused:
/etc/resolv.conf,/etc/hostsand/etc/hostname(Podos provides them) and any path above or below them;/proc,/sys,/devand anything inside them; a path inside a volume of the service or above one; a path inside or above the path of another file of the service; the same path twice. - If the image has a directory or a symbolic link at the path, the release fails at once with the reason.
- With
template = trueonly${env.NAME}and${secret.NAME}are replaced; every other$stays, and$${env.NAME}gives the literal text. The values are read when a container is created, not pinned by the release. A template must be text. - In an override,
filesis merged by name, likeenv.unsetacceptsfilesandfiles.NAME. podos manifest validatechecks the rules above. It does not check that the file is set on the server;podos deploydoes.
See Files in containers.
only
Limits a service to some environments. The listed environments must be
declared in environments.
namespace = "shop"
environments = ["test", "prod"]
[service.web]
image = "ghcr.io/example/shop:1.4.2"
[service.mailcatcher]
image = "ghcr.io/example/mailcatcher:1.0"
only = ["test"]
namespace: shop
environments: [test, prod]
service:
web:
image: ghcr.io/example/shop:1.4.2
mailcatcher:
image: ghcr.io/example/mailcatcher:1.0
only: [test]
only belongs in the shared part of the manifest; an override cannot set
or change it.
lint_ignore
Available Names of env entries that the secret check should skip for this
service. podos manifest validate and podos deploy print a warning for a
literal env value that looks like a secret, for example:
- the name has a word such as
PASSWORD,SECRET,TOKENorKEYand the value is a non-empty literal; - the value is a URL with a user name and password;
- the value is a long random-looking string.
The warning never contains the value and never blocks a deploy. It tells you
to store the value with podos secret set NAME and write ${secret.NAME}.
Values that contain ${...} are not checked. If the value is not a secret,
silence the warning for that name:
[service.web]
image = "ghcr.io/example/shop:1.4.2"
env.AUTH_TOKEN_MODE = "bearer"
lint_ignore = ["AUTH_TOKEN_MODE"]
service:
web:
image: ghcr.io/example/shop:1.4.2
env:
AUTH_TOKEN_MODE: bearer
lint_ignore: [AUTH_TOKEN_MODE]
Each entry is the name of an environment variable, without duplicates. An override replaces the whole list; see How values merge.
context
Available Names the context (server) an environment is deployed to. It is a key of the environment, not of a service:
namespace = "shop"
environments = ["test", "prod"]
[service.web]
image = "ghcr.io/example/shop:1.4.2"
[environment.prod]
context = "prod-eu"
namespace: shop
environments: [test, prod]
service:
web:
image: ghcr.io/example/shop:1.4.2
environment:
prod:
context: prod-eu
- The value is the name of a context made with
podos login, never an address or a token.localmeans the daemon socket of the machine you run the command on. - In an override file the key is the top-level
context. Set it in one place only, inline or in the file; both is an error. - It is routing information for the CLI. It is never uploaded to the server and is not part of the release.
- The first time a manifest selects a context for a namespace, the CLI asks you to confirm. See Environments and overrides.
Validation limits
| What | Limit |
|---|---|
| Manifest file size | 256 KiB |
| Services | 200 |
| Environments | 20 |
env entries per service |
1000 |
files entries per service |
16 |
Items in command, domains, publish, volumes |
100 each |
env value |
32 KiB |
image reference |
512 characters |
Planned keys
These keys are reserved and give a "not supported yet" error today:
| Key | Planned for |
|---|---|
job.<name> run-to-completion jobs |
not yet scheduled |
volume.<name> top-level volume settings |
not yet scheduled |
routes |
not yet scheduled |
share between namespaces |
0.3 |
ingress advanced section |
0.3 |
backup |
0.2 |
node, nodes placement |
0.4 |