Skip to content

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:

brew install --cask voilelab/plainshelf/plainshelf

If you prefer to tap the repository explicitly first:

brew tap voilelab/plainshelf https://github.com/voilelab/plainshelf
brew install --cask plainshelf

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):

brew install --cask voilelab/plainshelf/bookpkg-reader

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:

plainshelf_<version>_<os>_<arch>.tar.gz

Available builds:

OS Architectures
Linux amd64, arm64
macOS arm64

Each release ships a SHA256SUMS file. After downloading both the archive and SHA256SUMS into the same directory:

sha256sum --ignore-missing -c SHA256SUMS

3. Extract

mkdir -p plainshelf
tar -xzf plainshelf_<version>_linux_amd64.tar.gz -C plainshelf
cd plainshelf

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:

xattr -d com.apple.quarantine ./plainshelf-srv

4. Configure and run

cp config.sample.yaml config.yaml
./plainshelf-srv -conf config.yaml

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.

  1. Stop the running server (or docker stop plainshelf).
  2. Download/pull the new version using the steps above.
  3. 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.