From 0b44611441d82a5e50f4616db70d83b07163418a Mon Sep 17 00:00:00 2001 From: Skyfuller1303 Date: Tue, 3 Nov 2026 22:55:30 +0100 Subject: [PATCH 001/158] server: add healthcheck subcommand `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 --- apps/craft-cloud-server/src/cli.rs | 67 ++++++++++++++++- apps/craft-cloud-server/tests/cli.rs | 103 +++++++++++++++++++++++++++ 2 files changed, 169 insertions(+), 1 deletion(-) diff --git a/apps/craft-cloud-server/src/cli.rs b/apps/craft-cloud-server/src/cli.rs index a9b4908e..e09e8a5d 100644 --- a/apps/craft-cloud-server/src/cli.rs +++ b/apps/craft-cloud-server/src/cli.rs @@ -2,8 +2,9 @@ //! appear in the process list or shell history: `printf '%s\n' "$PASSWORD" | craft-cloud-server user add …`. use std::io::{BufRead, Read, Write}; -use std::net::{IpAddr, SocketAddr}; +use std::net::{IpAddr, SocketAddr, TcpStream}; use std::path::{Path, PathBuf}; +use std::time::{Duration, Instant}; use clap::{Parser, Subcommand}; use craft_cloud_meta::{Meta, Role, valid_username}; @@ -85,6 +86,13 @@ pub enum Command { #[command(subcommand)] action: LiveAction, }, + /// Ask a running server whether it answers (`GET /api/info`). Prints nothing and exits 0 if it does; otherwise + /// exits 1 with one line on standard error. For a container's health check, which has no shell and no `curl`. + Healthcheck { + /// The address the server listens on, as seen from here. + #[arg(long, default_value = "127.0.0.1:8080")] + addr: String, + }, } #[derive(Debug, Subcommand)] @@ -179,6 +187,11 @@ pub async fn run(command: Command, input: &mut impl BufRead, out: &mut impl Writ init(&dir, &admin, &listen, (behind_proxy, &trusted_proxies), input, out).await } Command::Serve { .. } => Err(CliError::Usage("serve is run by main".into())), + Command::Healthcheck { addr } => { + let addr: SocketAddr = addr.parse().map_err(|_| CliError::Usage(format!("bad address {addr}")))?; + // Blocking for at most `HEALTH_TIMEOUT`: this process does nothing else. + check_health(addr, HEALTH_TIMEOUT) + } Command::User { config, action } => { let config = Config::load(&config_path(config)?)?; let (meta, _) = open(&config).await?; @@ -259,6 +272,50 @@ pub async fn run(command: Command, input: &mut impl BufRead, out: &mut impl Writ } } +/// How long `healthcheck` waits for the whole exchange: connecting, sending and reading the status line. +pub const HEALTH_TIMEOUT: Duration = Duration::from_secs(3); + +/// Sends `GET /api/info` to `addr` and succeeds only if the status line says 200. The whole exchange must finish +/// within `timeout`. The body is never read, and nothing the server sends is printed. +pub fn check_health(addr: SocketAddr, timeout: Duration) -> Result<(), CliError> { + let fail = |what: &str| CliError::Usage(format!("{addr} is not healthy: {what}")); + let deadline = Instant::now() + timeout; + let left = || deadline.checked_duration_since(Instant::now()).filter(|d| !d.is_zero()); + let mut stream = TcpStream::connect_timeout(&addr, timeout).map_err(|e| fail(&format!("can't connect: {e}")))?; + let request = format!("GET /api/info HTTP/1.0 +Host: {addr} +Connection: close + +"); + stream.set_write_timeout(left()).map_err(|e| fail(&e.to_string()))?; + stream.write_all(request.as_bytes()).map_err(|e| fail(&format!("can't send the request: {e}")))?; + // The status line fits in 64 bytes; a server that sends more before a line ending is not answering HTTP. + let mut head = [0u8; 64]; + let mut len = 0; + loop { + let wait = left().ok_or_else(|| fail("no answer in time"))?; + stream.set_read_timeout(Some(wait)).map_err(|e| fail(&e.to_string()))?; + let Some(room) = head.get_mut(len..).filter(|room| !room.is_empty()) else { break }; + match stream.read(room) { + Ok(0) => break, + Ok(n) => len += n, + Err(e) if matches!(e.kind(), std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut) => return Err(fail("no answer in time")), + Err(e) => return Err(fail(&format!("can't read the answer: {e}"))), + } + if head.get(..len).is_some_and(|read| read.contains(&b' +')) { + break; + } + } + let line = String::from_utf8_lossy(head.get(..len).unwrap_or_default()); + let mut parts = line.split_whitespace(); + match (parts.next(), parts.next()) { + (Some(version), Some("200")) if version.starts_with("HTTP/1.") => Ok(()), + (Some(_), Some(status)) => Err(fail(&format!("status {}", status.chars().take(3).collect::()))), + _ => Err(fail("not an HTTP answer")), + } +} + /// `user invite`: makes the invite and prints how to use it. The code is printed only here, never logged. async fn invite(meta: &Meta, config: &Config, username: &str, out: &mut impl Write) -> Result<(), CliError> { let code = Code::generate(INVITE_CHARS).map_err(|e| CliError::Usage(format!("the system random source failed: {e}")))?; @@ -513,6 +570,14 @@ mod tests { } } + #[test] + fn healthcheck_parses_with_and_without_an_address() { + let cli = Cli::try_parse_from(["craft-cloud-server", "healthcheck"]).unwrap(); + assert!(matches!(&cli.command, Command::Healthcheck { addr } if addr == "127.0.0.1:8080")); + let cli = Cli::try_parse_from(["craft-cloud-server", "healthcheck", "--addr", "127.0.0.1:9000"]).unwrap(); + assert!(matches!(&cli.command, Command::Healthcheck { addr } if addr == "127.0.0.1:9000")); + } + #[test] fn reset_epoch_takes_a_username_or_all_but_not_both_or_neither() { assert!(Cli::try_parse_from(["craft-cloud-server", "reset-epoch", "--config", "c.toml", "--all"]).is_ok()); diff --git a/apps/craft-cloud-server/tests/cli.rs b/apps/craft-cloud-server/tests/cli.rs index 4a5332bf..bef63f54 100644 --- a/apps/craft-cloud-server/tests/cli.rs +++ b/apps/craft-cloud-server/tests/cli.rs @@ -294,3 +294,106 @@ fn the_binary_serves_what_init_created() { assert!(body.starts_with("HTTP/1.1 200"), "{body}"); assert!(body.contains("\"chunker_params\":[\"fastcdc-v1\"]"), "{body}"); } + +/// A listener on a free loopback port that answers every connection with `reply` (or, with `None`, reads the +/// request and then stays silent until `hold` has passed), for `healthcheck` to ask. +fn fake_server(reply: Option<&'static str>, hold: Duration) -> std::net::SocketAddr { + use std::io::{Read, Write}; + let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + let addr = listener.local_addr().unwrap(); + std::thread::spawn(move || { + for conn in listener.incoming() { + let Ok(mut conn) = conn else { return }; + let mut request = [0u8; 512]; + let _ = conn.read(&mut request); + match reply { + Some(text) => { + let _ = conn.write_all(text.as_bytes()); + } + None => std::thread::sleep(hold), + } + } + }); + addr +} + +fn healthcheck(addr: std::net::SocketAddr) -> std::process::Output { + Process::new(env!("CARGO_BIN_EXE_craft-cloud-server")).args(["healthcheck", "--addr", &addr.to_string()]).output().unwrap() +} + +#[test] +fn healthcheck_succeeds_only_on_a_200() { + let ok = fake_server(Some("HTTP/1.1 200 OK\r\ncontent-length: 2\r\n\r\n{}"), Duration::ZERO); + let out = healthcheck(ok); + assert!(out.status.success()); + assert!(out.stdout.is_empty() && out.stderr.is_empty()); + + let broken = fake_server(Some("HTTP/1.1 500 Internal Server Error\r\ncontent-length: 0\r\n\r\n"), Duration::ZERO); + let out = healthcheck(broken); + assert_eq!(out.status.code(), Some(1)); + assert!(out.stdout.is_empty()); + let stderr = String::from_utf8(out.stderr).unwrap(); + assert_eq!(stderr.lines().count(), 1, "{stderr}"); + assert!(stderr.contains("status 500") && !stderr.contains("panicked"), "{stderr}"); + + let not_http = fake_server(Some("hello there\r\n"), Duration::ZERO); + let out = healthcheck(not_http); + assert_eq!(out.status.code(), Some(1)); + assert!(String::from_utf8(out.stderr).unwrap().contains("not an HTTP answer")); +} + +#[test] +fn healthcheck_fails_with_nobody_listening_and_with_a_bad_address() { + let port = std::net::TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port(); + let out = healthcheck(std::net::SocketAddr::from(([127, 0, 0, 1], port))); + assert_eq!(out.status.code(), Some(1)); + let stderr = String::from_utf8(out.stderr).unwrap(); + assert!(stderr.contains("can't connect") && !stderr.contains("panicked"), "{stderr}"); + + let out = Process::new(env!("CARGO_BIN_EXE_craft-cloud-server")).args(["healthcheck", "--addr", "not an address"]).output().unwrap(); + assert_eq!(out.status.code(), Some(1)); + assert!(String::from_utf8(out.stderr).unwrap().contains("bad address")); +} + +#[test] +fn healthcheck_gives_up_on_an_answer_that_never_comes() { + // Called in-process with a short timeout so the test stays quick; the binary uses `HEALTH_TIMEOUT`. + let silent = fake_server(None, Duration::from_secs(5)); + let started = Instant::now(); + let result = craft_cloud_server::cli::check_health(silent, Duration::from_millis(300)); + assert!(matches!(result, Err(CliError::Usage(m)) if m.contains("no answer in time"))); + assert!(started.elapsed() < Duration::from_secs(3)); + + let started = Instant::now(); + let out = healthcheck(silent); + assert_eq!(out.status.code(), Some(1)); + assert!(started.elapsed() < Duration::from_secs(4), "{:?}", started.elapsed()); +} + +#[test] +fn healthcheck_is_ok_against_the_real_server() { + let parent = tempfile::tempdir().unwrap(); + let dir = parent.path().join("data"); + let port = std::net::TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port(); + let exe = env!("CARGO_BIN_EXE_craft-cloud-server"); + let mut init = Process::new(exe) + .args(["init", "--dir", dir.to_str().unwrap(), "--admin", "ana", "--listen", &format!("127.0.0.1:{port}")]) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .spawn() + .unwrap(); + use std::io::Write; + init.stdin.take().unwrap().write_all(b"admin password 1\n").unwrap(); + assert!(init.wait().unwrap().success()); + let _server = + Server(Process::new(exe).args(["serve", "--config", dir.join("config.toml").to_str().unwrap()]).stderr(Stdio::null()).spawn().unwrap()); + let addr = std::net::SocketAddr::from(([127, 0, 0, 1], port)); + let deadline = Instant::now() + Duration::from_secs(20); + loop { + if healthcheck(addr).status.success() { + return; + } + assert!(Instant::now() < deadline, "the server never became healthy"); + std::thread::sleep(Duration::from_millis(100)); + } +} From 585e4b94d3d334ed89f0b4c6c2c47b179b100703 Mon Sep 17 00:00:00 2001 From: Skyfuller1303 Date: Tue, 3 Nov 2026 23:03:30 +0100 Subject: [PATCH 002/158] packaging: add a hardened container image and a Docker Compose deployment 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 --- .dockerignore | 20 ++ .gitignore | 3 + README.md | 2 +- docs/server.md | 151 +++++++++++++ packaging/docker/.env.example | 42 ++++ packaging/docker/.gitattributes | 2 + packaging/docker/Dockerfile | 63 ++++++ packaging/docker/caddy/Caddyfile | 57 +++++ packaging/docker/caddy/tls-acme.caddy | 3 + packaging/docker/caddy/tls-custom.caddy | 4 + packaging/docker/caddy/tls-internal.caddy | 2 + packaging/docker/compose.postgres.yaml | 96 ++++++++ packaging/docker/compose.s3.yaml | 29 +++ packaging/docker/compose.yaml | 147 +++++++++++++ packaging/docker/config.toml.in | 33 +++ packaging/docker/db-init.sh | 45 ++++ packaging/docker/install.sh | 231 ++++++++++++++++++++ packaging/docker/render-config.sh | 137 ++++++++++++ packaging/docker/secrets-init.sh | 90 ++++++++ packaging/docker/tests/render-config.sh | 121 ++++++++++ packaging/docker/tests/workspace-version.sh | 72 ++++++ packaging/docker/workspace-version.sh | 31 +++ 22 files changed, 1380 insertions(+), 1 deletion(-) create mode 100644 .dockerignore create mode 100644 packaging/docker/.env.example create mode 100644 packaging/docker/.gitattributes create mode 100644 packaging/docker/Dockerfile create mode 100644 packaging/docker/caddy/Caddyfile create mode 100644 packaging/docker/caddy/tls-acme.caddy create mode 100644 packaging/docker/caddy/tls-custom.caddy create mode 100644 packaging/docker/caddy/tls-internal.caddy create mode 100644 packaging/docker/compose.postgres.yaml create mode 100644 packaging/docker/compose.s3.yaml create mode 100644 packaging/docker/compose.yaml create mode 100644 packaging/docker/config.toml.in create mode 100755 packaging/docker/db-init.sh create mode 100755 packaging/docker/install.sh create mode 100755 packaging/docker/render-config.sh create mode 100755 packaging/docker/secrets-init.sh create mode 100755 packaging/docker/tests/render-config.sh create mode 100755 packaging/docker/tests/workspace-version.sh create mode 100755 packaging/docker/workspace-version.sh diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..72b5ef0a --- /dev/null +++ b/.dockerignore @@ -0,0 +1,20 @@ +# The build context of packaging/docker/Dockerfile is the repository root, because Cargo needs the manifests of +# every workspace member. Nothing here may reach the image: no history, no local data, no secrets. +.git +.github +target +**/target +/dist +/temp +/data +docs +packaging +**/*.md +.env +.env.* +**/.env +**/.env.* +*.sqlite +*.sqlite-wal +*.sqlite-shm +*~ diff --git a/.gitignore b/.gitignore index 6ea3d416..714e91fe 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,6 @@ target/ *.sqlite-shm # a snapshot test's own render when it doesn't match *.new.png +# the Docker deployment's settings and secrets (written by packaging/docker/install.sh), and a custom TLS certificate +/packaging/docker/.env +/packaging/docker/tls/ diff --git a/README.md b/README.md index 48d61966..3f0ecc60 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ that is signed in, and enter its code on the new one. ## Documentation - [Installing the Craft Cloud app](docs/install.md) on Windows, macOS and Linux -- [Running the server](docs/server.md): reverse proxy, Postgres and S3, accounts, invites, backups +- [Running the server](docs/server.md): reverse proxy, Postgres and S3, accounts, invites, backups, Docker - [The agent on the command line](docs/agent.md): `login`, `run`, `sync`, `join`, start at login - [Development](docs/development.md): how it fits together, building, testing, the sync engine's rules - [The app kit](docs/kit.md): how a Craft app makes its documents live diff --git a/docs/server.md b/docs/server.md index bf2a6492..c973d5af 100644 --- a/docs/server.md +++ b/docs/server.md @@ -71,3 +71,154 @@ every machine then sends up what the emptied log lacks, so nothing any machine h affected. A document whose own history is over 16 MiB stays full until compacting the log is supported. An account may have 64 live documents holding updates and 1,024 in all (one per app today); past that, new ones stay on the machines. Live documents can't be deleted yet. + +## Docker + +`packaging/docker/` holds a hardened container image of the server and a Docker Compose deployment: the server +behind Caddy, which terminates TLS. By default the database (SQLite) and the blobs live on a Docker volume; Postgres +and S3 are overlays. It needs Docker Compose 2.32 or newer on Linux and builds the image locally: there is no image +to pull and nothing is published to a registry. The first build wants about 4 GiB of memory for the Docker engine (it +uses two compiler jobs). + +### Quick start + +```sh +cd packaging/docker +./install.sh --domain cloud.example.org --admin you +``` + +`install.sh` checks Docker and the free disk space, writes `.env` (mode 0600, never committed) with random database +passwords, builds the image, starts the stack and creates the first admin. The admin's password is asked for without +echo, or read from a pipe, and reaches the server through standard input only. On a terminal it asks for the +settings you did not give; `./install.sh --help` lists the options (`--tls acme|internal|custom`, `--email`, +`--db sqlite|postgres`, `--http-port`, `--https-port`, `--no-admin`, `--no-start`). It never overwrites an existing +`.env`. Afterwards `docker compose ps` and `docker compose logs -f server` show the state, and the domain's +`/api/info` answers through Caddy. + +To set it up by hand, copy `.env.example` to `.env`, fill it in, and run `docker compose build` and +`docker compose up -d --wait`. + +### What runs + +| Service | Image | Notes | +|---|---|---| +| `server` | built from `packaging/docker/Dockerfile` | distroless `cc`, uid 65532, plain HTTP on port 8080 inside the stack | +| `caddy` | `caddy:2.11-alpine` | the only service with published ports (80 and 443); TLS and the redirect from HTTP | +| `secrets-init` | `caddy:2.11-alpine` | one-shot, no network: renders `config.toml` and writes the secret files | +| `db`, `db-init` | `postgres:17-alpine` | only with `compose.postgres.yaml` | + +Every base image is pinned by the digest of its multi-arch index, with the tag in a comment next to it. To update +one, change the tag and the digest together (`docker buildx imagetools inspect :` prints the index +digest). + +Every service has a read-only root filesystem, no capabilities (`cap_drop: [ALL]`), `no-new-privileges`, memory and +process limits, and a `noexec` tmpfs for `/tmp`. The exceptions are explained next to each service: Postgres and +`secrets-init` start as root and need a few capabilities to fix ownership, Caddy needs to bind ports 80 and 443, and +`secrets-init` (in the Postgres and S3 overlays) is not read-only because Compose writes its secret files into the +root filesystem. + +Three networks keep the parts apart: `edge` (published ports and outbound access, Caddy only), `frontend` (internal; +Caddy to the server) and `backend` (internal; the server to Postgres, Caddy is not attached). + +### Configuration and secrets + +The server reads only its TOML file. `config.toml.in` is the template and `render-config.sh` fills it. The +`secrets-init` service renders it into the `secrets` volume (mode 0400, owner 65532) and the server mounts it +read-only at `/etc/craft-cloud/config.toml`. The file holds the database URL (with the password, for Postgres) and, +for S3, the keys. The server's `Debug` output hides the URL's credentials, and `docker inspect` of the running +services shows no secret, since none is in an environment or a Compose file. The values are checked against short +lists of allowed characters before they are written, so a value cannot break the TOML or add a setting. + +To change a setting in `.env` (`CC_*`, see `.env.example`), edit the file, run `docker compose run --rm secrets-init` +and then `docker compose up -d`. + +The server believes `X-Forwarded-For` only from Caddy. `trusted_proxies` takes single addresses, no networks, so +Caddy has a fixed address (`CC_CADDY_IP`, `172.29.215.2` in the network `CC_FRONTEND_SUBNET`, `172.29.215.0/24`). If +these defaults clash with a network on your host, change both together. + +### TLS modes + +Set `CC_TLS_MODE` in `.env`: + +- `acme` (default): a public certificate from Let's Encrypt. The domain must resolve to the host, and the ports must + be reachable from the internet (with other ports, set `CC_HTTP_PORT`, `CC_HTTPS_PORT` and a matching + `CC_PUBLIC_URL`). +- `internal`: a certificate from Caddy's own CA, for tests. Clients do not trust it. There is no HSTS in this mode. +- `custom`: your own certificate. Put `fullchain.pem` and `private.key` in `packaging/docker/tls/` (or `CC_TLS_DIR`), + readable by root only, and restart Caddy to load a renewed one. + +Caddy sets a request header timeout of 10 seconds, as the checklist above asks. It writes no access log, because URLs hold invite +codes (`/join/`). + +### Postgres + +```sh +./install.sh --domain cloud.example.org --db postgres +``` + +or add `COMPOSE_FILE=compose.yaml:compose.postgres.yaml` to `.env`. This adds a Postgres container and a one-shot +`db-init` that creates the role `craft_cloud`. The server migrates its database when it opens it, so that role owns +the database `craft_cloud` and its schema and may change them. That is less separation than an owner role plus a +runtime role. The role is not a superuser and has no other privileges; `PUBLIC` may not connect to the database or +create in its schema, and the role cannot connect to `postgres` or `template1`. The superuser password exists only +for the Postgres container and `db-init`. Blobs stay on the data volume. + +To rotate the database password, change `CC_SECRET_DB_PASSWORD` in `.env` (characters from `A-Za-z0-9._~-`, at least +32), then run `docker compose run --rm secrets-init`, `docker compose up -d db-init` and +`docker compose restart server`. The superuser password cannot be changed that way: Postgres applies it only when +the data directory is created. Change it with `ALTER ROLE postgres` first and then in `.env`. + +The connection between the server and Postgres is not encrypted (the server's `sqlx` has no TLS feature). It never +leaves the internal `backend` network. An external Postgres over TLS is not covered. + +### S3 + +`compose.s3.yaml` replaces the disk storage with an S3 bucket: fill in the `CC_S3_*` and `CC_SECRET_S3_*` lines of +`.env.example` in `.env` and add `compose.s3.yaml` to `COMPOSE_FILE`. The keys end up in `config.toml` like the +database password, not in the server's environment. The server joins the `edge` network to reach the endpoint. The +image holds the CA certificates the server needs for HTTPS endpoints. This overlay has only been written, not yet +run against a real S3 service. + +### The first admin and more accounts + +`install.sh` creates the first admin. By hand, with the password on standard input: + +```sh +printf '%s\n' 'a password' | docker compose run --rm --no-deps -T server user --config /etc/craft-cloud/config.toml add --admin you +``` + +More accounts: the same line without `--admin`, or `docker compose run --rm --no-deps server user --config +/etc/craft-cloud/config.toml invite name`, which prints the whole join string because `public_url` is set. The +other commands of this guide (`device`, `reset-epoch`, `live`) run the same way. + +### Data, upgrading and backups + +The data is in the volume `data` (`/var/lib/craft-cloud` in the container): `meta.db` (with SQLite) and `blobs/`. +The image creates the directory for uid 65532 with mode 0700, so a new named volume gets that owner. A bind mount +instead of the volume must be prepared first: `chown 65532:65532 DIR && chmod 0700 DIR`. + +To upgrade, update the source, then run `docker compose build server` and `docker compose up -d --wait`. The server +migrates the database when it opens it and refuses a database newer than itself, so back up before an upgrade and do +not go back to an older image without the backup. + +There is no backup automation yet. Stop the server (`docker compose stop server`), copy the volume (SQLite: +`meta.db`, `meta.db-wal`, `meta.db-shm` and `blobs/` together; Postgres: `pg_dump` from the `db` container plus +`blobs/`), and start it again. Restoring is described above, including `reset-epoch`. + +`docker compose down` keeps the volumes. `docker compose down -v` deletes all data. + +### Troubleshooting + +- `secrets-init` fails with a message such as `PUBLIC_URL has a value that is empty or has characters that are not + allowed`: a setting in `.env` is wrong. The message names the setting and never shows the value. +- The server exits at once with a permission error on `/var/lib/craft-cloud`: the data directory is not owned by + 65532 (see bind mounts above). +- `server` is not healthy: `docker compose logs server`. The check is `craft-cloud-server healthcheck`, a + `GET /api/info` request to `127.0.0.1:8080` inside the container. +- All devices share one sign-in budget: `trusted_proxies` does not contain Caddy's address. `CC_CADDY_IP` must lie in + `CC_FRONTEND_SUBNET`; run `docker compose run --rm secrets-init` after changing either. + +### Not covered + +Postgres over TLS, TLS in the server itself (Caddy terminates it), Kubernetes or Helm files, a registry image and +release automation, and backup automation (copy the data as above until the server can create backups itself). diff --git a/packaging/docker/.env.example b/packaging/docker/.env.example new file mode 100644 index 00000000..3304eb76 --- /dev/null +++ b/packaging/docker/.env.example @@ -0,0 +1,42 @@ +# Settings of the Docker deployment. install.sh writes a real `.env` from this list (mode 0600, never committed); +# copy this file to `.env` and fill it in by hand if you do not use install.sh. Nothing in this file is a secret. + +# --- required --------------------------------------------------------------- +# The domain computers reach the server at, and the matching public URL (add :port if HTTPS is not on 443). +CC_DOMAIN=cloud.example.org +CC_PUBLIC_URL=https://cloud.example.org + +# --- TLS --------------------------------------------------------------------- +# acme (Let's Encrypt), internal (Caddy's own CA, for tests) or custom (files in CC_TLS_DIR). +CC_TLS_MODE=acme +CC_ACME_EMAIL= +CC_TLS_DIR=./tls +CC_HTTP_PORT=80 +CC_HTTPS_PORT=443 + +# --- image ------------------------------------------------------------------- +CC_IMAGE=craft-cloud:local +CC_VERSION=0.0.0 +CC_REVISION=unknown + +# --- networks ------------------------------------------------------------------ +# Caddy's fixed address on the internal frontend network. The server believes X-Forwarded-For from this address only +# (trusted_proxies takes single addresses, no networks), so it must lie inside CC_FRONTEND_SUBNET. +CC_FRONTEND_SUBNET=172.29.215.0/24 +CC_CADDY_IP=172.29.215.2 +CC_EDGE_SUBNET=172.29.216.0/24 + +# --- secrets (the Postgres profile; install.sh fills them with random values) ----------------------------------- +# Only characters A-Z a-z 0-9 . _ ~ - and at least 32 of them: the database password becomes part of a database URL. +CC_SECRET_DB_SUPERUSER_PASSWORD= +CC_SECRET_DB_PASSWORD= + +# --- S3 storage (compose.s3.yaml) ---------------------------------------------------------------------------- +CC_S3_BUCKET= +CC_S3_PREFIX= +CC_S3_REGION=us-east-1 +# Leave empty for Amazon S3; set it for MinIO and other S3-compatible services. +CC_S3_ENDPOINT= +CC_S3_ALLOW_HTTP=false +CC_SECRET_S3_ACCESS_KEY_ID= +CC_SECRET_S3_SECRET_ACCESS_KEY= diff --git a/packaging/docker/.gitattributes b/packaging/docker/.gitattributes new file mode 100644 index 00000000..0c6475c3 --- /dev/null +++ b/packaging/docker/.gitattributes @@ -0,0 +1,2 @@ +# Scripts and configs are mounted into Linux containers and must keep LF line endings. +* text eol=lf diff --git a/packaging/docker/Dockerfile b/packaging/docker/Dockerfile new file mode 100644 index 00000000..3cff90cd --- /dev/null +++ b/packaging/docker/Dockerfile @@ -0,0 +1,63 @@ +# Container image of craft-cloud-server: a Debian trixie build stage and a distroless runtime that holds the binary +# and nothing else (no shell, no package manager). It runs as uid 65532. +# +# The build context is the repository root, because Cargo needs the manifests of all workspace members: +# docker build -f packaging/docker/Dockerfile -t craft-cloud:local . +# docker build -f packaging/docker/Dockerfile --build-arg CRAFT_CLOUD_VERSION=0.1.0 \ +# --build-arg CRAFT_CLOUD_REVISION="$(git rev-parse HEAD)" -t craft-cloud:0.1.0 . +# +# Every base image is pinned by the digest of its multi-arch index; the tag in the comment is for humans. Update +# the tag and the digest together (see "Docker" in docs/server.md). + +# rust:1.94-trixie (the workspace's rust-version; glibc 2.41 like the runtime image below) +ARG RUST_IMAGE=rust:1.94-trixie@sha256:652612f07bfbbdfa3af34761c1e435094c00dde4a98036132fca28c7bb2b165c +# debian:trixie-slim (only used to create the data directory with its owner and mode) +ARG DEBIAN_IMAGE=debian:trixie-slim@sha256:f6b08b09a05725f9431502d3b5714f5c4576e82c1a84fa1debe0c24a7e0c3ec4 +# gcr.io/distroless/cc-debian13:nonroot (glibc, libgcc and CA certificates; no shell, no package manager; uid 65532) +ARG RUNTIME_IMAGE=gcr.io/distroless/cc-debian13:nonroot@sha256:08476c244888bfb425bae1ae4dd7c17f093e972aab8426883d97f3c6f280f7c1 + +# ---- build --------------------------------------------------------------------- +FROM ${RUST_IMAGE} AS build +# Docker builds often run in a small VM: keep the compiler's parallelism and memory use low. +ENV CARGO_BUILD_JOBS=2 \ + CARGO_INCREMENTAL=0 \ + CARGO_PROFILE_RELEASE_STRIP=symbols +WORKDIR /src +COPY Cargo.toml Cargo.lock ./ +# Cargo resolves every workspace member, including the apps and xtask, even when only the server package is built. +# Nothing of them but the server enters the image. +COPY .cargo .cargo +COPY crates crates +COPY apps apps +COPY xtask xtask +RUN cargo build --release --locked -p craft-cloud-server \ + && install -D target/release/craft-cloud-server /out/craft-cloud-server + +# ---- files that need a shell to create --------------------------------------------- +FROM ${DEBIAN_IMAGE} AS files +# The data directory belongs to the runtime user from the start, so a fresh named volume inherits the owner and the +# mode 0700. +RUN install -d -m 0700 -o 65532 -g 65532 /rootfs/var/lib/craft-cloud + +# ---- runtime ----------------------------------------------------------------------- +FROM ${RUNTIME_IMAGE} +ARG CRAFT_CLOUD_VERSION=0.0.0 +ARG CRAFT_CLOUD_REVISION=unknown +LABEL org.opencontainers.image.title="craft-cloud-server" \ + org.opencontainers.image.description="Self-hosted sync and storage server for the Craft App Suite" \ + org.opencontainers.image.source="https://github.com/itrycodinganditsbad/craft-cloud" \ + org.opencontainers.image.licenses="MIT OR Apache-2.0" \ + org.opencontainers.image.version="${CRAFT_CLOUD_VERSION}" \ + org.opencontainers.image.revision="${CRAFT_CLOUD_REVISION}" +COPY --from=files --chown=65532:65532 /rootfs/var/lib/craft-cloud /var/lib/craft-cloud +COPY --from=build /out/craft-cloud-server /usr/local/bin/craft-cloud-server +USER 65532:65532 +EXPOSE 8080 +# The SQLite database and the blob storage (when it is on disk) live here: the only writable place besides /tmp. +VOLUME ["/var/lib/craft-cloud"] +# The image has no shell and no curl: the binary asks its own listener (GET /api/info on 127.0.0.1:8080). +HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 \ + CMD ["/usr/local/bin/craft-cloud-server", "healthcheck"] +ENTRYPOINT ["/usr/local/bin/craft-cloud-server"] +# The config file is mounted by Compose; see packaging/docker/compose.yaml. +CMD ["serve", "--config", "/etc/craft-cloud/config.toml"] diff --git a/packaging/docker/caddy/Caddyfile b/packaging/docker/caddy/Caddyfile new file mode 100644 index 00000000..762ea433 --- /dev/null +++ b/packaging/docker/caddy/Caddyfile @@ -0,0 +1,57 @@ +# Reverse proxy of the Docker deployment: TLS in front of craft-cloud-server, which speaks plain HTTP only. +# +# CC_DOMAIN, CC_PUBLIC_URL, CC_TLS_MODE and CC_ACME_EMAIL come from the Compose environment: +# acme a public certificate from Let's Encrypt (the domain must resolve here, ports 80 and 443 be reachable) +# internal a certificate from Caddy's own CA, for local tests (browsers warn) +# custom your own certificate: fullchain.pem and private.key in the directory CC_TLS_DIR + +{ + # Not exposed: the admin API listens on loopback inside this container only. + admin localhost:2019 + email "{$CC_ACME_EMAIL}" + + servers { + timeouts { + # The server cuts off slow request bodies itself, but asks the proxy to bound the request headers. + read_header 10s + } + } +} + +# Plain HTTP: redirect to the configured public URL, which keeps a port other than 443. An explicit site for the HTTP +# address replaces Caddy's automatic redirect, which would drop the port. ACME HTTP challenges are answered before this. +http://{$CC_DOMAIN} { + redir {$CC_PUBLIC_URL}{uri} 308 +} + +{$CC_DOMAIN} { + import tls-{$CC_TLS_MODE}.caddy + + # Only fills in the generic headers where the server sent none (the leading `?`). HSTS comes from the tls file of + # a real certificate; a test certificate must not pin the browser to HTTPS. + header { + ?X-Content-Type-Options "nosniff" + -Server + } + + # No `request_body { max_size ... }` on purpose: uploads are streamed and the server limits each route itself. + reverse_proxy server:8080 { + # Pass response bytes on at once: downloads stream and nothing is held back. + flush_interval -1 + + # Send requests only while the server answers its info endpoint. + health_uri /api/info + health_status 200 + health_interval 10s + health_timeout 3s + + transport http { + dial_timeout 5s + # The time until the server starts to answer; there is no limit on how long a body takes to transfer. + response_header_timeout 60s + } + } + + # No access log on purpose: a log of full URLs would keep invite codes (/join/). If you need one, drop the + # path and the query, and never write the Authorization and Cookie headers. +} diff --git a/packaging/docker/caddy/tls-acme.caddy b/packaging/docker/caddy/tls-acme.caddy new file mode 100644 index 00000000..676383aa --- /dev/null +++ b/packaging/docker/caddy/tls-acme.caddy @@ -0,0 +1,3 @@ +# A certificate from Caddy's default public issuers (Let's Encrypt, ZeroSSL). Nothing to configure. +# HSTS only with a real certificate, so not in the internal mode. +header Strict-Transport-Security "max-age=31536000" diff --git a/packaging/docker/caddy/tls-custom.caddy b/packaging/docker/caddy/tls-custom.caddy new file mode 100644 index 00000000..e26ac61d --- /dev/null +++ b/packaging/docker/caddy/tls-custom.caddy @@ -0,0 +1,4 @@ +# Your own certificate: the directory CC_TLS_DIR holds fullchain.pem and private.key and is mounted read-only at +# /certs. Keep the key readable by root only. Caddy reads the files at start; restart it to load a renewed one. +tls /certs/fullchain.pem /certs/private.key +header Strict-Transport-Security "max-age=31536000" diff --git a/packaging/docker/caddy/tls-internal.caddy b/packaging/docker/caddy/tls-internal.caddy new file mode 100644 index 00000000..06e1f32c --- /dev/null +++ b/packaging/docker/caddy/tls-internal.caddy @@ -0,0 +1,2 @@ +# A certificate from Caddy's internal CA. For tests only: browsers and agents do not trust it. No HSTS. +tls internal diff --git a/packaging/docker/compose.postgres.yaml b/packaging/docker/compose.postgres.yaml new file mode 100644 index 00000000..651e79b8 --- /dev/null +++ b/packaging/docker/compose.postgres.yaml @@ -0,0 +1,96 @@ +# Overlay for Postgres instead of SQLite: +# docker compose -f compose.yaml -f compose.postgres.yaml up -d --wait +# Adds the `db` container (on the internal `backend` network, which Caddy is not attached to) and `db-init`, which +# creates the server's database role. The data volume still holds the blobs. +# +# The connection is not encrypted: the server's sqlx has no TLS feature. That is acceptable on an internal network of +# one host only. An external Postgres over TLS is not covered. + +x-postgres-image: &postgres-image postgres:17-alpine@sha256:266d3c257594e195b309ae9d1805e54c788f1d7b375f56bf6c367aac6c917e7b + +services: + # Compose puts a file secret into the container's root filesystem, so this one service cannot be read-only here. + secrets-init: + read_only: false + environment: + DB_KIND: postgres + secrets: + - db_superuser_password + - db_password + + db: + read_only: true + cap_drop: [ALL] + security_opt: ["no-new-privileges:true"] + restart: unless-stopped + image: *postgres-image + environment: + POSTGRES_DB: craft_cloud + POSTGRES_USER: postgres + POSTGRES_PASSWORD_FILE: /run/secrets/db_superuser_password + POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256 --data-checksums" + volumes: + - pgdata:/var/lib/postgresql/data + # Read by the image's entrypoint while it still runs as root. + - type: volume + source: secrets + target: /run/secrets + read_only: true + volume: {subpath: db} + depends_on: + secrets-init: {condition: service_completed_successfully} + tmpfs: + - /tmp + - /run/postgresql + # The entrypoint starts as root to fix the ownership of the data directory and then drops to the postgres user; it + # needs exactly these capabilities. + cap_add: [CHOWN, FOWNER, DAC_OVERRIDE, SETUID, SETGID] + healthcheck: + test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "postgres", "-d", "craft_cloud"] + interval: 5s + timeout: 5s + retries: 20 + start_period: 20s + networks: [backend] + mem_limit: 1g + pids_limit: 200 + stop_grace_period: 60s + + # Creates the database role of the server, or refreshes its password. Runs on every `up`; safe to run again. + db-init: + read_only: true + cap_drop: [ALL] + security_opt: ["no-new-privileges:true"] + restart: "no" + image: *postgres-image + # The postgres user of the alpine image. + user: "70:70" + entrypoint: ["/bin/sh", "/db-init.sh"] + environment: + PGHOST: db + PGDATABASE: craft_cloud + volumes: + - ./db-init.sh:/db-init.sh:ro + - type: volume + source: secrets + target: /run/secrets + read_only: true + volume: {subpath: db-init} + depends_on: + db: {condition: service_healthy} + healthcheck: {disable: true} + networks: [backend] + mem_limit: 128m + pids_limit: 50 + + server: + depends_on: + db-init: {condition: service_completed_successfully} + networks: [backend] + +volumes: + pgdata: {} + +secrets: + db_superuser_password: {environment: CC_SECRET_DB_SUPERUSER_PASSWORD} + db_password: {environment: CC_SECRET_DB_PASSWORD} diff --git a/packaging/docker/compose.s3.yaml b/packaging/docker/compose.s3.yaml new file mode 100644 index 00000000..dc3561b4 --- /dev/null +++ b/packaging/docker/compose.s3.yaml @@ -0,0 +1,29 @@ +# Overlay for S3-compatible storage instead of the local disk (combine it with compose.postgres.yaml if you like): +# docker compose -f compose.yaml -f compose.s3.yaml up -d --wait +# Set CC_S3_* and CC_SECRET_S3_* in .env. The keys go into config.toml (mode 0400, readable by the server only) like +# the database password; they are not in the server's environment. +# +# The server needs a route to the S3 endpoint, so it also joins the `edge` network, the only one with outbound access. +# That network publishes no port of the server. + +services: + # Compose puts a file secret into the container's root filesystem, so this one service cannot be read-only here. + secrets-init: + read_only: false + environment: + STORAGE_KIND: s3 + S3_BUCKET: ${CC_S3_BUCKET:?set CC_S3_BUCKET in .env} + S3_PREFIX: ${CC_S3_PREFIX:-} + S3_REGION: ${CC_S3_REGION:-us-east-1} + S3_ENDPOINT: ${CC_S3_ENDPOINT:-} + S3_ALLOW_HTTP: ${CC_S3_ALLOW_HTTP:-false} + secrets: + - s3_access_key_id + - s3_secret_access_key + + server: + networks: [edge] + +secrets: + s3_access_key_id: {environment: CC_SECRET_S3_ACCESS_KEY_ID} + s3_secret_access_key: {environment: CC_SECRET_S3_SECRET_ACCESS_KEY} diff --git a/packaging/docker/compose.yaml b/packaging/docker/compose.yaml new file mode 100644 index 00000000..20f77d9f --- /dev/null +++ b/packaging/docker/compose.yaml @@ -0,0 +1,147 @@ +# Docker Compose deployment of Craft Cloud: the server (SQLite and local disk) behind Caddy, which terminates TLS. +# Postgres and S3 are overlays: -f compose.yaml -f compose.postgres.yaml [-f compose.s3.yaml]. See "Docker" in +# docs/server.md, and run ./install.sh for a first setup. +# +# ./install.sh # writes .env, builds the image, starts the stack +# docker compose up -d --wait # after that +# +# Secrets never appear in this file or in the environment of a service that runs. Compose reads them from the +# gitignored .env and gives them to the one-shot `secrets-init` service only, which writes them as files (mode 0400, +# owned by the reading user) into the `secrets` volume. Every other service mounts just its own subdirectory +# read-only. +# +# Volume subpaths (used below) need Docker Compose 2.32 or newer. + +name: craft-cloud + +x-hardening: &hardening + read_only: true + cap_drop: [ALL] + security_opt: ["no-new-privileges:true"] + restart: "no" + +services: + # Renders config.toml and distributes the secrets (see secrets-init.sh). It has no network at all, runs as root for + # about a second and needs only the capabilities to change the owner and mode of the files it writes. + secrets-init: + <<: *hardening + # Any image with busybox will do; the one of Caddy is needed anyway. + image: caddy:2.11-alpine@sha256:e70b164da81ef698b3ad19af799ea6086ce6d9e48ed4079eb9fe26f6fbf14ee5 + user: "0:0" + entrypoint: ["/bin/sh", "/secrets-init.sh"] + network_mode: none + cap_add: [CHOWN, DAC_OVERRIDE, FOWNER] + # Not secrets: what render-config.sh puts into config.toml. + environment: + PUBLIC_URL: ${CC_PUBLIC_URL:?set CC_PUBLIC_URL in .env, or run ./install.sh} + TRUSTED_PROXY: ${CC_CADDY_IP:-172.29.215.2} + DB_KIND: sqlite + STORAGE_KIND: disk + volumes: + - ./secrets-init.sh:/secrets-init.sh:ro + - ./render-config.sh:/render-config.sh:ro + - ./config.toml.in:/config.toml.in:ro + - secrets:/out + healthcheck: {disable: true} + mem_limit: 64m + pids_limit: 50 + + server: + <<: *hardening + restart: unless-stopped + image: ${CC_IMAGE:-craft-cloud:local} + build: + context: ../.. + dockerfile: packaging/docker/Dockerfile + args: + CRAFT_CLOUD_VERSION: ${CC_VERSION:-0.0.0} + CRAFT_CLOUD_REVISION: ${CC_REVISION:-unknown} + user: "65532:65532" + command: ["serve", "--config", "/etc/craft-cloud/config.toml"] + volumes: + # The SQLite database and the blobs. A new named volume inherits the owner (65532) and mode (0700) of the image's + # directory. A bind mount must be given both first: chown 65532:65532 DIR && chmod 0700 DIR. + - data:/var/lib/craft-cloud + - type: volume + source: secrets + target: /etc/craft-cloud + read_only: true + volume: {subpath: server} + tmpfs: + - /tmp:size=16m,mode=1777,noexec,nosuid,nodev + depends_on: + secrets-init: {condition: service_completed_successfully} + # The image has no shell and no curl: the binary asks its own listener. + healthcheck: + test: ["CMD", "/usr/local/bin/craft-cloud-server", "healthcheck", "--addr", "127.0.0.1:8080"] + interval: 15s + timeout: 5s + retries: 3 + start_period: 30s + networks: [frontend] + mem_limit: 1g + pids_limit: 512 + stop_grace_period: 30s + + caddy: + <<: *hardening + restart: unless-stopped + image: caddy:2.11-alpine@sha256:e70b164da81ef698b3ad19af799ea6086ce6d9e48ed4079eb9fe26f6fbf14ee5 + ports: + - "${CC_HTTP_PORT:-80}:80" + - "${CC_HTTPS_PORT:-443}:443" + - "${CC_HTTPS_PORT:-443}:443/udp" + environment: + CC_DOMAIN: ${CC_DOMAIN:?set CC_DOMAIN in .env, or run ./install.sh} + CC_TLS_MODE: ${CC_TLS_MODE:-acme} + CC_PUBLIC_URL: ${CC_PUBLIC_URL:?set CC_PUBLIC_URL in .env, or run ./install.sh} + CC_ACME_EMAIL: ${CC_ACME_EMAIL:-} + volumes: + - ./caddy:/etc/caddy:ro + - caddy_data:/data + - caddy_config:/config + # Only read in the `custom` TLS mode. + - ${CC_TLS_DIR:-./tls}:/certs:ro + tmpfs: + - /tmp + # Runs as root inside the container (the official image does), with no capability except binding ports 80 and 443. + cap_add: [NET_BIND_SERVICE] + depends_on: + server: {condition: service_healthy} + healthcheck: + test: ["CMD", "wget", "--quiet", "--spider", "http://127.0.0.1:2019/config/"] + interval: 30s + timeout: 5s + retries: 3 + start_period: 15s + networks: + edge: {} + # The fixed address the server lists in trusted_proxies. + frontend: + ipv4_address: ${CC_CADDY_IP:-172.29.215.2} + mem_limit: 256m + pids_limit: 200 + +networks: + # Published ports and outbound access (ACME); only Caddy is attached. + edge: + ipam: + config: + - subnet: ${CC_EDGE_SUBNET:-172.29.216.0/24} + # Caddy to the server. `internal`: no route to the outside world. + frontend: + internal: true + ipam: + config: + - subnet: ${CC_FRONTEND_SUBNET:-172.29.215.0/24} + # Server and database in the Postgres profile. `internal`, and Caddy is not attached. + backend: + internal: true + +volumes: + # The SQLite database and, with disk storage, the blobs: the data to back up. + data: {} + # config.toml and the secret files written by `secrets-init`, one directory per consuming service. + secrets: {} + caddy_data: {} + caddy_config: {} diff --git a/packaging/docker/config.toml.in b/packaging/docker/config.toml.in new file mode 100644 index 00000000..d5b684ea --- /dev/null +++ b/packaging/docker/config.toml.in @@ -0,0 +1,33 @@ +# Template of the server's config.toml in the Docker deployment. render-config.sh fills the placeholders (a name +# between two at signs) and keeps the lines whose marker prefix is active: the database kind, the storage kind, and +# for S3 the optional endpoint and plain-HTTP lines. Every other marker line is dropped. The values are checked +# before they are written. +# The rendered file is written by the secrets-init service into the secrets volume (mode 0400, owner 65532); it can +# hold the database password and S3 keys, so nobody but the server can read it. + +# The server speaks plain HTTP inside the stack. Caddy terminates TLS and has the fixed address in trusted_proxies, +# whose X-Forwarded-For the server believes (it takes single addresses, no networks). +listen = "0.0.0.0:8080" +behind_proxy = true +trusted_proxies = ["@TRUSTED_PROXY@"] +public_url = "@PUBLIC_URL@" + +# Optional limits, in bytes. See docs/server.md. +# stored_bytes_per_user = 2_000_000_000_000 +# live_bytes_per_user = 1_073_741_824 + +[database] +#sqlite#url = "sqlite:/var/lib/craft-cloud/meta.db" +#postgres#url = "postgres://craft_cloud:@DB_PASSWORD@@db:5432/craft_cloud" + +[storage] +#disk#kind = "disk" +#disk#path = "/var/lib/craft-cloud/blobs" +#s3#kind = "s3" +#s3#bucket = "@S3_BUCKET@" +#s3#prefix = "@S3_PREFIX@" +#s3#region = "@S3_REGION@" +#s3#access_key_id = "@S3_ACCESS_KEY_ID@" +#s3#secret_access_key = "@S3_SECRET_ACCESS_KEY@" +#s3endpoint#endpoint = "@S3_ENDPOINT@" +#s3http#allow_http = true diff --git a/packaging/docker/db-init.sh b/packaging/docker/db-init.sh new file mode 100755 index 00000000..cc1397e1 --- /dev/null +++ b/packaging/docker/db-init.sh @@ -0,0 +1,45 @@ +#!/bin/sh +case $- in *x*) set +x ;; esac +# One-shot role setup for the Postgres profile (service `db-init`). It runs as the postgres user of the Postgres +# image, reads the passwords from secret files and never prints them. Safe to run again: every run applies the +# password and the role's attributes, which is also how the password is rotated. +# +# The server migrates its database when it opens it, so its role owns the database and the schema `public` and may +# change them. That is less separation than an owner role plus a runtime role would give. The role is not a +# superuser and has no other privileges, and nobody else may connect to its database or to the other databases. +set -eu + +PGUSER=postgres +PGPASSWORD="$(cat /run/secrets/db_superuser_password)" +export PGUSER PGPASSWORD + +# POSTGRES_PASSWORD_FILE only applies when the data directory is first created, so a changed superuser password in +# .env cannot log in here. +if ! psql --no-psqlrc --quiet --command 'SELECT 1' >/dev/null 2>&1; then + cat >&2 <<'MSG' +db-init: cannot log in as the Postgres superuser "postgres" (or the database is unreachable). +If CC_SECRET_DB_SUPERUSER_PASSWORD in .env was changed after the first start, the database still has the old +password: the image applies it only when the data directory is created. Put the old value back in .env. +MSG + exit 1 +fi + +# psql reads the password itself (backticks), so it is not on a command line. +psql --no-psqlrc --set ON_ERROR_STOP=1 --quiet <<'SQL' +\set db_password `cat /run/secrets/db_password` + +SELECT 'CREATE ROLE craft_cloud LOGIN' + WHERE NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'craft_cloud')\gexec + +ALTER ROLE craft_cloud LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS PASSWORD :'db_password'; + +ALTER DATABASE craft_cloud OWNER TO craft_cloud; +ALTER SCHEMA public OWNER TO craft_cloud; +REVOKE ALL ON DATABASE craft_cloud FROM PUBLIC; +REVOKE CREATE ON SCHEMA public FROM PUBLIC; +-- The role must not be able to connect to the maintenance databases either. +REVOKE CONNECT ON DATABASE postgres FROM PUBLIC; +REVOKE CONNECT ON DATABASE template1 FROM PUBLIC; +SQL + +echo "db-init: the database role craft_cloud is ready" diff --git a/packaging/docker/install.sh b/packaging/docker/install.sh new file mode 100755 index 00000000..98ad74e2 --- /dev/null +++ b/packaging/docker/install.sh @@ -0,0 +1,231 @@ +#!/bin/sh +# Sets up the Docker deployment of Craft Cloud in this directory: checks the requirements, writes `.env` (mode 0600) +# with random database passwords, builds the image, starts the stack and, if asked, creates the first admin. +# +# ./install.sh [--domain cloud.example.org] [--tls acme|internal|custom] [--email you@example.org] +# [--db sqlite|postgres] [--http-port 80] [--https-port 443] [--admin name | --no-admin] [--no-start] +# +# Missing values are asked for when a terminal is attached; without one, --domain is required. The admin's password +# is read from standard input without echo (or from a pipe: printf '%s\n' "$PASSWORD" | ./install.sh ... --admin you) +# and goes to the server over a pipe: never into an argument, the environment or a log. +# +# It never overwrites an existing `.env`. It runs from a clone of the repository or an unpacked release archive; it +# downloads nothing itself (Docker pulls the pinned base images). +set -eu +umask 077 + +cd "$(dirname "$0")" + +die() { + echo "install.sh: $*" >&2 + exit 1 +} + +domain= +tls_mode= +acme_email= +db_kind= +http_port= +https_port= +admin= +no_admin=0 +no_start=0 +interactive=0 +[ -t 0 ] && interactive=1 + +while [ $# -gt 0 ]; do + case $1 in + --domain | --tls | --email | --db | --http-port | --https-port | --admin) + [ $# -ge 2 ] || die "$1 needs a value" + case $1 in + --domain) domain=$2 ;; + --tls) tls_mode=$2 ;; + --email) acme_email=$2 ;; + --db) db_kind=$2 ;; + --http-port) http_port=$2 ;; + --https-port) https_port=$2 ;; + --admin) admin=$2 ;; + esac + shift 2 + ;; + --no-admin) + no_admin=1 + shift + ;; + --no-start) + no_start=1 + shift + ;; + -h | --help) + sed -n '2,13p' "$0" | sed 's/^# \{0,1\}//' + exit 0 + ;; + *) die "unknown option $1 (see --help)" ;; + esac +done + +# --- requirements --------------------------------------------------------------------------------------------------- +command -v docker >/dev/null 2>&1 || die "docker is not installed" +compose_version=$(docker compose version --short 2>/dev/null) || die "docker compose (version 2) is not available" +# Volume subpaths, which the secret distribution relies on, need Compose 2.32. +major=${compose_version%%.*} +rest=${compose_version#*.} +minor=${rest%%.*} +case "$major$minor" in + *[!0-9]*) die "can't read the Docker Compose version '$compose_version'" ;; +esac +if [ "$major" -lt 2 ] || { [ "$major" -eq 2 ] && [ "$minor" -lt 32 ]; }; then + die "Docker Compose 2.32 or newer is needed (found $compose_version)" +fi +[ ! -e .env ] || die ".env exists already; edit it, or move it away to set up again" + +free_kib=$(df -Pk . | awk 'NR == 2 { print $4 }') +case $free_kib in + "" | *[!0-9]*) ;; + *) [ "$free_kib" -ge 4194304 ] || die "less than 4 GiB of free disk space here; the image build needs room" ;; +esac + +# --- settings ------------------------------------------------------------------------------------------------------- +ask() { + # ask + if [ "$interactive" -eq 1 ]; then + printf '%s [%s]: ' "$2" "$3" + IFS= read -r answer || answer= + eval "$1=\${answer:-\$3}" + else + eval "$1=\$3" + fi +} + +if [ -z "$domain" ]; then + [ "$interactive" -eq 1 ] || die "--domain is required without a terminal" + printf 'Domain the server is reached at (for example cloud.example.org): ' + IFS= read -r domain || domain= +fi +[ -n "$tls_mode" ] || ask tls_mode "TLS (acme, internal, custom)" acme +[ -n "$db_kind" ] || ask db_kind "Database (sqlite, postgres)" sqlite +[ -n "$http_port" ] || ask http_port "HTTP port" 80 +[ -n "$https_port" ] || ask https_port "HTTPS port" 443 +if [ "$tls_mode" = acme ] && [ -z "$acme_email" ] && [ "$interactive" -eq 1 ]; then + printf 'Email for Let'\''s Encrypt notices (optional): ' + IFS= read -r acme_email || acme_email= +fi + +printf '%s' "$domain" | grep -Eq '^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$' || die "the domain has characters that are not allowed" +case $tls_mode in acme | internal | custom) ;; *) die "--tls must be acme, internal or custom" ;; esac +case $db_kind in sqlite | postgres) ;; *) die "--db must be sqlite or postgres" ;; esac +for port in "$http_port" "$https_port"; do + case $port in "" | *[!0-9]* | 0*) die "ports are numbers from 1 to 65535" ;; esac + [ "$port" -le 65535 ] || die "ports are numbers from 1 to 65535" +done +if [ -n "$acme_email" ]; then + printf '%s' "$acme_email" | grep -Eq '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+$' || die "the email address has characters that are not allowed" +fi +if [ -n "$admin" ]; then + printf '%s' "$admin" | grep -Eq '^[A-Za-z0-9._-]{1,64}$' || die "usernames are 1-64 letters, digits, '.', '_' or '-'" +fi + +if command -v ss >/dev/null 2>&1; then + for port in "$http_port" "$https_port"; do + if ss -ltn 2>/dev/null | awk '{ print $4 }' | grep -Eq "[:.]$port\$"; then + die "port $port is already in use; pick another with --http-port / --https-port" + fi + done +fi + +public_url="https://$domain" +[ "$https_port" = 443 ] || public_url="$public_url:$https_port" + +version=$(sh ./workspace-version.sh) +revision=$(git rev-parse HEAD 2>/dev/null || true) +[ -n "$revision" ] || revision=unknown + +# --- .env --------------------------------------------------------------------------------------------------------- +# A random password of 40 URL-safe characters (the database password becomes part of a database URL). +random_password() { + value=$(LC_ALL=C tr -dc 'A-Za-z0-9' /dev/null | head -c 40 || true) + [ "${#value}" -eq 40 ] || die "can't read random bytes from /dev/urandom" + printf '%s' "$value" +} + +compose_file=compose.yaml +[ "$db_kind" != postgres ] || compose_file=compose.yaml:compose.postgres.yaml + +{ + echo "# Written by install.sh. Holds the database passwords: keep it private (mode 0600) and out of version control." + echo "COMPOSE_PATH_SEPARATOR=:" + echo "COMPOSE_FILE=$compose_file" + echo "CC_DOMAIN=$domain" + echo "CC_PUBLIC_URL=$public_url" + echo "CC_TLS_MODE=$tls_mode" + echo "CC_ACME_EMAIL=$acme_email" + echo "CC_HTTP_PORT=$http_port" + echo "CC_HTTPS_PORT=$https_port" + echo "CC_IMAGE=craft-cloud:$version" + echo "CC_VERSION=$version" + echo "CC_REVISION=$revision" + if [ "$db_kind" = postgres ]; then + echo "CC_SECRET_DB_SUPERUSER_PASSWORD=$(random_password)" + echo "CC_SECRET_DB_PASSWORD=$(random_password)" + fi +} >.env.new +chmod 600 .env.new +mv .env.new .env +echo "Wrote .env (mode 0600)." + +if [ "$tls_mode" = custom ]; then + mkdir -p tls + chmod 700 tls + echo "Put fullchain.pem and private.key in $(pwd)/tls before the stack starts, then run: docker compose up -d --wait" + no_start=1 +fi + +[ "$no_start" -eq 0 ] || { + echo "Not started. Next: docker compose build && docker compose up -d --wait" + exit 0 +} + +# --- build and start ---------------------------------------------------------------------------------------------- +echo "Building the image craft-cloud:$version (this takes a while the first time)..." +docker compose build server +echo "Starting the stack..." +docker compose up -d --wait + +# --- first admin ---------------------------------------------------------------------------------------------------- +if [ "$no_admin" -eq 0 ] && [ -z "$admin" ] && [ "$interactive" -eq 1 ]; then + printf 'Name of the first admin (empty to skip): ' + IFS= read -r admin || admin= + printf '%s' "$admin" | grep -Eq '^([A-Za-z0-9._-]{1,64})?$' || die "usernames are 1-64 letters, digits, '.', '_' or '-'" +fi + +if [ "$no_admin" -eq 0 ] && [ -n "$admin" ]; then + password= + if [ "$interactive" -eq 1 ]; then + trap 'stty echo 2>/dev/null || true' EXIT INT TERM + stty -echo + printf 'Password for %s: ' "$admin" + IFS= read -r password || password= + printf '\nRepeat the password: ' + IFS= read -r again || again= + stty echo + printf '\n' + [ "$password" = "$again" ] || die "the passwords differ; create the admin later (see docs/server.md)" + unset again + else + IFS= read -r password || password= + fi + [ -n "$password" ] || die "no password given; create the admin later (see docs/server.md)" + # The password travels through a pipe into the container's standard input. A refusal (a password the server's rules + # do not accept) is shown by the server without the password. + if printf '%s\n' "$password" | docker compose run --rm --no-deps -T server user --config /etc/craft-cloud/config.toml add --admin "$admin"; then + unset password + else + unset password + die "the admin was not created; see the message above, then run it by hand (see docs/server.md)" + fi +fi + +echo +echo "Craft Cloud runs at $public_url" +[ "$tls_mode" != internal ] || echo "TLS mode 'internal': the certificate is from Caddy's own CA; clients must be told to trust it (curl -k for a test)." +echo "Next: docker compose ps, and docker compose logs -f server" diff --git a/packaging/docker/render-config.sh b/packaging/docker/render-config.sh new file mode 100755 index 00000000..a5609711 --- /dev/null +++ b/packaging/docker/render-config.sh @@ -0,0 +1,137 @@ +#!/bin/sh +# Renders the server's config.toml from config.toml.in and writes it to standard output. +# +# render-config.sh