Deployment runbook

The whole sequence, in order, from a bare Linux box to a server the household uses daily — reachable by name, over HTTPS, inside and outside the house, with mail, external sign-in and backups working.

Each stage has a checkpoint. Do not move past one that fails: almost every confusing failure later on turns out to be an earlier stage that was never actually verified, and diagnosing it from three stages downstream is much harder than catching it here.

Every name here is invented

comics.example.com stands in for whatever name you choose, and 192.168.1.10 for the server's address on your network. Neither will work as written.

What this assumes

• A Linux host you control, with sudo.
• A domain name you own, if you want HTTPS and access from outside. A LAN-only install can skip stages 4 and 5 entirely.
• The comics already on that host, or reachable from it.

Stage 1 — Install

Installing has the detail. For a systemd host:

git clone <your-repo> longbox && cd longbox
sudo ./deploy/install.sh

That installs Python and unar, creates a longbox service user, builds a virtualenv in /opt/longbox, puts data in /var/lib/longbox, enables the service, and puts longbox-cli on the path.

Checkpoint. curl -s localhost:8000/healthz returns a version and an account count of zero.

Stage 2 — Point it at the comics

Set LONGBOX_BROWSE_ROOTS in /etc/longbox.env, not in the unit — the unit is replaced on every upgrade and the env file never is.

LONGBOX_BROWSE_ROOTS=/srv/comics

sudo systemctl restart longbox

If the comics live outside the default paths, re-run sudo ./deploy/install.sh so the sandbox grant is regenerated. Skipping this is the EROFS failure in Troubleshooting.

Checkpoint. Register the first account — it becomes the administrator — and import a folder. Covers appear in the grid.

Stage 3 — Back it up before you depend on it

Do this now, while there is little to lose, so the procedure is proven before it matters.

Admin → Server → Backups sets the schedule and retention. Then prove a copy can leave the machine:

sudo longbox-cli backup --label first
rsync -av server:/var/lib/longbox/backups/ ~/longbox-backups/

A backup on the same disk as the database survives a mistake, not a failed drive.

Checkpoint. A .db.gz file exists on a different machine.

Stage 4 — A name, and HTTPS

Longbox speaks plain HTTP and should stay that way, with a reverse proxy in front terminating TLS. Reverse proxy and HTTPS covers it, and deploy/proxy/ is a complete worked example for a host running several apps behind one Caddy.

Order matters here:

1. DNS first. An A record for comics.example.com pointing at your public address.
2. Router. Forward 80 and 443 to the server. Nothing else.
3. Caddy, on staging certificates. Let's Encrypt allows only a handful of failed attempts an hour, and a DNS typo or a missed forward will burn through them. Start on staging, then switch.
4. Switch to production certificates and reload.

Checkpoint. https://comics.example.com loads with a certificate your browser trusts, from outside the house.

Stage 5 — Tell Longbox it is behind a proxy

Three settings, in /etc/longbox.env:

LONGBOX_HOST=127.0.0.1
LONGBOX_PUBLIC_URL=https://comics.example.com
LONGBOX_SECURE_COOKIES=1

And the one that is easy to get wrong — LONGBOX_TRUSTED_PROXIES. The login throttle keys on the caller's address, which behind a proxy arrives in X-Forwarded-For, a header anyone can write. The default of loopback is right for a proxy on the same host. Never *. Both failure modes are in Troubleshooting.

Checkpoint. Sign in over https://. A password reset link generated from Admin → People names the public URL, not an internal address.

Stage 6 — The same names on the LAN

Devices at home should reach the server directly rather than going out to the public address and back in. Many routers cannot do that hairpin at all.

Answer the same public names with the server's private address on the LAN — deploy/proxy/dnsmasq-lan-names.conf is the worked example. One line per name, never a wildcard for the whole domain, or you will answer for mail and www as well.

Checkpoint.

dig +short comics.example.com @127.0.0.1   # the LAN address
dig +short comics.example.com @1.1.1.1     # the public address

Both resolve; the first is private. The same URL works on a phone on wifi and on mobile data.

Stage 7 — Mail

Optional, and only ever used for setup and reset links. Without it, administrators hand out links by hand, which works fine for a household.

The SMTP fields are a few boxes in Admin → Mail; getting mail delivered is the harder half, and sending straight from a home connection does not work. See Sending mail.

Checkpoint. Send a test message in Admin → Mail arrives, and not in spam.

Stage 8 — External sign-in

Also optional. External sign-in covers Google, Apple and Facebook.

The redirect URI registered with each provider must match LONGBOX_PUBLIC_URL exactly — this is the one that breaks silently if the name ever changes.

Checkpoint. Sign in with one provider, sign out, and sign in again with the password. Both reach the same account.

Stage 9 — Readers and phones

The OPDS feed is what phones and e-readers talk to. Reading and OPDS has the client notes.

Point readers at the https:// address only — OPDS clients send your password with every request.

Checkpoint. A client on a phone lists the library and downloads an issue.

Stage 10 — Prove the whole thing

sudo longbox-cli verify        # hash every comic, report anything changed
sudo longbox-cli list-users    # accounts, roles, comic counts
curl -s https://comics.example.com/healthz

The first run of verify hashes the collection in full and stores the result, which is what makes every later run — and the check after a migration — meaningful.

Keep this list

When you rebuild on a new machine, stages 4 through 8 are the ones with state that lives outside Longbox: DNS records, router forwards, certificates, provider consoles. The data migration is covered separately in Migrating to a new machine; this list is what that page cannot move for you.