Configure a local shelf file source¶
A local shelf keeps the library on a disk directly attached to the machine running PlainShelf — an internal drive, an external USB drive, a local data volume. This is the setup PlainShelf works best on.
Use it for libraries you care about, unless you specifically need an experimental network-backed shelf.
Before you start¶
You need:
- A directory on a local filesystem that the PlainShelf process can read and write.
- Enough free disk space for imported books, cover images, metadata, and temporary files.
- One PlainShelf server process using the shelf at a time.
PlainShelf stores user-owned library data and rebuildable runtime state under the shelf root. See the data model for the full shelf layout.
1. Create a shelf directory¶
Create a directory for the shelf and make sure the user running PlainShelf owns it or can write to it:
You can place the directory anywhere that is stable across restarts. For example:
- A project-local development directory such as
./workspace/shelf. - A user data directory such as
$HOME/PlainShelf/shelf. - A persistent server directory such as
/var/lib/plainshelf/shelf. - A Docker volume mounted at
/data/shelf.
On the desktop app¶
The desktop app has no config file, so a shelf is created in Settings →
Shelves → Add a shelf. The dialog first asks where the shelf lives, then for
its name and that source's settings. On New folder, the app creates the
shelf in its own data directory, under shelves/<shelf id> — beside the
shelves.json that records it:
| Platform | Default shelf directory |
|---|---|
| macOS | ~/Library/Application Support/PlainShelf/shelves/<shelf id> |
| Linux | ~/.config/PlainShelf/shelves/<shelf id> |
| Windows | %AppData%\PlainShelf\shelves\<shelf id> |
The dialog shows the exact path before you create the shelf, and that path is what is recorded. To put the shelf somewhere else, such as an external drive or a directory you back up separately, choose Existing folder and type the Folder path in or pick it with Browse; a directory you chose is kept even if you then change the name.
2. Configure lib_root¶
Edit your PlainShelf config file and set the shelf lib_root to the local
directory:
lib_root may be relative or absolute:
| Path type | Behavior |
|---|---|
| Relative path | Resolved relative to the process working directory when PlainShelf starts. |
| Absolute path | Uses that exact path regardless of the process working directory. |
For production or service deployments, prefer an absolute path so startup behavior does not depend on the working directory.
3. Configure the application store¶
PlainShelf also uses app_conf.store_path for server settings outside the shelf
itself:
Keep store_path on reliable local storage. It does not replace lib_root;
both paths should be configured and persisted. Reading progress, history, and
time are stored by each client rather than here.
For every other key the config file accepts, see the Configuration reference.
4. Run PlainShelf¶
Start PlainShelf with the config file that points to your local shelf:
Then open the web UI and import or create books as usual.
Docker notes¶
The default container config stores shelf data at /data/shelf and application
store data at /data/store. Use a named volume or bind mount so data persists
after the container exits:
docker run --rm \
--name plainshelf \
-p 127.0.0.1:20000:20000 \
-v plainshelf-data:/data \
plainshelf
If you mount a custom config file, make sure its lib_root and store_path
match paths that exist inside the container.
Backup guidance¶
The shelf is plain files, so backing it up is a directory copy:
- Stop PlainShelf or make sure no imports, edits, moves, or deletes are running.
- Back up the entire
lib_rootdirectory. - Back up
store_pathif you want to preserve server settings. Back up client profiles separately for reading progress, history, and time.
Do not back up only individual .bookpkg folders unless you intentionally want
a partial library backup.
Backup and restore has the full procedure for each installation, what a shelf-only copy leaves behind, and how to restore.
Open a shelf read-only¶
To browse a shelf without writing anything to it (a restored backup, a read-only
mount, an archived snapshot), set read_only on that shelf:
app_conf:
shelves:
- id: archive_shelf
name: Archive (read-only)
lib_root: /mnt/backup/plainshelf-shelf
read_only: true
PlainShelf then creates no folders, writes no lock or cache files under app/,
and refuses every edit with an error instead of touching the shelf. lib_root
must already exist. See Shelf cache and disk
I/O for exactly what
is skipped.
While you are browsing a read-only shelf, the app hides the controls that would write to it (importing, editing metadata, sources and covers, creating and moving folders, deleting, and restoring from the trash) and shows a banner saying the shelf is read-only. Browsing, reading, searching and rescanning stay available. Switching to a writable shelf brings those controls back without a reload; the shelves you can write to are unaffected by the ones you cannot.
To do the same for every shelf at once, set read_only next to shelves
instead:
PlainShelf then answers every write request with HTTP 403 and opens each shelf,
including one added after startup, as if it carried read_only: true.
Rescanning a shelf is still allowed, because it only walks the shelf and
rebuilds the in-memory cache.
From the desktop app¶
The desktop app keeps its shelves in its own data directory rather than in a config file, so the same setting is a Read-only shelf toggle in Settings → Shelves — in the dialog that adds a shelf, and in Modify for a shelf that already exists. Switching it closes that shelf and opens it again in the new mode, without restarting the app.
The toggle works in both directions, including on a shelf that is already
read-only: what read_only stops is writing to the shelf, and the desktop
shelf list lives outside every shelf.
Share shelves on your local network (desktop app)¶
Settings → Shelves → Share on local network exports the shelves you tick,
read-only, to other devices on the same network. It is the server's
dav_export behind a switch:
- Off by default, with no shelves ticked on a fresh setup. Turning it off closes the listener immediately, including active transfers.
- Turned on, no shelf is shared until you tick it. An unticked shelf is 404 on the export, the same as one that does not exist.
- The page shows the address (
http://<LAN IP>:20001/dav/, one shelf per/dav/<shelf id>/), the token every request must carry, and a QR code holding both plus every ticked shelf (see the QR code). Replace token revokes the old one at once. - It binds one detected local LAN IPv4 address and refuses
0.0.0.0; with more than one network the page lets you choose which. If that address is gone at the next start, the switch stays on and the page says why it is not running. - The switch, the ticked shelves and the token are kept in the app's data
directory (
lan_share.json,lan_share.token), not in any shelf, and survive a restart. The port is20001unlesslan_share.jsonsetsport. - On macOS, a PlainShelf icon sits in the menu bar while sharing is running and disappears when it stops. Its menu lists the shared shelves and the address, and offers Copy URL (the same address the settings page shows), Stop Sharing and Open PlainShelf. It never shows the token. The icon lives only as long as the app: closing the last window still quits PlainShelf and stops sharing.
The URL reveals the computer's network address and shelf identifiers; the token and QR payload grant read access to the selected shelves. Treat the connection details as sensitive: keep them out of public screenshots, logs and messages. If the token or QR is disclosed, turn sharing off or replace the token and update the receiving devices. Replacing it affects subsequent requests; it does not erase files a device has already downloaded. Saved enabled settings can start the listener again on restart, so switch sharing off when finished.
For the alternatives, scope and security tradeoffs, see the desktop LAN sharing decision record.
The QR code¶
The QR code is JSON, and its shape is a promise between devices:
{
"v": 1,
"url": "http://192.168.1.20:20001/dav/",
"token": "…",
"shelves": [
{"id": "default_shelf", "name": "Default Shelf", "url": "http://192.168.1.20:20001/dav/default_shelf/"}
]
}
vis the format version. A device reading the code must refuse any value other than1instead of guessing at the fields.shelveslists only the ticked shelves, in the order of the shelf list, and is[]when none is ticked. Eachurlopens that shelf on its own, so a scanner needs nothing else; the export rooturlitself lists nothing (404).- The token is only ever in
token, never in a URL. Send it asAuthorization: Bearer <token>. - Ticking or unticking a shelf, replacing the token, or changing the address changes the code; scan it again afterwards.
- A QR code holds about 2 KB, roughly 18 shelves with short names; past that the page shows an error instead of the code. The address and token are still shown, so add the shelves by hand, or share fewer at a time.
Import on another desktop¶
In Settings → Shelves → Add a shelf, choose Paste QR content to add them all, paste the QR's JSON text, then click Preview shelves. Check the names and addresses before confirming with Import shelves. Pasting or previewing does not connect, save entries or store the token. This accepts text, not images.
The shared Go parser (internal/lanshare) rejects unknown versions, missing
fields and non-HTTP(S) addresses before any entry is created. URLs must have no
userinfo, query or fragment, and shelf URLs must use the share root's origin.
An empty shelves: [] is valid but offers nothing to import.
After confirmation, each shelf becomes a read-only plainshelf source using
its supplied name and URL. Each source is checked before saving. A failed
connection or refused token leaves that source unsaved; other sources are
still attempted, and the dialog shows each result. Paste and confirm again to
retry failures. An existing PlainShelf source with the same URL (ignoring a
trailing slash) is skipped, including on retries: its name and token are never
replaced. Name collisions receive the usual new shelf ID suffix.
Imported tokens use the existing OS keychain flow, never shelves.json, logs
or URLs. The pasted JSON is cleared after import or closing the dialog.
The share publisher's existing lan_share.token storage is separate from
imported credentials. For Android, use Add a shelf → Scan a QR code to add them all,
then preview and confirm the shelves. The Android reader uses this same parser and import
semantics, with tokens in Android Keystore; see
Android QR import for camera
permissions, results and device verification.
The first time it is turned on, the operating system's firewall may ask whether PlainShelf may accept incoming connections; allow it on private networks only. The export is plain HTTP, so share only on a network you trust; see the threat model.
Read a shelf from another device (desktop app)¶
Settings → Shelves → Add a shelf → Another device adds a
shelf that lives elsewhere, read-only: another PlainShelf's local-network share
(above), the server's dav_export, or
any WebDAV server holding a shelf directory, such as a NAS.
- Enter the URL of the shelf folder, the one that holds
books/. For another PlainShelf it ishttp://<address>:20001/dav/<shelf id>/, as its share page shows. - Another PlainShelf needs the share's token. WebDAV takes an optional account and password or token.
- The dialog checks the source as soon as the address and token are filled in and shows how many books it found, and Add shelf checks again if needed. A refused token and an address that cannot be reached are reported differently, and nothing is saved.
- The token is stored in the operating system's keychain (Keychain on macOS,
Credential Manager on Windows, the Secret Service on Linux), never in
shelves.json. Removing the shelf removes it from the keychain. - If the keychain cannot answer at startup, for example because it is locked, that shelf is skipped and the app says so; your other shelves open as usual. It remains visible in Settings → Shelves, with its source, URL and a safe failure summary. Unlock the keychain or restore the connection, then choose Retry to open it without restarting, or remove it there (including its keychain secret). Virtual shelves have no Open folder action or read-only toggle.
The same is available in a server's config file as a
source block.
Troubleshooting¶
PlainShelf cannot create or update books¶
Confirm the user running PlainShelf can create, rename, and delete files in
lib_root:
touch ./workspace/shelf/.write-test
mv ./workspace/shelf/.write-test ./workspace/shelf/.write-test-renamed
rm ./workspace/shelf/.write-test-renamed
Books disappear after restart¶
Check whether lib_root was configured as a relative path and PlainShelf was
started from a different working directory. Use an absolute path for service
deployments.
Docker data disappears after container exit¶
Make sure /data or both /data/shelf and /data/store are backed by a Docker
volume or bind mount. Container-local files are removed when the container is
deleted.