My BookWyrm shelves, on my own site
My reading lives on BookWyrm, a federated network for books. I wanted the shelves on my own site, searchable, without running a database for it.
- Client
- Open source (MIT)
- Role
- Design & full build
- Period
- 2026
- Stack
- Perl, Mojolicious, Podman, systemd
Context
My reading lives on BookWyrm, a federated social network for books. I wanted the shelves on my own site too, with search, filters and a page for each book, without adding a database to look after.
Decision
- No database. The catalogue is a single JSON file. The site reads it and notices when it changes, without a restart.
- Two processes, one file. The site runs in one container with the data mounted read-only. The downloader runs in another, started by a systemd timer, and is the only thing that writes. It detects added, removed and changed books, and replaces the file atomically.
- Public data only. The downloader reads the public shelves, so no password or token is needed.
- Deploy. A Bash script builds the image for the server’s architecture, from Linux or from an Apple Silicon Mac, moves it over SSH, updates both systemd units and checks the site before calling it done.
Trade-off
Reading only public data keeps secrets out of the system, but private shelves cannot appear and the catalogue is only as fresh as the last sync. For a personal library that does not change by the minute, that is the right side of the trade.
Outcome
Live at books.federicorinaldi.com, as a rootless Podman container behind a reverse proxy, with systemd user units for the site and the downloader. A failed update rolls the services back to the previous image. Tests cover the downloader and the reader with local fixtures.
The code is MIT licensed: code.federicorinaldi.dev/federico/federico-book-library.