Stack spec
A stack is one YAML file that describes a group of containers (called services) for Clouduler to run across your cluster. This page lists every field the file accepts. It is a subset of Docker Swarm / Compose v3 plus an x-clouduler block for things Compose has no concept of: reverse-proxy routes, drive-backed volumes, node pins, actions and alert rules.
For the task-oriented view, see Stacks. Terms like drive, overlay and placement are explained in the glossary.
Three rules to know before the tables:
- Unknown keys are an error. A typo fails the parse instead of being ignored, and
build:is not supported. - Everything takes effect on redeploy. The spec is stored as text. A change applies when you deploy a new revision, so the Reload column below reads
n/afor every field. - Types.
durationis a humantime value (30s,2m,1h30m).sizeis a byte size (10MB,64MiB,512M, or a plain number of bytes).
How validation works
Validation runs in two layers.
- Syntax runs on every save in the web UI and on every deploy. It needs no cluster: names, shapes, port collisions, dependency cycles, and so on.
- Cluster checks ask whether the network, drive and node you named actually exist and whether the service can be placed. The web UI, the HTTP API (and the MCP tools), the CLI (
clouduler stack deploy) and the git-backup pull all run them, and refuse the deploy with a message when a drive, network or node pin does not exist.
Because the UI errors come back without a path, the message carries the whole location, for example invalid config at services.web.env_file: ..., and the editor does not highlight a line for it.
A full example
This file touches most of the common fields. Comments explain each part.
gitlab.yaml
version: "3.8" # ignored, optional
networks:
wan: {} # a cluster network with a domain, used by the proxy route
tailscale: {} # a second network, used by the SSH expose
secrets:
db_password:
file: ./secrets/db.txt # read at deploy time, sealed with the cluster key
configs:
gitlab_rb:
file: ./conf/gitlab.rb # bundled at deploy time
services:
gitlab:
image: gitlab/gitlab-ce:16.9.1-ce.0
restart: unless-stopped # the real restart policy lives here
networks: [wan, tailscale] # must be declared above
environment:
GITLAB_OMNIBUS_CONFIG: "external_url 'https://gitlab.example.com'"
volumes:
- fast/gitlab-data:/var/opt/gitlab # drive/volume:/target
- fast/gitlab-config:/etc/gitlab
- bulk/gitlab-logs:/var/log/gitlab
- type: tmpfs
target: /tmp/cache
tmpfs: { size: 64m }
secrets:
- source: db_password
env: DB_PASSWORD # exposed as an env var instead of a file
configs:
- source: gitlab_rb
target: /etc/gitlab/gitlab.rb
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost/-/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 2m
stop_grace_period: 2m
deploy:
replicas: 1
resources:
limits: { cpus: "2.0", memory: 4G }
x-clouduler:
node: atlas # hard pin, optional
proxy:
- host: gitlab # becomes gitlab.<domain of wan>
network: wan
port: 80
tls: true
middlewares: [redirect_https]
max_body_size: 2GiB
preserve_host: true
response_timeout: 120s
expose:
- port: 22 # container port
published: 2222 # host port, bound on every node
protocol: tcp
network: tailscale
backup:
stop_before: true # stop the service during a restic backup
Top level
Option
Type / default
Reload
Description
servicesrequiredmapno defaultn/a
The containers of the stack, keyed by service name. Each key must be a DNS label.
mapdefault {}n/a
Cluster networks this stack uses. Clouduler does not create Docker networks from this block. Each name must exist in the cluster and be implemented by some node (nat networks excepted).
list of strdefault unrestrictedn/a
Restricts what the stack can reach through that network. Entries: host, *.suffix, host:port, host:lo-hi, host:port/udp, or an IPv4 literal. See Networking.
Watch out: A bare allowed: with no value is an error. Write allowed: [] to deny everything.
mapdefault {}n/a
Accepted for Compose compatibility but not used. Services reference drives directly.
Watch out: Parsed but currently not acted on.
mapdefault {}n/a
Cluster configs. With file: the content is bundled at deploy time (path relative to the stack file, or absolute). Without file: the config must already exist in the cluster.
mapdefault {}n/a
Cluster secrets. Same rules as configs. The content is sealed with the cluster key.
mapno defaultn/a
Stack-wide defaults that services inherit: auto_update, node, volume_sync, backup, alerts. Other keys are rejected here.
Watch out: proxy, expose, colocate, actions and docker_socket are service-level only.
Stack names and service names
The stack name is not a spec key. It comes from the file name (CLI, without the extension) or the Stack name field in the web UI. It must be 1 to 63 bytes, start and end with a lowercase letter or digit, and use only a-z, 0-9, - and _. The UI hint says "Lowercase letters, numbers and dashes", but the server also accepts underscores.
Each key under services: must be a DNS label (lowercase letters, digits and hyphens, not starting or ending with a hyphen, at most 63 characters). It is the service's hostname on the overlay and part of the container name STACK_SERVICE_INDEX.
Service
Option
Type / default
Reload
Description
imagerequiredstrno defaultn/a
Container image reference.
Watch out: build: is rejected as an unknown key.
string or listdefault image defaultn/a
Overrides the image CMD. A string is split like Docker does, a list is exec form.
map or list of KEY=valueno defaultn/a
Environment variables.
Watch out: List entries must contain =. Numbers and booleans in a map are stringified, null becomes empty. Secret environment variables come from secrets with env:.
path or listno defaultn/a
Not supported.
Watch out: Always rejected. Move the entries into environment.
map or list of key=valueno defaultn/a
Docker labels on the container. Clouduler adds its own revision label.
list of namesno defaultn/a
Networks this service attaches to. Each must be declared in the stack's top-level networks.
Watch out: At most one egress, wireguard or nat network per service.
list of service namesno defaultn/a
Start-order gate: an instance is not first created until every dependency has at least one instance running on any node.
Watch out: Waits for running, not healthy. Cycles and self-references are errors.
mapno defaultn/a
Docker healthcheck. See Healthcheck below.
Watch out: Without test: the whole block is silently dropped.
durationdefault cluster failover.stop_grace (30s)n/a
How long a graceful stop may take before the kill.
Watch out: Must be greater than zero and at most 600s.
strdefault image STOPSIGNALn/a
Signal for the graceful stop, for example SIGINT.
Watch out: Must be SIG plus uppercase letters, or digits. Lowercase sigint fails.
listno defaultn/a
Cluster configs mounted into this service. Name or long form, see Configs and secrets in services.
listno defaultn/a
Cluster secrets mounted at /run/secrets/NAME. Name or long form.
Watch out: write: true on a secret is rejected.
mapno defaultn/a
Clouduler extensions for this service. See Proxy and x-clouduler per service.
Volumes
Volumes come from drives, from tmpfs, or are anonymous container paths. Host binds are not supported. See Drives and volumes.
Option
Type / default
Reload
Description
strno defaultn/a
Mount a volume from a drive, read-write. The reference is split on the first slash.
strno defaultn/a
Mount the drive's whole root directory.
Watch out: Allowed only when the drive has exactly one holder and the service is pinned to it with x-clouduler.node. See Drives and volumes.
strno defaultn/a
Long form. In-memory mount. Contents are lost on restart and never replicated.
Watch out: A tmpfs cannot have a source.
n/ano defaultn/a
Not supported.
Watch out: Bind mounts and host paths are rejected: volumes must live on a drive so they can be replicated and migrated.
Ports
Option
Type / default
Reload
Description
strno defaultn/a
Publish on the node that runs the container. Ranges like 8080-8090:80-90 are allowed when both sides are ranges of equal length.
host or ingressdefault hostn/a
Long form. Only host is supported.
Watch out: ingress is rejected: Clouduler has no Swarm-style ingress mesh. Use x-clouduler.expose for a port that follows the container across nodes.
A published port is bound on the node that runs the container and moves with it. For a port that follows the container across nodes, use x-clouduler.expose. Two services in the same stack cannot publish the same port. Collisions between different stacks are not checked.
Healthcheck
Option
Type / default
Reload
Description
testrequiredstring or listno defaultn/a
CMD, CMD-SHELL, NONE list forms, or a shell string.
Watch out: If absent, the whole healthcheck block is ignored.
Configs and secrets in services
Option
Type / default
Reload
Description
strno defaultn/a
Mount the object at its default path.
Watch out: An empty name is an error.
absolute pathdefault secrets: /run/secrets/NAME, configs: /NAMEn/a
Where it appears in the container.
strno defaultn/a
Expose the value as an environment variable instead of a file.
Watch out: Cannot be combined with target, mode, uid, gid or write.
booldefault falsen/a
Configs only. Container edits feed back to the cluster's copy.
Watch out: Only one service may hold a writable config, and not with replicas above 1. A secret with write: true is rejected.
Deploy
Option
Type / default
Reload
Description
intdefault 1n/a
Number of instances, named STACK_SERVICE_INDEX. 0 is allowed.
Watch out: At most 1000. Ignored when mode is global. A service with more than one replica cannot hold a writable config.
replicated or globaldefault replicatedn/a
global runs one instance on every eligible node.
list of strno defaultn/a
Swarm-style node filters: KEY==VALUE or KEY!=VALUE with keys node.hostname, node.id, node.role (manager or worker), node.labels.KEY.
Watch out: node.hostname==NAME and node==NAME are checked against cluster nodes by the CLI. An unknown key never matches.
str (float)no defaultn/a
CPU cap, for example "1.0".
Watch out: A value that does not parse is silently ignored.
sizeno defaultn/a
Memory cap. Also used by the rebalancer.
Watch out: An unparseable value is silently ignored (no cap). A digit string that overflows is an error.
same as limitsno defaultn/a
Parsed but currently not acted on. No consumer outside the config parser.
mapno defaultn/a
Parsed but currently not acted on. Use the service-level restart key instead.
Watch out: The shipped gitlab.yaml example sets max_attempts: 3 here and it does nothing.
mapno defaultn/a
Parsed but currently not acted on. Rolling updates are not controlled from the spec.
Proxy and x-clouduler per service
x-clouduler is the Clouduler-specific block on a service.
Option
Type / default
Reload
Description
strno defaultn/a
Hard pin to one node. Must be a cluster node.
Watch out: Inherited from the stack-level default. A stack-wide node can break drive/. whole-drive mounts.
list of servicesno defaultn/a
Pins this group of services to the same node. Transitive.
Watch out: Must name other services in the stack, not itself.
list of routesno defaultn/a
HTTP routes published through the reverse proxy. See the proxy table below.
listno defaultn/a
Non-HTTP ports routed over the overlay (SSH and similar). See the expose table below.
strno defaultn/a
Name of an action of this service, run in the container on the primary node before each scheduled replication. If it fails, that replication is skipped.
Watch out: Service level only. Runs on scheduled replication, not on migrations or manual syncs.
strno defaultn/a
Name of an action run after each replication attempt.
Watch out: Service level only.
durationdefault drive sync_intervaln/a
Per-volume replication interval override. Parsed but currently not acted on.
Watch out: Only the drive's own sync_interval is used today.
booldefault truen/a
Per-volume replication on/off. Parsed but currently not acted on.
booldefault falsen/a
Meant to follow :latest. Parsed but currently not acted on.
Watch out: Image updates are applied from the Updates page.
booldefault drive backup target decides (stop)n/a
Whether a restic backup stops this service first.
x-clouduler.docker_socket.targetrequiredpathno defaultn/a
Path inside the container where the Docker socket appears.
local or cloudulerdefault localn/a
local is the node's real socket (root-equivalent on the host). clouduler is a read-only endpoint for image queries.
booldefault falsen/a
Read-only socket.
Watch out: mode: clouduler requires true.
mapno defaultn/a
Named commands runnable in the container from the UI or as sync hooks. The label is the button text.
actions.LABEL.cmdrequiredstr or listno defaultn/a
Command. A string runs as sh -c, a list is exec form.
durationdefault 30sn/a
Time limit.
Watch out: Capped at 300s: longer values are clamped.
booldefault truen/a
false hides the button and refuses UI/API runs. The action is then only usable as a sync hook.
false or mapdefault enabledn/a
Alert control for the service's containers, merged over the stack-level block. See Alerts below.
Proxy routes
Each entry of x-clouduler.proxy. See Proxy and TLS.
Option
Type / default
Reload
Description
hostrequiredstrno defaultn/a
Hostname of the route. A bare label gets the network's domain appended, a name with a dot is used as is.
networkrequiredstrno defaultn/a
Network that publishes the route. Must be declared in the stack and have a domain in the cluster.
durationdefault none (waits forever)n/a
Maximum wait for the backend's response headers.
booldefault falsen/a
Publish the hostname through Cloudflare's proxy. Public networks only; on only if every route behind the host sets it.
Expose
Each entry of x-clouduler.expose. See Networking.
Option
Type / default
Reload
Description
publishedrequiredintno defaultn/a
Host port bound on every node. Must not collide with ports in the same stack.
networkrequiredstrno defaultn/a
Declared cluster network. On a public or wireguard network, some node must list the port in open_ports.
Watch out: Error: no node has PORT/PROTO open on network NET, this port could never be reached.
booldefault falsen/a
Send a PROXY v2 header so the backend sees the real client address. TCP only.
Watch out: Enable PROXY v2 on the backend first or the connection breaks.
Middlewares
Written under middlewares: of a route, either as a bare name (redirect_https) or as a one-key map (cors: {origins: [...]}).
Option
Type / default
Reload
Description
bare or mapdefault n/a
Require an IdP login. Needs proxy.auth in the cluster config covering that network.
Watch out: Error: authenticated asks for a login on network NET, but proxy.auth does not list it in networks.
listdefault any logged-in usern/a
Restrict by IdP group. Empty names are rejected.
booldefault truen/a
Let containers on the cluster's own networks through without a login.
mapno defaultn/a
Set headers on the request to the container or the response to the client.
Watch out: Header names must be valid tokens, values cannot contain control characters. A bare headers entry is rejected: use a map.
cors.originsrequiredlistno defaultn/a
Allowed origins.
Watch out: * cannot be combined with allow_credentials.
redirect_regex.regexrequiredstrno defaultn/a
Matched against the full URL including host and query. Must compile.
Alerts
Allowed at the stack level and the service level under x-clouduler.alerts. See Alerts.
Option
Type / default
Reload
Description
booldefault true (enabled)n/a
Nothing about this stack or service is sent. Log rules still parse but never run.
listno defaultn/a
Alert keys like instance.unhealthy, or a prefix like instance.*, to mute.
info, warning or criticaldefault per eventn/a
Override the severity of an event.
Watch out: An unknown event key is rejected.
strno defaultn/a
Plain substring to look for in the logs. Exactly one of match and regex.
durationdefault 5mn/a
After a match, repeats inside the window are counted, not raised.
listdefault alln/a
Stack level only. Limits a stack-level rule to named services.
Common validation errors
The format is invalid config at PATH: MESSAGE, where PATH is a dotted path such as services.web.volumes[0].
Syntax errors (UI and CLI)
service name must be a valid DNS label (lowercase letters, digits, hyphens, not starting or ending with a hyphen) since it becomes an overlay hostnameenv_file is not supported yet, move its entries into environmentnetwork NET is not declared in this stack's top-level networksno service named DEP in this stack,a service cannot depend on itself,dependency cycle: a -> b -> aport P/PROTO is already published by services.X.ports[I]bind mounts are not supported, volumes must live on a drive so they can be replicated and migrated"SRC" must use drive/volume syntax, e.g. fast/gitlab-datamode: ingress is not supported, clouduler has no swarm-style ingress mesh; ...unknown restart policy "X", expected no, always, on-failure[:N] or unless-stopped"sigint" is not a signal name (e.g. SIGINT) or numbermust be greater than zeroormust be at most 600s(stop_grace_period)write is not allowed on a secret, only on a configCFG is writable but this service runs N replicas; only one instance may write a configN is more than the maximum of 1000(replicas)expected KEY=value, got "ENTRY"(list-form environment or labels)mode: clouduler is read-only; set read_only: trueallowed must be a list (write `allowed: []` to deny everything, or drop the key)invalid stack name "NAME": must be 1 to 63 bytes long,must start and end with a lowercase letter or digit,only lowercase letters, digits, - and _ are allowed
Cluster errors (CLI and git sync only)
no network named NET declared in the clusterno node implements network NET, this service could never be placedonly one egress network is allowed per service, found A and Bno drive named DRIVE declared in the clusterno node named NODE in the clusternetwork NET has no domain, so it cannot serve an HTTP routeno node has P/PROTO open on network NET, this port could never be reacheddrive D can be served by more than one node (...), so mounting D/. (its whole root) is not allowed: pin a specific volume under it instead
Deploy errors (UI and API)
config NAME needs content: it has no existing value to keep(and the same for a secret)this node holds no cluster key(the node you are connected to cannot seal secrets)stacks A and B would both use the overlay network ... which would break isolation between them: rename one of the stacks or networks
Deploy errors (CLI)
this stack has secrets, so the cluster key at PATH is needed. Deploy from a node that holds it, or use the web uiNAME is N bytes, over the 1048576 byte limit(each bundled config or secret file is capped at 1 MiB)