Deploy

Each recipe runs one or more Scafo nodes against one S3-compatible bucket and puts an ingress in front of them. The ingress pulls: Caddy reads /v1/ingress/routes through the scafo dynamic-upstreams module, Traefik reads /v1/ingress/routes/traefik through its http provider. The node writes no ingress configuration, and nothing but the ingress ever talks to the node's own listener. Operators reach the fleet through the ingress too, at the platform apex.

#Common prerequisites

#Object store

An S3-compatible bucket that supports conditional writes with If-Match and If-None-Match. It is the whole registry: no recipe creates it, and the node refuses to boot without SCAFO_S3_ENDPOINT, SCAFO_S3_BUCKET, SCAFO_S3_ACCESS_KEY and SCAFO_S3_SECRET_KEY.

Prefer a flat-rate or self-hosted store over one billed per request: every runtime process polls the bucket several times a minute whether or not anyone is calling it, and that adds up to tens of millions of requests a month for a small installation. See what an installation costs its bucket.

One bucket-and-prefix pair is one fleet. Every node pointed at the same bucket and the same SCAFO_S3_PREFIX is one installation; nothing else joins two nodes together. Use separate buckets or prefixes for separate installations.

#DNS

Point an apex record and a wildcard record for the platform domain at the machines that terminate TLS, for example apps.example.com and *.apps.example.com. The same domain goes in SCAFO_PLATFORM_DOMAINS (no scheme, no wildcard); without it, applications get no host.

Do this before the first deploy, not after: the apex is also how the CLI reaches the fleet, and the recipes assume it resolves.

A wildcard DNS record does not imply a wildcard certificate. Whether the platform domain is covered by one wildcard certificate (DNS-01) or by a certificate per host (HTTP-01 or TLS-ALPN, issued on first request) is per recipe.

#Ports

On every host that terminates TLS, open TCP 80 and 443, plus UDP 443 where the recipe's ingress speaks HTTP/3. With the WireGuard transport, also open UDP 51820 between the hosts.

Nothing else is opened, published or forwarded. The node API is not a port of the host in any recipe: see the node API.

#Ingress token

The ingress presents one bearer token to /v1/ingress/routes and /v1/storage on the node's own listener. Generate one per installation, or per host where the recipe says so:

openssl rand -hex 32

It goes to the node as SCAFO_INGRESS_TOKEN and to the ingress through whatever mechanism that ingress has. It is the only credential the ingress ever holds.

#Persistent state

Every recipe keeps the node's state directory (SCAFO_STATE_DIR, /var/lib/scafo in the image) on storage that survives the node being re-created, not only restarted: a named volume, a retained claim, a real host directory. It holds the node's identity and the working directory of every runtime process, and a write is acknowledged to the caller once a peer holds it there, before the bucket has a copy. Starting on an empty one starts without those writes.

The node id has to be stable for the same reason. Neither it nor the directory may change when you move the node to a newer image.

#Shutdown grace

Give the node at least 50 seconds between SIGTERM and SIGKILL, so it can drain its runtimes. If CELLD_SHUTDOWN_TOTAL_MS is raised above its 40-second default, use that value plus at least 10 seconds instead.

In containers this is stop_grace_period: 50s (Compose), --stop-timeout 50 (docker run) or terminationGracePeriodSeconds: 50 (Kubernetes). Under systemd it is TimeoutStopSec=50s.

#Process layout

In a container, the Node entrypoint must stay PID 1 in a private PID namespace. Do not use host PID mode, and do not wrap the entrypoint in a persistent supervisor. On a bare host, use the installer's systemd unit or an equivalent cgroup-owning supervisor that signals the daemon itself rather than every process beside it.

#The node API

The node's own listener, 127.0.0.1:7400 by default, carries everything privileged: deploy intake, operator commands, the routing document and the TLS storage the ingress keeps private keys in. Two parties need it, and both are already next to the node:

• The ingress, which reads routing and storage from it with the ingress token. A colocated Caddy shares the node's network namespace and dials loopback; a platform's Traefik dials the node over the container network it shares with it.
• The node itself, whose health probe asks it.

Operators are not a third. The node serves its API at the platform apex through the ingress by default (SCAFO_API_PUBLIC), with /v1/storage and /v1/ingress/routes denied there, so scafo remote add prod --endpoint https://apps.example.com is the operator path on every recipe, from any machine, over the TLS the ingress already terminates. No recipe publishes port 7400 to a host, a loopback included: a listener nothing uses is only a surface, and a host-loopback publish is one edit away from a public one.

Widening the listener beyond loopback is a transport decision: SCAFO_TRANSPORT=none states that the network the node binds is already private and trusted (a container bridge, a pod network), SCAFO_TRANSPORT=wireguard puts node and runtime traffic on a tunnel. The recipes that need one say which and why; the ones that do not leave the defaults alone.

#Without the apex

If SCAFO_API_PUBLIC=0 leaves the apex unrouted, or the DNS record does not exist yet, the API is reached only where it listens, through a tunnel you open for the occasion:

Then name the forwarded end on each command, --node http://127.0.0.1:7400, or register it as the remote's endpoint. The forward is yours and goes away with the shell; nothing in the recipe stays open for it.

#The recipes

The container image documents the image the first six recipes run, its tags, and the scafo-caddy images and flavours.

#Choosing by ingress

No ingress on the host yet: run scafo-caddy beside the node. The Compose, bare-metal and VPS recipes take this shape. Caddy holds no bucket credential: it keeps certificates and their locks in the bucket by asking the colocated node over /v1/storage, and reads the fleet's routing from /v1/ingress/routes. Both calls carry the ingress token. The image runs from environment variables alone, and one Caddy can front several fleets. scafo-caddy is the only Caddy build that can do it; upstream Caddy carries none of its scafo modules.

A Traefik already runs in front of everything on this host or cluster: teach it the http provider. The K3s, Coolify and Dokploy recipes take this shape. Traefik polls /v1/ingress/routes/traefik with an Authorization: Bearer header and gets native Traefik dynamic configuration back; its routers arrive as <host>@http beside the platform's own. That needs Traefik v3, because providers.http.headers is what presents the token; Traefik 2.x has no such setting. TLS is then whatever that Traefik already does, and SCAFO_TRAEFIK_ENTRYPOINTS names the entryPoint Scafo's routers attach to.

#First deploy

The same on every recipe. The fleet trusts no operator key until somebody mints one, and no node holds one: the first key is minted on your own machine, never on a server or inside a container, and it talks to the fleet through the apex.

npm install --global scafo

export SCAFO_S3_ENDPOINT="https://s3.example.com"
export SCAFO_S3_BUCKET="scafo"
export SCAFO_S3_ACCESS_KEY="<access key>"
export SCAFO_S3_SECRET_KEY="<secret key>"
export SCAFO_S3_REGION="us-east-1"
export SCAFO_S3_PREFIX="scafo"

scafo remote add prod --endpoint https://apps.example.com --register

scafo fleet nodes

scafo deploy ./my-app --name shop
curl -sS https://shop.apps.example.com/