feat(deb): package the server, and ask the questions that fail silently
CI / fmt, clippy, test (pull_request) Successful in 1m48s
CI / advisories and licences (pull_request) Successful in 42s
CI / static musl binary (pull_request) Successful in 1m46s
CI / debian package (pull_request) Failing after 3h10m28s

DR-015, DR-016. §8 already shipped a static binary and an optional
container; this adds the third form, and it packages the SAME binary the
musl job proved static rather than building its own. Two builds of the
same commit could diverge, and the whole point of that assertion is that
the artifact an operator installs is the one that was checked.

Built with dpkg-deb from an explicit staging tree rather than cargo-deb.
debconf's `config` script and `templates` live in the control archive
next to the maintainer scripts, and controlling that archive directly
beats discovering what a wrapper will copy into it. dpkg-dev is on every
Debian builder, so this adds no build dependency.

Why debconf at all: two settings fail SILENTLY when unset. Without
JRAY_TMDB_API_KEY every upload stays `pending` and is never listed;
without JRAY_TRUSTED_PROXIES the X-Forwarded-For header is ignored, so
every client shares one rate-limit bucket and every abuse report points
at the proxy. Both leave a server that works and is quietly doing the
wrong thing — the worst thing to leave to a README nobody reads.

Three properties, each a way packaging usually goes wrong:

The generated config is NOT a dpkg conffile. It is written from the
debconf answers, so shipping it as one would make dpkg prompt on every
upgrade about changes the package itself had made.

Hand edits survive. postinst rewrites only the keys debconf manages;
comments, ordering and any other setting are left alone.

A blank key on reconfigure keeps the existing one. Otherwise pressing
Enter through a dpkg-reconfigure would unpublish every future upload.

The seeding guard is worth its comment, because the obvious version is
wrong twice over. `config` seeds unanswered questions from the env file
so a reconfigure shows what is actually in force. Seeding
unconditionally overwrites a preseed — debconf-set-selections marks what
it sets as seen — so every unattended install would quietly reconfigure
itself back to whatever was on disk. Guarding on an empty value does not
work either: server-id and bind carry template Defaults, so db_get
returns "localhost" for a question nobody answered. The test is the
`seen` flag, which is the actual question being asked.

Purge keeps the database, knowingly departing from the expectation that
purge removes everything. Manifests are the output of real CV compute on
media the operator may no longer have, and §8 says federation is
explicitly not a backup. Destroying that during an `apt purge` is not a
trade worth making for tidiness; postrm names the path instead.

The nginx example is documentation, not installed configuration. The
proxy usually runs on a different host from the server, so a file
dropped into this machine's nginx would be in the wrong place — and §8
leaves the edge to the operator deliberately.

Verified by running it, not by reading it: a full lifecycle in a
bookworm container — build, preseeded install, mode-600 env file, key
absent from debconf's database afterwards, `systemd-analyze verify` on
the unit, the installed binary answering /health and /ready, reconfigure
preserving both the key and an unmanaged setting, and purge leaving the
database. It failed on the seeding bug above the first time, which is
why that guard exists. CI runs the same checks against every build.

TRACES: DR-015, DR-016 | PR-004
This commit is contained in:
2026-09-06 09:58:47 +02:00
parent b4cf0c0fbf
commit 6c0c80f20b
12 changed files with 817 additions and 0 deletions
+78
View File
@@ -0,0 +1,78 @@
# Example nginx site for jray-server. NOT installed anywhere by the package —
# the proxy usually runs on a different host from the server, so a file dropped
# into this machine's nginx would be in the wrong place. Copy it to the proxy.
#
# /etc/nginx/sites-available/jray-server (then symlink into sites-enabled)
#
# Replace jray.example.org and the upstream address, and point ssl_certificate
# at your own certificate.
upstream jray_server {
# The address jray-server listens on. If the proxy runs on the SAME host,
# this is 127.0.0.1:8080 and JRAY_BIND can stay at its loopback default. If
# the proxy is elsewhere, put the server's address here, set JRAY_BIND to
# something that host can reach (0.0.0.0:8080), and firewall the port to
# this proxy.
server 10.0.0.42:8080;
keepalive 8;
}
server {
listen 443 ssl;
http2 on;
server_name jray.example.org;
ssl_certificate /etc/letsencrypt/live/jray.example.org/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/jray.example.org/privkey.pem;
# SPEC section 6 stage 1 body caps, mirrored at the edge. Section 8 asks for
# them in both places: the proxy rejects the bulk before it reaches the
# application, and the application stays correct if it is ever run without a
# proxy. These must not be tightened below the application's own limits or
# legitimate uploads get a 413 from nginx that the server never sees.
client_max_body_size 2m;
location = /api/v1/manifests/bundle {
# Series bundles only (section 2). This is why the cap is per-location
# rather than one global 25m: widening it everywhere would hand every
# other endpoint a 25 MiB budget it has no use for.
client_max_body_size 25m;
proxy_pass http://jray_server;
include snippets/jray-server-proxy.conf;
}
# Liveness. Kept out of the access log because uptime checks poll it hard.
location = /health {
proxy_pass http://jray_server;
include snippets/jray-server-proxy.conf;
access_log off;
}
location / {
proxy_pass http://jray_server;
include snippets/jray-server-proxy.conf;
}
}
# ---------------------------------------------------------------------------
# /etc/nginx/snippets/jray-server-proxy.conf
# ---------------------------------------------------------------------------
#
# proxy_http_version 1.1;
# proxy_set_header Connection "";
#
# proxy_set_header Host $host;
# proxy_set_header X-Forwarded-Proto $scheme;
#
# # $proxy_add_x_forwarded_for appends the real peer on the RIGHT of any header
# # the client sent. That is the safe form for this server: client_ip() in
# # src/auth.rs reads X-Forwarded-For from the right and walks left past further
# # trusted hops, so a client that forges its own entries only pollutes the part
# # that is ignored. Do not "harden" this to $remote_addr unless you have exactly
# # one proxy layer — with two, overwriting loses the real client.
# proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
#
# # Longer than JRAY_REQUEST_TIMEOUT_SEC (30 by default) so the application's own
# # timeout fires first and returns a real status rather than nginx reporting 504
# # for a request the server was still handling.
# proxy_read_timeout 60s;