Skip to content

feat(media): author Audiobookshelf beside Jellyfin, behind a fifth Hicks pass (#140) - #629

Merged
Gerrrt merged 1 commit into
mainfrom
gerrrt/github-issue-140-38935b
Sep 22, 2026
Merged

Gerrrt merged 1 commit into
mainfrom
gerrrt/github-issue-140-38935b

Conversation

@Gerrrt

@Gerrrt Gerrrt commented Sep 22, 2026 •

Copy link
Copy Markdown
Owner

Refs #140. Authors Audiobookshelf in stacks/media. Nothing is deployed on smaug by this PR. Deploying is build-the-nas.md §6.5, and the roadmap holds that until the mirror is whole (#558). The issue stays open until the service is deployed and a NAS set holds its archive.

Two premises in the issue were wrong

  • "No rule beyond the 50→40 in Media tier: Jellyfin — placement answers the terminal-VLAN problem #138." No such segment rule exists. Hicks reaches 10.0.40.30 through two port-scoped passes, 443 and 8096, and the phones are on Hicks. Audiobookshelf listens on 13378, so it needs a fifth pass, vlan50 net → 10.0.40.30:13378, named Allow 13378 to smaug and placed above Block access to CasaBonita. You create it in pfSense as step 1 of §6.5. The docs describe it as specified, not as existing.
  • Backups. backup-nas.sh pulled one hard-coded path (jellyfin/config). The listening-progress database would have been snapshotted nightly and never left the NAS.

What changed

  • stacks/media/compose.yaml: a new audiobookshelf service, pinned by digest, running as 65534 with a read-only root, cap_drop: ALL, init: false, a 1 GiB ceiling and a busybox-wget healthcheck. The library is mounted read-only, so this is audiobooks only and podcasts are deferred. Every non-obvious line is backed by a measurement on the pinned image, recorded in the MEASURED block.
  • scripts/backup-nas.sh:
    • It pulls a table of archives from one snapshot into one set; audiobookshelf-state holds config/ and metadata/.
    • The Audiobookshelf row is pending. While its directory is absent it is skipped, and the skip is logged by name. Once the directory exists it is pulled and verified strictly. §6.5's Done commit flips the row to required. Without this, merging would have failed every Saturday's Jellyfin pull until the deploy.
    • --verify-only checks each set against its own MANIFEST, so the Jellyfin-only sets already kept still verify.
  • scripts/backup-volumes.sh: a sentinel and companions for audiobookshelf-state. The compose parser no longer reads a ${VAR}/sub:/mnt bind mount as a named volume. Inventory output is byte-identical for observability, sensitive and lab. soc differs only in the script name inside its existing missing-sentinel error.
  • ADR-0050 records the pass, the podcast deferral, the multi-archive pull, the pending state and the absence of a secrets file. ADR-0016 and ADR-0045 get forward pointers.
  • Docs:
    • build-the-nas.md: §0.5, §0.6, §4, §6.3, a new §6.5 with a Done block to fill in, §7 and §8.
    • The media README, including a measured admin-reset command.
    • network.md, security.md, architecture.md, roadmap.md, changelog.md, restore-the-stack.md, schedule-maintenance.md, successor-handover.md, observability.md and README.md.
    • The dependabot comment, and the unit and Makefile descriptions.

Verification

  • Scratch boot of the pinned image on the monitoring host, read-only as 65534, with a generated book, a root user, a scan, a progress write and a forced transcode:
    • no writes outside /config and /metadata;
    • the database is in rollback-journal mode, and progress is stored in mediaProgresses;
    • 91 MiB idle and 119 MiB while transcoding;
    • admin reset: clearing root's hash lets a blank password sign in, and the old password gets a 401.
  • The committed service definition, booted from stacks/media/compose.yaml: healthy in about 9 s, /healthcheck returns 200, and no tini warning. Torn down with down -v afterwards.
  • Bench pull against a fake snapshot tree on oracle (with --local-only, into the worktree), exit codes as expected in all three cases:
    • Audiobookshelf absent: skipped, rc 0.
    • Present with no sentinel: rc 1, no MANIFEST written.
    • Present with its sentinel: both archives verified.
  • The two real retained sets, copied into the worktree, pass --verify-only --all under the new script.
  • scripts/validate.sh passes, before and after rebasing on main. The only skips are the usual worktree-only systemd checks.

Left for you, in order

  1. Once erebor lost ZVTBSDL3 at lifetime hour 27, node_exporter hung nine minutes before the fault, and erebor/apps has no copy anywhere else #558 has the mirror whole, work through §6.5 on smaug: the pfSense pass, the directories, re-fetching the stack, the root user, and a phone test of progress sync.
  2. After that, I'll check the rule's position from morpheus, run make backup-nas from the main checkout to see both archives, flip the row to required, fill in the Done block, and the issue closes then — by hand, not by this merge.

🤖 Generated with Claude Code

…cks pass

Audiobookshelf joins stacks/media for the one thing Jellyfin does not
do: listening progress that follows a person between devices. It is
authored and validated here; deploying it on smaug is build-the-nas.md
§6.5, which waits on the mirror being whole (#558).

The issue said no rule beyond #138's 50→40 would be needed. There is no
such rule - Hicks reaches smaug on 443 and 8096, one pass per port - and
the phones are on Hicks, so the service brings a fifth pass,
`Allow 13378 to smaug`, created when it is deployed. ADR-0050 records
that, audiobooks only with podcasts deferred behind a read-only library,
and the backup shape.

Measured on the pinned image first: it binds port 80 by default, which a
capability-less non-root process cannot (PORT=13378); /config and
/metadata do not exist in the image; its entrypoint is tini (init: false,
as for Immich); the database is in rollback-journal mode; 91 MiB idle.
The admin reset was proved on a scratch boot, not described.

backup-nas.sh now pulls a table of archives from one snapshot instead of
one path, so Audiobookshelf's database leaves the NAS with Jellyfin's.
Its row is `pending` until §6.5's Done commit flips it: skipped by name
while its directory is absent, so merging this does not fail Saturday's
Jellyfin pull. Verification reads each set against its own MANIFEST, so
the retained Jellyfin-only sets still verify - both were re-verified, and
a bench pull on oracle covered the skip, a missing sentinel and two
archives. backup-volumes.sh's compose parser learns that a ${VAR}-spelled
source is a host path, which it already was.

Refs #140

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Gerrrt
Gerrrt merged commit 4d1fcfe into main Sep 22, 2026
3 checks passed
@Gerrrt
Gerrrt deleted the gerrrt/github-issue-140-38935b branch September 22, 2026 22:35
Gerrrt added a commit that referenced this pull request Sep 22, 2026
#629 and this branch each rewrote the same files for a second media
service. Main's side is the base and Navidrome is added on top of it:

- backup-nas.sh is #629's table, including its pending/required state.
  navidrome-data joins it as a pending row. This branch's own two-archive
  rewrite is dropped.
- backup-volumes.sh gains the navidrome-data sentinel and companions in
  #629's version of the tables.
- compose.yaml and .env.example carry all four services.
- build-the-nas.md keeps §6.5 for Audiobookshelf. Navidrome's steps move
  to §6.6 and use the same pending -> required flip, which replaces the
  Saturday-ordering hazard this branch used to document.
- Passes are named by port. 4533 exists as of 2026-09-22, so it is the
  fifth. 13378, which ADR-0050 calls the fifth, will be the sixth.

Refs #141

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Gerrrt Gerrrt mentioned this pull request Sep 26, 2026
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant