Podos A lightweight container platform Early development · not released

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

Complete example

TOML
project = "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"
YAML
project: 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
project name yes The project 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 projects and services, and podos for projects.

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:

TOML
[service.web]
image = "nginx:1.27"
# image = "ghcr.io/example/app:1.2"
# image = "ghcr.io/example/app@sha256:..."
YAML
service:
  web:
    image: nginx:1.27
    # image: ghcr.io/example/app:1.2
    # image: ghcr.io/example/app@sha256:...

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.

TOML
[service.web]
build = "."
YAML
service:
  web:
    build: .

Rules for the value:

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.

TOML
[service.worker]
image = "busybox:1.36"
command = ["/bin/sh", "-c", "echo started; sleep infinity"]
YAML
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:

TOML
[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}"
YAML
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.

resources

Limits for each container of the service:

TOML
[service.web]
image = "ghcr.io/example/shop:1.4.2"
resources = { cpu = 0.5, memory = "256M" }
YAML
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:

TOML
[service.web]
image = "ghcr.io/example/shop:1.4.2"
port = 3000
domains = ["shop.example.com", "www.shop.example.com", "example.com/shop"]
YAML
service:
  web:
    image: ghcr.io/example/shop:1.4.2
    port: 3000
    domains: [shop.example.com, www.shop.example.com, example.com/shop]

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:

TOML
[service.web]
image = "ghcr.io/example/shop:1.4.2"
port = 3000
health = { path = "/healthz", interval = "10s", timeout = "2s" }
YAML
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:

TOML
[service.db]
image = "postgres:17"
port = 5432
health = { type = "tcp", interval = "5s", retries = 5 }
YAML
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.
TOML
[service.worker]
image = "ghcr.io/example/shop:1.4.2"
restart = "on-failure"
YAML
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:

TOML
[service.db]
image = "postgres:17"
publish = ["5432/tcp"]
YAML
service:
  db:
    image: postgres:17
    publish: [5432/tcp]

The port is 1 to 65535, the protocol tcp or udp. Duplicates are refused.

See Published ports.

volumes

Available Persistent directories, as a table from a volume name to a path inside the container:

TOML
[service.db]
image = "postgres:17"
volumes = { data = "/var/lib/postgresql/data" }
YAML
service:
  db:
    image: postgres:17
    volumes:
      data: /var/lib/postgresql/data

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:

TOML
[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 }
YAML
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.

See Files in containers.

only

Limits a service to some environments. The listed environments must be declared in environments.

TOML
project = "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"]
YAML
project: 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 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:

TOML
[service.web]
image = "ghcr.io/example/shop:1.4.2"
env.AUTH_TOKEN_MODE = "bearer"
lint_ignore = ["AUTH_TOKEN_MODE"]
YAML
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:

TOML
project = "shop"
environments = ["test", "prod"]

[service.web]
image = "ghcr.io/example/shop:1.4.2"

[environment.prod]
context = "prod-eu"
YAML
project: shop
environments: [test, prod]

service:
  web:
    image: ghcr.io/example/shop:1.4.2

environment:
  prod:
    context: prod-eu

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 projects 0.3
ingress advanced section 0.3
backup 0.2
node, nodes placement 0.4