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:
Use the shelf controls in the app to add a shelf. Creating one needs only a name, because PlainShelf makes the folder in its own shelves directory, or you can choose an existing folder to open instead.
Prebuilt server¶
After extracting a release archive, copy and edit the sample configuration:
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
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. Keep the port published on 127.0.0.1, as
above, and put a real boundary (reverse proxy auth or a VPN) in front before
exposing it — see Deployment and threat
model. Opening the UI through any other
origin needs that origin listed as well; the Docker
page has both settings.
2. Configure storage¶
A server configuration needs two durable locations:
app_conf.shelves[].lib_rootstores book packages and shelf runtime state.app_conf.store_pathstores server settings; reading progress, history, and time stay on each client device.
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, .md, .epub or .cbz file.
You can then edit its metadata, add a cover, place it in a folder, and open the
reader.
In the macOS desktop app you can select or drop several files at once, and switch to another app while they import. When an import of two or more books, or an import of shelves from another device's LAN share, finishes while PlainShelf is in the background, macOS shows a notification with how many were added and how many failed; clicking it brings PlainShelf back. macOS asks for permission the first time, and if you decline, imports carry on without notifications. Turn them off under Settings → Import & covers → Notify when an import finishes.
The book detail page shows the current source's size, including source.txt
and all files in its assets/ directory. Other sources, metadata and the cover
are excluded. Images sources show their listed page count instead of line and
character counts. Size is measured when opening the detail page, including on
read-only shelves; if it cannot be measured, the size row is hidden.
A Markdown book's detail page also lists the chapters its source splits into, the same H2 headings the reader navigates by. Selecting one opens the reader at that chapter instead of your last position. Plain text has no chapters, so the list is absent there.
On the Android app and narrow browser screens, the reader uses an immersive layout: tap the center of the page to show or hide its controls, swipe left for the next chapter, and swipe right for the previous chapter. Vertical swipes continue to scroll within the current chapter. These gestures are shown once the first time you open a book; the ? button in the reader's controls brings the reminder back at any time.
The library's search box matches titles, authors, tags and comments. It ignores
case, accents and full-width or half-width forms, treats katakana as hiragana,
and matches Traditional Chinese, Simplified Chinese and Japanese shinjitai or
kyujitai forms of the same character, so 红楼梦 finds 紅樓夢. Name separators
such as · and ・ match a space. It does not search book contents.
An EPUB is converted to text as it is imported; see EPUB import for what is kept, what is dropped, and how to choose the output layout.
A CBZ is extracted into an ordered image source; see CBZ import for supported images, metadata, and limits.
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¶
The on-disk format freezes at 1.0.0-rc1. Until that release it can still change
between releases, so upgrading a v0.x shelf may require a fresh start for some
data; see
Compatibility policy.
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.