Skip to content

Docker: hardened image and Compose deployment - #13

Open
Skyfuller1303 wants to merge 10 commits into
itrycodinganditsbad:mainfrom
Skyfuller1303:docker
Open

Skyfuller1303 wants to merge 10 commits into
itrycodinganditsbad:mainfrom
Skyfuller1303:docker

Conversation

@Skyfuller1303

@Skyfuller1303 Skyfuller1303 commented Nov 4, 2026 •

Copy link
Copy Markdown

A Craft Cloud server can now be run with Docker Compose: one command builds a small, hardened image and starts the server behind Caddy for TLS. SQLite is the default; Postgres and S3 are optional overlays. This is meant as a starting point for M6 packaging; nothing in the server's behaviour changes apart from a new healthcheck subcommand.

Server

  • craft-cloud-server healthcheck [--addr <host:port>] sends GET /api/info to the local listener and exits 0 on a 2xx answer, 1 otherwise. It needs no shell or curl in the image, reads a bounded answer, accepts only a complete HTTP status line and has a short timeout. Numeric IPv4 and bracketed IPv6 addresses work.
  • Tests in tests/cli.rs cover a healthy answer, error statuses, a refused connection, a non-HTTP answer and a status line that is cut off or too long.

Image (packaging/docker/Dockerfile)

  • Multi-stage build; the runtime is distroless nonroot (uid 65532) with no shell. Base images are pinned by digest.
  • Entrypoint craft-cloud-server, default serve --config /etc/craft-cloud/config.toml, Docker HEALTHCHECK through the new subcommand.
  • OCI labels for version and revision; the version comes from the workspace Cargo.toml (workspace-version.sh).
  • .dockerignore keeps .git, target and local files out of the build context.

Compose (packaging/docker/compose*.yaml)

  • compose.yaml: server, Caddy and a one-shot secrets-init that renders config.toml from .env and secret files. Every service is read-only, drops all capabilities (Caddy adds only NET_BIND_SERVICE), runs with no-new-privileges, and has memory and pid limits. The server publishes no port; only Caddy does. The server sits on an internal network.
  • compose.postgres.yaml: Postgres 17 on its own internal network and a one-shot db-init that creates an unprivileged craft_cloud role owning its database and schema (no superuser, createdb, createrole, replication or bypassrls; PUBLIC loses CREATE). The superuser password reaches db-init only through a private passfile on a noexec tmpfs, never through the environment.
  • compose.s3.yaml: points the chunk store at an S3-compatible bucket; keys are passed as secret files.
  • Caddy: TLS modes acme, internal and custom (own certificate). trusted_proxies is set to Caddy's address, so the server's per-client rate limits still count each real client. Caddy's logs drop the request URI and headers, so /join/<code> links and bearer tokens never reach a log.
  • install.sh writes .env (mode 0600), builds the image, starts the stack and creates the first admin with the password read from stdin.
  • Values from .env are validated before they go into config.toml; a rejected value is named but never printed. A secret file with more than one line is refused.

Docs

docs/server.md gets a Docker section: quick start, what runs, configuration and secrets, TLS modes, Postgres, S3, the first admin, data, upgrades and backups, password rotation, troubleshooting and what isn't covered. README.md links to it.

Testing

  • cargo test -p craft-cloud-server --locked passes (61 lib, 76 api, 13 cli tests), with cargo fmt --check, cargo clippy -p craft-cloud-server --all-targets --locked -- -D warnings and cargo xtask licenses (661 crates on the allow-list). cargo check -p craft-cloud-server --all-targets --locked passes on Rust 1.94.
  • On Windows with Docker Desktop, the image builds (about 17.6 MB, no shell, uid 65532), and the SQLite, Postgres and S3 setups start healthy and survive restart and down/up. Two agents synced files through each setup and the downloads matched byte for byte (SHA-256).
  • Through Caddy, /api/info answers over TLS (internal CA, checked with curl -k), and the login limiter counted two clients separately: one got 429 after 30 failures while the other still got 401.
  • Checked with docker inspect and psql: the hardening flags and limits above, the Postgres role's privileges, Caddy unable to resolve db, no password in any container's environment, inspect output, image history or Caddy log.
  • Postgres password rotation: after a change, the server works with the new password, the old one is refused and a plain up -d does not bring it back.
  • The installer ran end to end and its log doesn't contain the admin password.
  • packaging/docker/tests/render-config.sh and tests/workspace-version.sh pass under Git Bash's sh; the scripts also ran for real under busybox inside the containers.

