Where the files go

Where the files go

Path	Holds	Back it up?
/var/lib/longbox	database, covers, uploads	yes — losing it loses reading state, ratings and every metadata edit
/var/cache/longbox	extracted pages	no — regenerated on demand, and evicted automatically
wherever you keep them	the comics themselves	your call; Longbox only reads them

The split follows the FHS: /var/lib is "state information... that pertains to one specific host", while /var/cache is for data that "must be able to be regenerated". Keeping the page cache out of /var/lib means a backup of the library never sweeps up gigabytes of extracted JPEGs.

The comics are not Longbox's data at all — they predate it, survive it, and another reader could index them tomorrow. /srv is the conventional home for them ("data for services provided by this system"), and it avoids ProtectHome=read-only biting you if they would otherwise live under /home.

systemd creates and owns the first two through StateDirectory= and CacheDirectory=, which also grant them through the sandbox and export the paths that app/config.py reads. That is deliberate: the unit does not repeat a path that also lives in /etc/longbox.env, so the two cannot drift apart.

Moving the data directory on a systemd host

Setting LONGBOX_DATA_DIR is not quite enough on its own, because the unit is hardened with ProtectSystem=strict: the entire filesystem is read-only to the service except the paths systemd has granted. Point the data directory somewhere the unit has not been told about and every write fails with

OSError: [Errno 30] Read-only file system: '/srv/longbox/data/pages'

on a directory that exists, on a writable disk, owned by the right user. The errno describes the mount namespace, not the hardware.

So set the path and re-run the installer, which reads /etc/longbox.env and generates the matching grant as a drop-in:

sudo ./deploy/install.sh

It writes /etc/systemd/system/longbox.service.d/10-longbox-paths.conf. A drop-in rather than an edit to the unit, because the unit is replaced on every upgrade; it is regenerated on each run, so going back to the stock paths withdraws the grant again. Your own overrides belong in a separate file, which sudo systemctl edit longbox creates for you and the installer never touches.

The same applies to LONGBOX_UPLOAD_DIR and LONGBOX_BACKUP_DIR when they sit outside the data directory. If you would rather not re-run the installer, the equivalent by hand is:

sudo systemctl edit longbox     # [Service] / ReadWritePaths=/srv/longbox/data
sudo systemctl restart longbox

uploads/ follows LONGBOX_DATA_DIR unless you set it explicitly — but it holds the only copy of anything added through the browser, so move the existing directory rather than just repointing the setting.

Moving the comics themselves

Comic paths are stored absolutely, so moving files on disk marks every one of them missing. Re-importing from the new location is not the fix: it strands reading state, ratings and metadata edits on the old rows. Move the files first, then tell the library where they went:

sudo longbox-cli relocate --dry-run /old/path /srv/longbox/comics
sudo longbox-cli relocate /old/path /srv/longbox/comics

It rewrites comic paths, watched folders and per-account library folders in one pass — the database only, never a file. Add a username to limit it to one account. A rewrite that would land on a path another comic already occupies is skipped rather than forced, and anything still absent afterwards is reported rather than quietly marked present. Follow it with longbox-cli verify to confirm the contents are what the library thinks they are.