[thiras]

Summary

Adds the onboarding sponsor (sponsord + sponsord-onramp) and an optional Caddy to the Docker Compose deploy path, as profiles in compose/compose.yaml:

Profile	Starts
node	decdn-node
sponsord	sponsord
onramp	sponsord-onramp + sponsord (the onramp needs its daemon on the same host)
caddy	Caddy in front of the onramp (leave it out to bring your own proxy)

Breaking for existing Compose node operators: add COMPOSE_PROFILES=node to compose/.env, or docker compose up -d selects no service.

Design

• Same hardening as the node: host network with loopback listeners, nothing published, images by digest, read-only rootfs, cap_drop: [ALL], no-new-privileges, a dedicated non-root account, and stop graces matching the units (120 s / 30 s).
• Listeners and secret paths are set in environment:, which beats env files. The release images default to 0.0.0.0.
• Credential files keep the roles' /etc/sponsord/ layout, but are owned by a host sponsord account. Bind mounts keep owner and mode, and upstream rejects a group-readable keystore. Each file is mounted read-only into /run/secrets/, and each container gets only the files it needs.
• Caddy: the official image, digest-pinned, running non-root with only NET_BIND_SERVICE. compose/Caddyfile mirrors the role's: admin off, h1/h2 only, no trusted_proxies.
• No ${VAR:?}: Compose interpolates disabled services too, so a required variable would break the other profiles. An unset variable now renders a value its service refuses: an invalid image reference, an unknown user, or a domain with a non-numeric port (the onramp and Caddy both reject it).

Lint

make lint-compose now renders with --profile '*' under env -i, twice:

• compose/tests/invariants.jq, with the example .env:
  • each service may only set its allowed keys, so privileged, pid: host or devices fail;
  • each service's mounts must match its allow-list exactly;
  • security_opt must be exactly no-new-privileges:true;
  • every service runs as a non-root uid:gid;
  • the sponsord daemons may not override command or entrypoint;
  • listeners stay on loopback;
  • *_FILE paths are pinned to /run/secrets/, and inline secrets are refused.
• compose/tests/fail-closed.jq, with an empty .env: checks that unset variables fail closed.

Other changes to the target:

• It refuses an empty render.
• It takes LINT_COMPOSE_FILE instead of Compose's own COMPOSE_FILE.
• Each violation prints as <service>: <invariant>.

tests/scripts-test.sh adds a positive baseline and pins which invariant each of 47 broken variants trips.

Docs

• compose/README.md: new sponsord section, upgrade note, sudo docker compose -f compose/compose.yaml throughout.
• Env examples: sponsord.env, sponsord-secret.env, sponsord-onramp.env. Contract addresses are left blank and point at the generated networks.yml.
• Updated: docs/requirements.md, docs/lifecycle.md, the root README.md, AGENTS.md, CONTRIBUTING.md and the ci.yml comment.

Test plan

• make lint (pre-commit)
• make lint-compose, plus negatives for an empty render (docker shim) and shell-env isolation
• make test-scripts: baseline + 47 compose variants
• make security-compose: 0 HIGH/CRITICAL; the MEDIUM/INFO findings are by design, as documented
• caddy validate / caddy fmt on compose/Caddyfile, and caddy adapt rejects the unset-domain default
• Smoke test with images built from local decdn/sponsord HEAD, pushed to a loopback registry:
  • sponsord reads its token, password and 0600 keystore as the host account and fails only at the unreachable RPC; its bind stays on loopback even with 0.0.0.0 in its env file;
  • the onramp, against a stub /v1/info, listens on 127.0.0.1:8080 only, reads its files, and serves /healthz and /decdn.sh over https through non-root Caddy;
  • restart sponsord also restarts the onramp, and an env-file change recreates the container on up -d.
• Not exercised: a real sponsord against a funded pool, and a real ACME certificate

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

The safety gate does not enforce that RPC secrets remain outside tracked Compose YAML.

Review effort: Balanced
Findings: 2

Open (2)

• Stop command leaves Caddy running on public ports · New
• Guard fails to enforce root-only secret env files · New

What changed in this PR

Adds profile-based Docker Compose deployment for sponsord, sponsord-onramp, and optional Caddy alongside the existing node.

Changes:

• Adds hardened, digest-pinned Compose services and configuration examples.
• Introduces security and fail-closed invariant checks with negative tests.
• Updates operational documentation and CI guidance.

File	Description
compose/​compose.yaml	Defines profile-based services and hardening.
compose/​Caddyfile	Adds TLS reverse proxy configuration.
compose/​.env.example	Documents profiles, images, and service identities.
compose/​decdn.env.example	Clarifies env-file quoting.
compose/​sponsord.env.example	Adds non-secret daemon settings.
compose/​sponsord-secret.env.example	Adds RPC secret template.
compose/​sponsord-onramp.env.example	Adds public onramp settings.
compose/​tests/​invariants.jq	Validates rendered security invariants.
compose/​tests/​fail-closed.jq	Validates unset-variable behavior.
compose/​README.md	Documents setup and operations.
tests/​scripts-test.sh	Expands Compose regression variants.
Makefile	Reworks the Compose lint target.
.github/​workflows/​ci.yml	Updates Compose CI documentation.
README.md	Advertises expanded Compose support.
docs/​requirements.md	Documents requirements and firewall ports.
docs/​lifecycle.md	Updates Compose shutdown guidance.
CONTRIBUTING.md	Describes the expanded lint gate.
AGENTS.md	Records Compose architecture and conventions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.