Installation¶
This page covers installing prebuilt PlainShelf releases. If you would rather build from source, see Local Development Setup.
Every tagged release publishes:
- A Homebrew cask for the macOS desktop client
- Prebuilt server archives for Linux and macOS
- A multi-architecture Docker image on the GitHub Container Registry (GHCR)
Release artifacts live on the GitHub Releases page.
Before 1.0
The on-disk format freezes at 1.0.0-rc1; until that release the data
layout can still change between versions, and behavior can change either
way. Pin to a specific release tag.
Option 1 — Homebrew desktop app (macOS, Apple Silicon)¶
The desktop app and the standalone reader require macOS 13 (Ventura) or later on Apple Silicon. Intel Macs and earlier macOS versions are not supported: Homebrew refuses to install either cask there, and macOS refuses to open either app.
The quickest way to install the desktop app on Apple Silicon Macs is with Homebrew:
If you prefer to tap the repository explicitly first:
Upgrade with brew upgrade --cask plainshelf, uninstall with
brew uninstall --cask plainshelf.
The desktop cask depends on the standalone reader cask
(bookpkg-reader), so brew install/brew upgrade of plainshelf also
installs the reader. That is what lets the desktop app's "read" action open a
book: it shells out to the installed PlainShelfReader app. The reader is
not bundled inside PlainShelf.app — it is installed as its own cask
alongside the desktop app. See
the reader section below for
what the reader installs and how to remove it.
The bundled .app is unsigned and unnotarized; the cask's postflight_steps
clears Gatekeeper's quarantine attribute so the app opens normally on
first launch.
The desktop app's bundle identifier is com.voilelab.plainshelf, pinned in
desktop/build/darwin/Info.plist so it no longer depends on the Wails build
template. Releases up to 0.12 shipped as com.wails.plainshelf, the Wails v2
template default; the identifier changed before 1.0.0-rc1 to match the
reader's com.voilelab.plainshelf-reader. macOS keys permissions to the
identifier, so after upgrading from one of those releases macOS asks again for
Local Network access the first time you turn on
Share on local network.
Your library, settings, and saved SMB and pCloud passwords are unaffected:
they are stored under PlainShelf, not under the bundle identifier.
brew zap --cask plainshelf removes the caches and preferences of both
identifiers.
For other platforms, build the desktop client from source — see Local Setup.
Experimental — standalone book-package reader¶
bookpkg-reader is an experimental cask for the standalone reader that
opens a single .bookpkg package. The plainshelf desktop cask declares it as
a dependency (depends_on cask: "voilelab/plainshelf/bookpkg-reader"), so you
normally do not install it directly — installing the desktop app pulls it in.
Both casks are pinned to the same release and move to each new stable release together, so the reader always matches the desktop app that depends on it.
You can also install the reader on its own — macOS on Apple Silicon
(darwin/arm64):
The reader registers .bookpkg as a document package on macOS: Finder shows
each one as a single item, and double-clicking it opens it in PlainShelf Reader.
If the reader is already open, the book opens in a new window of that same
reader instead of starting a second copy; a book that is already open has its
window brought to the front.
The reader .app is also unsigned and unnotarized; its postflight_steps
clears the quarantine attribute the same way. Uninstall with
brew uninstall --cask bookpkg-reader.
brew zap --cask bookpkg-reader removes only the reader's own data (keyed to
its com.voilelab.plainshelf-reader bundle identifier). It does not touch
the plainshelf desktop app's library.
Option 2 — Prebuilt server binary¶
1. Download¶
Grab the archive for your platform from the latest release. Archives are named:
Available builds:
| OS | Architectures |
|---|---|
| Linux | amd64, arm64 |
| macOS | arm64 |
2. Verify the download (recommended)¶
Each release ships a SHA256SUMS file. After downloading both the archive
and SHA256SUMS into the same directory:
3. Extract¶
Each archive contains the plainshelf-srv binary, LICENSE, README.md, the
version-matched docs/ directory, the README preview image, and a
config.sample.yaml to use as a starting point. The relative documentation
links in README.md therefore work both online and from the extracted archive.
macOS Gatekeeper
The macOS binaries are unsigned. On first run you may need to clear the quarantine attribute:
4. Configure and run¶
By default the server listens on http://127.0.0.1:20000. See Local Shelf File Source for shelf configuration.
Option 3 — Docker¶
Tagged releases push a multi-arch (linux/amd64, linux/arm64) image to
GHCR at ghcr.io/voilelab/plainshelf.
# Pin to a release tag
docker pull ghcr.io/voilelab/plainshelf:v1.0.0
# Or track the most recent stable release
docker pull ghcr.io/voilelab/plainshelf:latest
latest tag
latest only follows stable releases. Pre-release tags (those containing
a -, e.g. v1.0.0-rc1) are published but do not update latest.
Run the server on http://localhost:20000 with data persisted in a volume:
docker run --rm \
--name plainshelf \
-p 127.0.0.1:20000:20000 \
-v plainshelf-data:/data \
ghcr.io/voilelab/plainshelf:latest
Keep it local
The default container config protects writes with local_token, which is a
CSRF boundary and not a login: anything that can reach the port can read the
token out of the served page. Publish the port on the loopback address
(127.0.0.1) only, and do not expose 0.0.0.0:20000 to an untrusted
network without a real boundary (reverse proxy auth or a VPN edge) in front
of the container. See Deployment and threat
model. Reaching the UI through any other
origin (another host port, a NAS LAN IP, a custom domain) needs that exact
origin in app_conf.security.allowed_origins too, or the Origin check
rejects writes; the Docker page has both settings.
Stop timeout on a network shelf
docker stop and Compose wait 10 seconds before killing the container. A
killed server loses its unsaved shelf caches and rescans on the next start,
which is slow over SMB. With a network shelf, allow more time:
docker stop -t 30 plainshelf, or stop_grace_period: 30s in Compose. See
server_conf for what shutdown does.
For custom configuration and the bundled defaults, see the Docker page.
Upgrading¶
v0.8 reading history and reading time do not carry into v0.9.0 or later
Starting with v0.9.0, PlainShelf keeps these records per-device. v0.8's server-side values are not migrated and no longer appear after upgrading. PlainShelf provides no export, import, or recovery path for them. See v0.8 reading-data breaking change for details.
Reading progress does not carry into v0.10.0 or later
v0.10.0 changed the per-device reading-progress file to a timestamped format so that the desktop app and the standalone reader can reconcile concurrent writes. The older format is not migrated: on first run of v0.10.0 or later, web and desktop books start at the beginning again on that device. Android's per-book progress files are unaffected.
- Stop the running server (or
docker stop plainshelf). - Download/pull the new version using the steps above.
- Restart against the same data and config.
Because PlainShelf keeps data in human-readable files, back up your shelf and application store directories before upgrading across breaking changes. See Backup and restore for what to copy, what a shelf-only copy leaves behind, and how to roll back to an older release.