Getting Started¶

This guide takes you from an installed PlainShelf release to your first local library. To build the project itself, use Local Development Setup.

1. Choose how to run PlainShelf¶

macOS desktop app¶

Install and open the Homebrew app:

brew install --cask voilelab/plainshelf/plainshelf
open -a PlainShelf

Use the shelf controls in the app to add a local shelf directory.

Prebuilt server¶

After extracting a release archive, copy and edit the sample configuration:

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

Open http://127.0.0.1:20000. Relative paths in config.yaml are resolved from the directory where the server starts; use absolute paths for service installs.

Docker¶

docker run --rm \
  --name plainshelf \
  -p 127.0.0.1:20000:20000 \
  -v plainshelf-data:/data \
  ghcr.io/voilelab/plainshelf:latest

Open http://127.0.0.1:20000. The named volume preserves the shelf and application store when the container is replaced.

Keep the server private

Bind the port to 127.0.0.1 unless PlainShelf is behind a trusted VPN or authentication boundary. The default Docker configuration does not enable application-level authentication.

2. Configure storage¶

A server configuration needs two durable locations:

app_conf.shelves[].lib_root stores book packages and shelf runtime state.
app_conf.store_path stores application-level state.

The sample configuration works for local development. Before a long-running deployment, review Local Shelf File Source.

3. Add a book¶

Open the library, choose Import, and select a .txt or .md file. You can then edit its metadata, add a cover, place it in a folder, and open the reader.

PlainShelf creates a .bookpkg directory in the shelf and assigns a stable book ID. Renaming the title or moving the book between folders does not change that ID. See Data Model for the on-disk layout.

4. Back up before experimenting¶

PlainShelf is pre-alpha. Back up both the configured shelf and application store before upgrades or manual filesystem edits. Stop write activity first so the backup captures a consistent state.