Initial commit

Assisted-by: GLM 5.3
2026-09-29 10:03:32 +02:00
commit f8ed33df83
206 changed files with 44165 additions and 0 deletions
@@ -0,0 +1,748 @@
+# Deployment
+
+How Volumen runs in production.
+
+## Topology
+
+```mermaid
+flowchart TD
+  net["Internet"] -->|HTTPS| nginx
+  nginx["nginx :443, TLS termination and reverse proxy"] -->|"proxy_pass http://[::1]:9091"| app
+  app["volumen, one static binary, loopback only"] --> data
+  app --> etc
+  data["/var/lib/volumen holding posts/ (with media/ and .revisions/ inside) and users.toml, templates.toml, tokens.toml, webhooks.toml, secret.key"]
+  etc["/etc/volumen/config.toml"]
+```
+
+nginx terminates TLS on the public hostname and proxies `/api/volumen`,
+`/admin` and `/media` to the backend on loopback; everything else on that
+hostname is the public site, served separately. The engine owns one content
+directory (posts, media and revisions inside it) and four files beside it:
+`users.toml`, `templates.toml`, `tokens.toml` and `webhooks.toml`. There is
+one process per content directory.
+
+## Requirements
+
+- **A supported platform**: the release builds cover Linux on `amd64`,
+  `arm64`, `loong64`, and `riscv64`, and FreeBSD on `amd64` and
+  `arm64`. The binary is static
+  (`CGO_ENABLED=0`), so no runtime libraries are needed.
+- **Go 1.27.1** or newer only when building from source: the module declares
+  it.
+- **nginx** and a TLS certificate (e.g. via certbot) for the public hostname.
+- A dedicated system user, `volumen` by default, for the service. The
+  documentation creates it by hand; nothing in the binary creates users.
+- **systemd** for the managed service (optional; an rc.d script, a supervisor,
+  or a plain foreground run all work).
+- Nothing else: no interpreter, no virtual environment, no package manager.
+  The deployment itself is one command: start `volumen serve` and open
+  `/admin`, where the first-run wizard creates the administrator account. The
+  commented configuration template, `config.toml.example`, is committed at
+  the repository root, and the session secret is generated by the server.
+
+## Build
+
+```sh
+just build      # writes bin/volumen for the host platform
+```
+
+Releases are built by the tag pipeline for Linux (`amd64`, `arm64`, `loong64`,
+`riscv64`) and FreeBSD (`amd64`, `arm64`), with `CGO_ENABLED=0` and
+no build tags, so every artefact is a static binary. `-trimpath` keeps the
+checkout's own path out of the binary and `-buildvcs=true` records the
+revision it came from, so the same tree builds the same bytes from any
+directory and `volumen version` still names the tag or the commit. The version
+is recorded by the toolchain at build time; nothing injects it.
+
+## Run
+
+Installing the binary is a copy, and the installation is the wizard: start
+`volumen serve`, open `/admin`, and the first-run screen creates the
+administrator account, the interface language and the colour scheme. A
+system deployment writes the config by copying `config.toml.example`; a
+per-user one needs no config at all.
+
+Any account can then add a second factor from Settings, Security: scan the
+offered QR with an authenticator application and confirm one code. The
+recovery codes shown at that moment open the account when the application
+is lost; they work once each and are not shown again, so they belong in a
+password manager the moment they appear.
+
+### From a Gitea release
+
+Every release on
+[sourcedock.dev](https://sourcedock.dev/petrbalvin/volumen/releases) ships
+platform binaries and a `checksums.txt` with their SHA-256 digests. Asset
+names follow `volumen-<version>-<os>-<arch>`:
+
+```sh
+VERSION=1.0.0
+BASE="https://sourcedock.dev/petrbalvin/volumen/releases/download/v${VERSION}"
+curl -fLO "${BASE}/volumen-${VERSION}-linux-amd64"
+curl -fLO "${BASE}/checksums.txt"
+
+# Verify the download against the published digest.
+sha256sum --ignore-missing -c checksums.txt
+
+sudo install -m 0755 "volumen-${VERSION}-linux-amd64" /usr/local/bin/volumen
+volumen version
+```
+
+Replace `linux-amd64` with `linux-arm64`, `linux-loong64`, `linux-riscv64`,
+`freebsd-amd64`, or `freebsd-arm64`
+as needed. The release binary carries its version, so `volumen version`
+confirms what you installed.
+
+### From source
+
+```sh
+git clone https://sourcedock.dev/petrbalvin/volumen.git
+cd volumen
+just install
+sudo install -m 0755 bin/volumen /usr/local/bin/volumen
+```
+
+The binary reports the version the toolchain recorded at build time:
+`volumen version` names the commit of the checkout it was built from, and a
+release build names its tag. There is no version flag to pass and nothing to
+inject.
+
+### Bootstrap the deployment
+
+There is no bootstrap command. A deployment is a directory for its state, a
+configuration file copied from the template when the defaults do not fit, a
+supervisor to keep the server running, and one visit to `/admin`, where the
+first-run wizard creates the first account. The wizard stays open until that
+account exists: on a machine reachable from the network, start the service and
+claim the installation straight away.
+
+### System install (root, systemd)
+
+```sh
+# 1. Service account and its group.
+sudo useradd --system --user-group --home-dir /var/lib/volumen \
+  --shell /usr/sbin/nologin volumen
+
+# 2. The config: copy the commented template from the repository root.
+sudo mkdir -p /etc/volumen /var/lib/volumen/posts/media
+sudo cp config.toml.example /etc/volumen/config.toml
+
+# 3. Edit the copy for production behind a reverse proxy:
+#      host = "::1", env = "production", trust_proxy = true,
+#      cookie_secure = true,
+#      trusted_proxies = ["::1", "127.0.0.1"]
+#    Leave [admin].session_key empty: the server generates its secret into
+#    /var/lib/volumen/secret.key on first start and keeps it there.
+
+# 4. Own the data directory so the service can write posts, media, accounts
+#    and its secret.
+sudo chown -R volumen:volumen /var/lib/volumen
+
+# 5. Install the unit (the Service unit section below), then:
+sudo systemctl daemon-reload
+sudo systemctl enable --now volumen.service
+
+# 6. Open http://localhost:9091/admin/ and complete the wizard.
+```
+
+The two proxy settings carry weight: `trust_proxy = true` takes the client
+address from the proxy's `X-Forwarded-For`, and `cookie_secure = true` keeps
+the session cookie on HTTPS. The config is deployment state and stays mode
+`0600`.
+
+### Per-user install (no root)
+
+```sh
+volumen serve
+```
+
+With no config file the server runs on the per-user paths:
+`~/.local/share/volumen/posts` and `~/.local/share/volumen/users.toml`
+(honouring `XDG_DATA_HOME`), and it reads `~/.config/volumen/config.toml`
+when that file exists. No systemd unit is installed in this mode; run the
+server in the foreground or through a supervisor of your choice.
+
+### Configuration locations
+
+| Path | Purpose |
+|------|---------|
+| `/etc/volumen/config.toml` | configuration: a copy of the commented `config.toml.example`, edited to fit |
+| `/var/lib/volumen/posts` | Markdown posts |
+| `/var/lib/volumen/posts/media` | uploaded images (WebP / AVIF / SVG) |
+| `/var/lib/volumen/posts/.revisions` | archived post versions and delete tombstones |
+| `/var/lib/volumen/users.toml` | admin users (created by the first-run wizard or the Settings page) |
+| `/var/lib/volumen/secret.key` | the session secret the server generated on first start |
+| `/var/lib/volumen/templates.toml` | post templates (created from the admin Settings page) |
+| `/var/lib/volumen/tokens.toml` | API access tokens (created from the admin Settings page) |
+| `/var/lib/volumen/webhooks.toml` | admin-managed webhook endpoints (created from the admin Settings page) |
+| `/var/lib/volumen/audit.log` | audit trail (only when `audit_log` is configured) |
+| `/etc/systemd/system/volumen.service` | systemd unit (written by the operator, see the Service unit section) |
+| `~/.config/volumen/config.toml` | per-user config, read when it exists |
+| `~/.local/share/volumen/` | per-user data dir (the default when no config file exists) |
+
+The users, templates, tokens and secret files carry password hashes, token
+digests and the signing key, so never make them world-readable: every write
+the server performs re-applies mode `600`, media and post writes are atomic.
+Every configuration key is documented in
+[CONFIGURATION.md](CONFIGURATION.md).
+
+### Scheduled publishing
+
+Posts may carry a `publish_at` date in their frontmatter; they stay hidden
+until that date arrives. Two mechanisms can flip them, and both do the same
+thing: drop `publish_at` and set `date` when the post had none.
+
+**From cron** (or a systemd timer):
+
+```text
+*/5 * * * * /usr/local/bin/volumen publish-due --config /etc/volumen/config.toml
+```
+
+Use the absolute path to the binary, since cron's `PATH` is minimal.
+`--dry-run` lists due posts without touching files; `--json` emits
+machine-readable output. A real run delivers the `post.published` event to the
+configured `[[webhooks]]` for every post it publishes and waits for those
+deliveries to finish, so a front end that rebuilds from a webhook hears about
+a publish that came from cron. A post whose file could not be saved is
+reported on stderr and the command exits `1`, so a timer unit or a monitoring
+check can see the failure rather than assume success.
+
+**From the server itself**, via the `[scheduler]` configuration section:
+
+```toml
+[scheduler]
+enabled = true
+interval = 300     # seconds
+```
+
+The in-process loop starts with `volumen serve` and needs no external timer.
+It sweeps once at start-up, so a post whose date passed while the service was
+down is published as soon as it comes back, and then once every `interval`
+seconds. An interval below one second never reaches the loop: the
+configuration validation refuses it at start-up. The loop delivers the same
+`post.published` webhook as the
+admin does, and a save failure is logged and skipped, so one bad file cannot
+stop the sweep or the loop.
+
+The systemd timer equivalent for the CLI path:
+
+```ini
+# /etc/systemd/system/volumen-publish.service
+[Unit]
+Description=Publish due volumen posts
+
+[Service]
+Type=oneshot
+User=volumen
+ExecStart=/usr/local/bin/volumen publish-due --config /etc/volumen/config.toml
+```
+
+```ini
+# /etc/systemd/system/volumen-publish.timer
+[Unit]
+Description=Publish due volumen posts every five minutes
+
+[Timer]
+OnCalendar=*:0/5
+
+[Install]
+WantedBy=timers.target
+```
+
+```sh
+sudo systemctl daemon-reload
+sudo systemctl enable --now volumen-publish.timer
+```
+
+Adjust the `ExecStart` path to match the one in `volumen.service`.
+
+## Service unit
+
+`/etc/systemd/system/volumen.service`, written by the operator (paths and
+binary location fitted to the deployment):
+
+```ini
+[Unit]
+Description=Volumen, a lightweight publishing platform for scientists
+After=network.target
+
+[Service]
+Type=simple
+User=volumen
+Group=volumen
+WorkingDirectory="/etc/volumen"
+ExecStart="/usr/local/bin/volumen" serve --config "/etc/volumen/config.toml" --content "/var/lib/volumen/posts"
+Restart=on-failure
+RestartSec=2
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths="/var/lib/volumen"
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Quote every path so a layout with spaces in it stays one argument, and double
+any `%`, because unit files expand `%X` specifiers.
+
+- `User` / `Group` name the service account (default `volumen`), and
+  `WorkingDirectory` is the directory holding the config file.
+- `ExecStart` names the installed binary.
+- `ReadWritePaths` is the **parent of the data directory**, so a layout with
+  posts at `/srv/volumen/posts` yields `ReadWritePaths=/srv/volumen`: the
+  service also writes the users file, its templates, tokens, webhooks and
+  `secret.key` there. With `ProtectSystem=strict` the rest of the filesystem
+  is read-only to the service.
+- `NoNewPrivileges`, `ProtectHome` (`/home`, `/root`, `/run/user`
+  inaccessible), `PrivateTmp`, and a two-second restart delay on failure.
+
+The server bounds every connection: a 10 second read-header timeout, a 60
+second read timeout, a 120 second write timeout, and a 120 second idle
+timeout, so a client that opens a socket and dribbles a request cannot hold it
+indefinitely. On `SIGINT` or `SIGTERM` (what `systemctl stop` sends) it stops
+accepting new connections and drains the requests already in flight, giving
+them at most 15 seconds.
+
+### FreeBSD (rc.d)
+
+The `freebsd/amd64` and `freebsd/arm64` release binaries
+run natively; nothing is compiled at install time.
+
+```sh
+# Install the binary from the release, as above, to /usr/local/bin/volumen.
+pw useradd volumen -d /var/db/volumen -s /usr/sbin/nologin -c "Volumen publishing platform"
+mkdir -p /usr/local/etc/volumen /var/db/volumen/posts/media
+cp config.toml.example /usr/local/etc/volumen/config.toml
+chown -R volumen /var/db/volumen
+```
+
+Edit the copied config for a production deployment behind a proxy: set the
+three paths, `host = "::1"`, `env = "production"`, `trust_proxy = true`,
+`cookie_secure = true` and `trusted_proxies = ["::1", "127.0.0.1"]`. Leave
+`[admin].session_key` empty; the server writes `secret.key` into
+`/var/db/volumen`, which is owned by the `volumen` user.
+
+Conventional FreeBSD paths: config in `/usr/local/etc/volumen/`, data in
+`/var/db/volumen/`. Drop an `rc.d` script in
+`/usr/local/etc/rc.d/volumen`:
+
+```sh
+#!/bin/sh
+#
+# PROVIDE: volumen
+# REQUIRE: NETWORKING
+# KEYWORD: shutdown
+
+. /etc/rc.subr
+
+name="volumen"
+rcvar="volumen_enable"
+load_rc_config $name
+
+: ${volumen_enable:="NO"}
+: ${volumen_user:="volumen"}
+: ${volumen_config:="/usr/local/etc/volumen/config.toml"}
+: ${volumen_content:="/var/db/volumen/posts"}
+
+pidfile="/var/run/${name}.pid"
+command="/usr/sbin/daemon"
+command_args="-f -r -P ${pidfile} -u ${volumen_user} \
+  /usr/local/bin/volumen serve --config ${volumen_config} --content ${volumen_content}"
+
+run_rc_command "$1"
+```
+
+Enable and start:
+
+```sh
+chmod +x /usr/local/etc/rc.d/volumen
+sysrc volumen_enable=YES
+service volumen start
+```
+
+## Production configuration
+
+Volumen only owns `/api/volumen`, `/admin`, and `/media`. Serve your public
+site from the same hostname and proxy those prefixes to the backend, so the
+admin runs same-origin (session cookies and CSRF work without extra
+configuration). A production deployment binds the service to `::1`, so proxy
+to `[::1]:9091`:
+
+```nginx
+server {
+  listen 443 ssl http2;
+  server_name lab.example.com;
+
+  ssl_certificate     /etc/letsencrypt/live/lab.example.com/fullchain.pem;
+  ssl_certificate_key /etc/letsencrypt/live/lab.example.com/privkey.pem;
+
+  # Public site: any front end, static files or a built one.
+  root /var/www/site;
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+
+  # volumen API, admin and media.
+  location ~ ^/(api/volumen|admin|media)(/|$) {
+    proxy_pass http://[::1]:9091;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+}
+
+server {
+  listen 80;
+  server_name lab.example.com;
+  return 301 https://$host$request_uri;
+}
+```
+
+Caddy is the recommended front, and the same shape costs a handful of
+lines: certificates and the HTTP redirect are its own work.
+
+```caddyfile
+lab.example.com {
+  root * /var/www/site
+  @backend path /api/volumen/* /admin /admin/* /media /media/*
+  handle @backend {
+    reverse_proxy [::1]:9091
+  }
+  handle {
+    try_files {path} {path}/ /index.html
+  }
+}
+```
+
+Caddy appends the connecting address to `X-Forwarded-For` the way
+`$proxy_add_x_forwarded_for` does, so the guarantee described below holds
+with either front.
+
+With `[server].trust_proxy = true` (a production deployment turns it on), the
+client IP used by the API rate limiter and the login limiter is the **last**
+entry of `X-Forwarded-For`, and only when the connection itself comes from an
+address listed in `[server].trusted_proxies`. Session cookies then always
+carry `Secure`.
+
+The last entry is the one the peer that wrote it saw as its client, so the
+directives above are safe as written: `$proxy_add_x_forwarded_for` appends
+`$remote_addr` after anything the client sent, which means a client cannot
+displace its own address by sending a header of its own. The guarantee the
+proxy must provide is the other half: only nginx may reach the backend. Bind
+it to `::1`, and never expose port 9091,
+because anything that can open a connection to the backend directly can set
+`X-Forwarded-For` itself and choose the address it is rate-limited under (see
+the security notes below).
+
+`[server].trusted_proxies` turns that guarantee into a check rather than a
+promise: with `trusted_proxies = ["::1", "127.0.0.1"]`, the forwarded address
+is believed only when the connection itself comes from the loopback proxy, and
+a request that arrives from anywhere else is measured by its real address.
+A loopback proxy behind `nginx` uses exactly that list. An empty list never reads
+the header at all: behind a proxy every client is then measured under the
+proxy's own connection address and shares one rate-limit budget, so list the
+proxy to measure each client by its forwarded address.
+
+### Hardening the login
+
+The engine rate-limits `/admin/login` itself (10 attempts per IP per 60 s;
+see [the session and rate-limit rules](ARCHITECTURE.md#state-and-lifetime)),
+but nginx is the durable line of defence. Add brute-force throttling (and,
+optionally, an IP allowlist) at the proxy.
+
+**1. A rate-limit zone** in the `http { }` context (e.g.
+`/etc/nginx/conf.d/volumen.conf`):
+
+```nginx
+limit_req_zone $binary_remote_addr zone=volumen_login:10m rate=5r/m;
+```
+
+**2. A reusable proxy snippet** at `/etc/nginx/snippets/volumen-proxy.conf`:
+
+```nginx
+proxy_pass http://[::1]:9091;
+proxy_set_header Host $host;
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+```
+
+**3. Split the single proxy location** in the `server { }` block into three, namely
+public API/media, the throttled login, and the rest of the admin:
+
+```nginx
+  # Public API and uploaded media, open to everyone.
+  location ~ ^/(api/volumen|media)(/|$) {
+    include snippets/volumen-proxy.conf;
+  }
+
+  # Login: throttle brute-force attempts on top of the app-level limit.
+  location = /admin/login {
+    # Optional IP allowlist (uncomment to restrict):
+    # allow 203.0.113.0/24;
+    # deny all;
+    limit_req zone=volumen_login burst=10 nodelay;
+    include snippets/volumen-proxy.conf;
+  }
+
+  # The rest of the admin.
+  location ^~ /admin {
+    include snippets/volumen-proxy.conf;
+  }
+```
+
+nginx matches `= /admin/login` (exact) first, then `^~ /admin` (which stops
+regex matching), then the `~` regex for API/media. Apply with
+`sudo nginx -t && sudo systemctl reload nginx`.
+
+### Security notes
+
+- Bind to `::1` (or `127.0.0.1`); only nginx is public. TLS is terminated by
+  nginx. The production config sets `host = "::1"`.
+- Session cookies are `HttpOnly` and `SameSite=Strict`, and gain the `Secure`
+  attribute when `[server].cookie_secure = true` or when `trust_proxy = true`.
+  The session secret signs them and survives restarts: by default the server
+  generates it into `secret.key` beside the users file, and `[admin].session_key`
+  (at least 64 bytes, mandatory in production) overrides that file.
+- `[server].trusted_proxies` names the addresses whose `X-Forwarded-For` is
+  believed. A loopback-nginx deployment lists `["::1", "127.0.0.1"]`, or narrows
+  it to the proxy's address, so a client that reaches the backend directly cannot
+  choose the address it is rate-limited under. An empty list ignores the
+  forwarded header, which behind a proxy folds every client into one
+  rate-limit bucket.
+- Keep `config.toml`, `users.toml`, `tokens.toml` and `secret.key` readable only
+  by the `volumen` user (mode `600`). Every write the server makes enforces this.
+- To change a forgotten administrator password, reset it from the admin Settings
+  page as another admin, or rotate the account in `users.toml`. Never put a
+  password on the command line.
+- The controls themselves, and their limits, are described in
+  [the architecture](ARCHITECTURE.md#state-and-lifetime): how a body is
+  sanitised before it is served, how a password is stored, and what the session
+  cookie does and does not guarantee.
+
+## Upgrade
+
+### From the admin panel
+
+The Version panel in Settings shows the running release and, when the release
+check has found a newer one, an "Update now" action. The update endpoint is
+admin-only and CSRF-protected. On confirmation the server:
+
+1. queries the latest release from the Gitea releases API
+   (`/api/v1/repos/petrbalvin/volumen/releases/latest`),
+2. downloads the matching asset from
+   `https://sourcedock.dev/petrbalvin/volumen/releases/download/v<version>/volumen-<version>-<os>-<arch>`,
+3. verifies the SHA-256 digest against the release's `checksums.txt`,
+4. stages the new binary in the executable's directory and renames it over the
+   running one,
+5. re-executes itself with the original command-line arguments, preserving the
+   process ID so systemd never observes a restart.
+
+The response page polls `/healthz` until the server is back (up to three
+minutes). Nothing is installed without an admin clicking through.
+
+The self-update writes the running binary in place, so the service user needs
+write access to that directory. With the standard layout
+(`/usr/local/bin/volumen` owned by root, service running as `volumen`) the
+rename fails; either grant the service user write access to the install
+directory or use the manual path below. A checksum or download error in the
+panel means the release asset could not be fetched for the running platform;
+the state on disk is untouched.
+
+### From the shell
+
+```sh
+sudo systemctl stop volumen
+sudo install -m 0755 volumen-1.0.0-linux-amd64 /usr/local/bin/volumen
+volumen version
+sudo systemctl start volumen
+volumen status   # confirm: config, posts, users
+```
+
+The persistent state (`config.toml`, `users.toml`, posts, revisions) is
+untouched by either path.
+
+### Monitoring for updates
+
+```sh
+volumen check-update          # human-readable
+volumen check-update --json   # machine-readable
+```
+
+Exit codes: `0` when the running version is the latest release, `1` when a
+newer release exists, and `1` as well when the release API cannot be reached
+(the cause is on stderr, so a monitoring check distinguishes the two by its
+output rather than by the code); `2` is a usage error and nothing else.
+
+## Rollback
+
+There is no rehearsed rollback procedure for a running installation, and this
+document does not pretend otherwise.
+
+- **A bad upgrade** is undone by putting the previous binary back and
+  restarting: the release assets are versioned, so an older one is still on the
+  releases page, and the data is untouched by an upgrade. A restore from a
+  backup archive is the fallback when data changed as well.
+- **A bad content change** does not need a rollback: every save archives the
+  previous version under `posts/.revisions/<slug>/`, and a delete is a move into
+  that archive, so the admin's History view restores either one.
+- **A bad configuration change** is undone by editing the file and restarting;
+  a configuration that fails validation stops the process before it binds its
+  port, so a broken edit cannot half-start the service.
+
+### Backups
+
+All state is files, so any filesystem backup works. Volumen also ships its
+own archive commands:
+
+```sh
+volumen export --out /backup/volumen-$(date +%F).tar.gz
+volumen import /backup/volumen-2026-08-02.tar.gz
+```
+
+`export` packs the content directory (posts, media, `.revisions`) under
+`posts/`, plus `users.toml`, `templates.toml` and `tokens.toml`, into a
+`tar.gz` written at mode `600`; `--out` is the flag, and the default output
+path is `volumen-backup.tar.gz` in the working directory. `config.toml` is not
+in the archive: the import has no use for it and the session key it carries is
+a credential that should not travel in a file copied around. `import` restores
+the posts, users, templates and tokens into the locations from the config.
+
+A restore is confined by construction: the archive's entries are matched
+against the fixed `posts/`, `users.toml`, `templates.toml` and `tokens.toml`
+names, a `posts/` path must be a post, a revision or a media file with an
+allowed image extension, and every write goes through an `os.Root` opened on
+the content directory, which refuses an escape through `..` or through a
+symlink. The decompressed size is bounded at 512 MiB, so a compression bomb
+cannot exhaust memory. `.toml` files are written with mode `600`, everything
+else with `644`.
+
+The same export and restore is available from the admin Settings page, where
+both directions require the **admin** role, because the archive carries the
+users file with its password hashes and the tokens file with its digests. The
+admin path calls the same two functions as the CLI, so the archive and the
+containment rules are one implementation, not two.
+
+## Monitoring
+
+After the first-run wizard, confirm the installation state:
+
+```sh
+volumen status            # config, content dir, post and user counts
+volumen status --json     # machine-readable; exit code 1 on any issue
+volumen doctor            # config validation, post rendering, weak hashes
+volumen doctor --json     # machine-readable; exit code 1 when a check fails
+volumen validate          # content check: slugs, titles, aliases, rendering
+sudo systemctl status volumen
+journalctl -u volumen -f
+```
+
+`volumen status` reads the config and reports the post count (with a draft
+count) and the number of users; with no accounts yet it names the wizard as
+the next step. `volumen doctor` validates the configuration,
+renders every post, and warns when a stored password hash uses scrypt
+parameters below the current policy floor. The exit code follows the levels:
+a missing or broken config, an unreadable content directory and an unreadable
+users file fail the command with exit code 1, while an installation still
+waiting for its first account, posts that fail to render
+and weak stored hashes are warnings that leave the exit code at 0.
+`volumen validate` reports
+duplicate slugs, invalid slugs, missing titles, aliased collisions, and posts
+that fail to render.
+
+Those commands check a deployment. The build of the binary is checked by
+`just gates`, which runs `build`, `fmt-check`, `vet`, `test` and `race` in one
+pass; the release pipeline runs the same set without the race detector (see
+[Pipeline](#pipeline)).
+
+Logs go to stderr and therefore to journald under systemd. For structured
+output, set the log format to JSON:
+
+```toml
+[server]
+log_format = "json"
+```
+
+Each line is then one JSON object from `log/slog` (time, level, message, and
+the structured attributes of the event), suitable for `journalctl -o json`,
+Loki, or similar. The default `"text"` format is human-readable. Every request
+is logged once when it finishes, with its method, path, status and duration,
+under a 16-character request id; the same id is answered in the `X-Request-Id`
+header and attached to every line the handlers write while serving that
+request, so one id finds a request and everything it did in the journal. The
+server's own protocol errors are written through the same logger rather than
+straight to stderr.
+
+Set `audit_log` in the configuration to keep a separate, append-only
+JSON-lines record of administrative actions. Logins and logouts are not
+recorded; post creation, edits, deletions and bulk actions are, together with
+media deletions, user and token management, and backup imports. Each line is
+one JSON object carrying the timestamp `ts` (RFC 3339, UTC), the acting `user`
+and the `action` as its message, plus the `resource`, the client `ip` and a
+`detail` object wherever the action knows them.
+
+## Pipeline
+
+Releases are built by `.gitea/workflows/release.yml`, which runs when a `v*`
+tag is pushed. The branch flow is the one in
+[CONTRIBUTING.md](../CONTRIBUTING.md): work lands on `development`,
+`development` is merged into `main`, and the tag is cut on `main`. The build
+happens at the tag, and the toolchain records the tag into the binary's build
+information, so the version in the binary is right because of where the build
+ran; nothing is injected, and each job derives the version from the tag itself
+rather than receiving it from another job.
+
+```mermaid
+flowchart TD
+  subgraph gates["gates job, 10 minute timeout"]
+    direction TB
+    g1["validate the tag against the semver pattern"] --> g2["go build ./..."] --> g3["gofmt -l . prints nothing"] --> g4["go vet ./..."] --> g5["go fix -diff ./..."] --> g6["go test with a coverage profile"] --> g7["the coverage floor of 80 per cent"]
+  end
+  subgraph builds["build job, 25 minute timeout, six targets in one matrix"]
+    direction TB
+    b1["linux on amd64, arm64, loong64, riscv64"] --> b2["freebsd on amd64, arm64"]
+    b2 --> b3["CGO_ENABLED=0 build with -trimpath and -buildvcs into bin/volumen-VERSION-OS-ARCH"]
+    b3 --> b4["upload the artefact"] --> b5["linux/amd64 smoke test, the binary reports the tag and no +dirty"]
+  end
+  subgraph rel["release job, 15 minute timeout"]
+    direction TB
+    r1["download the artefacts"] --> r2["write checksums.txt over them"] --> r3["take the CHANGELOG section for the tag"] --> r4["create the release over the Gitea API"] --> r5["upload the six binaries and checksums.txt"]
+  end
+  tag["a v* tag is pushed"] --> gates
+  gates --> builds
+  builds --> rel
+```
+
+The gates job runs the same set as `just gates` minus the race detector:
+build, format check, `go vet` together with `go fix -diff`, the suite, and the
+coverage floor of 80 per cent. Race is deliberately absent: the runner is
+shared with the forge, and `just gates` races the tree on the machine where
+the tag is cut. A push or a pull request to `development` runs the same steps
+without race through `.gitea/workflows/test.yml`, and
+`.gitea/workflows/race.yml` runs the suite under the race detector when it is
+dispatched by hand.
+
+The release is the only publisher: nothing is deployed out of the repository,
+and a production installation takes its binary from a release, through the
+admin self-update (see [Upgrade](#upgrade)) or a manual install followed by a
+service restart.
+
+Each matrix entry builds one static binary named
+`volumen-<version>-<os>-<arch>` for the version without its leading `v`, with
+`-trimpath` and `-buildvcs=true`, uploads it, and, on linux/amd64 only, runs it
+and requires the output of `volumen version` to contain the tag and not
+`+dirty`. The release job then
+writes `checksums.txt`, one `sha256sum` line per asset, takes the release
+notes from the `CHANGELOG.md` section for the tag, creates the release over
+the Gitea API, and uploads the six binaries with the checksums file. That
+file is part of the update contract: the admin self-update refuses a download
+whose SHA-256 does not match it.
+
+The release carries no licence files of its own, because the repository holds
+them: `LICENSE` for Volumen, and
+[NOTICE.md](../NOTICE.md) for every module the binary
+is compiled from. Gitea attaches the tag's own source archive to the release
+beside the binaries, and that archive contains both.