Not tested

  • The agent synced through a local-only test port straight to the server, not through Caddy, because the agent doesn't trust Caddy's internal CA. Caddy's TLS path was only checked with curl.
  • S3 only against a local HTTP mock (adobe/s3mock); no HTTPS endpoint and no real provider.
  • No Linux host, no shellcheck, no cargo xtask ci run for this branch (its test step runs out of memory under my 16 GiB limit on unmodified main as well, in an_app_that_misbehaves_is_refused_or_dropped_and_the_rest_go_on, see Agent test an_app_that_misbehaves_is_refused_or_dropped_and_the_rest_go_on needs more than 16 GiB #15).
  • The full workspace doesn't build on Rust 1.94 on main today (egui needs 1.95, and crates/sync uses if-let guards); only the server crate was checked on 1.94.

Left for later

  • A data volume with the wrong owner makes the server exit with "unable to open database file", and restart: unless-stopped then loops. The docs describe it; a clearer message would need a server change.
  • No published image or registry workflow; the image is built locally.
  • No systemd unit or non-Docker packaging.

The design follows a container setup from my own prototype (Skyfuller1303/craftcloud, MIT OR Apache-2.0), rewritten for Craft Cloud's server and config.

Skyfuller1303 and others added 9 commits November 3, 2026 22:55
`craft-cloud-server healthcheck [--addr 127.0.0.1:8080]` sends GET /api/info
over a plain TcpStream and exits 0 only on a 200 status line, within 3 s.
Otherwise it exits 1 with one line on stderr. It prints nothing on stdout and
adds no dependency. A container image without a shell or curl can use it as
its health check.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ment

packaging/docker holds a Dockerfile (Debian trixie build, distroless cc
runtime as uid 65532, base images pinned by digest) and a Compose deployment:
the server behind Caddy for TLS (acme, internal or custom certificates), with
SQLite and the local disk by default and overlays for Postgres and S3.

Secrets never reach a service's environment. A one-shot secrets-init service
renders config.toml from a template and writes the secret files into a volume;
every other service mounts only its own directory read-only. Every service has
a read-only root, no capabilities and no-new-privileges. Caddy has a fixed
address that the config lists in trusted_proxies.

install.sh writes .env with random passwords, builds the image, starts the
stack and creates the first admin from a password read on stdin. The Docker
section in docs/server.md covers use, TLS, Postgres, S3, upgrading and what is
not covered. The Dockerfile uses the healthcheck subcommand.

Derived from the deployment in Skyfuller1303/craftcloud (deploy/compose),
written by the same author, MIT OR Apache-2.0, adapted to this repository's
TOML-only configuration.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The request used bare line feeds instead of CRLF, and an answer that is not
HTTP at all was reported as a bad status. Send CRLF line endings and report
"not an HTTP answer" unless the first word is an HTTP version.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
An answer that stopped inside the status line ("HTTP/1.1 200" and then EOF) or
filled the 64 byte buffer without a line end counted as healthy or as a bad
status. Now only a status line that ends in CRLF is read, and the other cases
are errors. Tests cover a truncated line, a line that does not end and a bare
line feed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
When the server is down, Caddy's error log entry for a failed request carried
the full request URI and headers, so an invite code (/join/<code>), a query
or a bearer token could end up in the log. The default log now drops
request>uri and request>headers. Caddy also skips installing its internal CA
into the container, which only produced an error line.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
db-init exported PGPASSWORD, which put the superuser password in the
environment of the shell and of psql. It now writes a mode 0600 password file
on a tmpfs, passes only PGPASSFILE and removes the file on exit. The
db-init service gets a small noexec tmpfs for it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…docs

The server started before Caddy and was given 172.29.215.2, the address
reserved for Caddy, so Caddy failed to start. The frontend network now hands
out dynamic addresses from CC_FRONTEND_POOL (the upper half by default). The
docs name the new setting, the error of a data directory with the wrong owner
and what was tried with S3.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
render-config.sh read only the first line of a secret file, so a database
password with a second line passed the check while db-init, which reads the
whole file, set a different password than the one in config.toml. The whole
file is read now, one trailing line feed is allowed and any other line feed is
refused. The tests cover a second line, an empty second line and the allowed
trailing line feed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Compose gives a container its secrets from .env when it is created. After
`docker compose run --rm secrets-init`, a later `up -d db-init` started the
original secrets-init container again, which wrote the old values back. The
docs and the script comment now say to recreate it (`up -d --force-recreate
secrets-init`) before restarting the services that read the files.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The locked egui 0.36 crates need rustc 1.95, so the image built from
rust:1.94-trixie fails once the workspace's rust-version is raised to
1.95: "rustc 1.94.1 is not supported by the following packages".
Rust 1.95 also builds the current workspace, so this does not depend on
the order in which the two changes land.
Skyfuller1303 added a commit to Skyfuller1303/craft-cloud that referenced this pull request Nov 6, 2026
@Skyfuller1303

Copy link
Copy Markdown
Author

Pushed 9003994: the image now builds from rust:1.95-trixie (pinned by its index digest).

With #26 merged, the workspace's rust-version is 1.95, and the image built from rust:1.94-trixie stopped at cargo build with "rustc 1.94.1 is not supported by the following packages: craft-cloud-api@0.1.0 requires rustc 1.95". Rust 1.95 builds main as it is today too, so this works whichever of the two lands first. I built the image from this branch alone and from #34 (which contains every open PR).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant