Pocket Bookshelf

Pocket Bookshelf is a free, open-source (MIT), self-hosted reading log: what you read, what you thought of it, the lines worth keeping and what to read next. One Go binary, one SQLite file, book details and covers from Open Library and Google Books, a REST API with personal tokens. It is made by the author of Pocket Homelab as its reading companion. Pocket Homelab is the shelf in your pocket: the books you are reading with the page you are on, finishing a book with a rating and a few words while it is fresh, the library, the plan, quotes, authors, series and the year’s stats. Importing from Goodreads, StoryGraph and Kindle, changing a cover and the daily highlights stay in the web app.

Install Pocket Bookshelf

If you do not run it yet, the project on GitHub has the setup for Docker and bare metal. The shortest way is the container:

mkdir pocket-bookshelf && cd pocket-bookshelf
curl -O https://raw.githubusercontent.com/abjelosevic88/pocket-homelab-bookshelf/main/docker-compose.yml
docker compose up -d

Open it in the browser, create your account and set TZ: it decides what “today” is for finish dates and the current year.

Set up

Environment keys

Key	Field	Required	Secret	Where to get it
BOOKSHELF_URL	Pocket Bookshelf URL	Required	—	Base address of your Pocket Bookshelf server, for what you are reading, your shelf, your thoughts and quotes, and what to read next. Leave empty to hide it.
BOOKSHELF_API_KEY	Pocket Bookshelf API token	Required	—	A token from Pocket Bookshelf → Settings → API tokens (starts with pb_). Stored in the Keychain.

Reading now

The Reading screen opens on the web app’s home page:

• The year: books read against your yearly goal, with the pace (“2 behind schedule”) and the pages read.
• Reading now: a card per book with its cover, the progress bar and a page field with Save; Finished… asks for the date, a half-star rating and a few words in one go.
• Up next: the first books of the plan with Start, and The whole plan.
• Recently finished with their ratings, and a random quote with Another quote.
• Rows for the Library, Plan, Quotes, Authors, Series and Stats, each with its count.

+ adds a book; ⋯ has Log reading, Reading settings, Open Pocket Bookshelf and Refresh.

Adding a book

Add book searches Open Library and Google Books by title, author or ISBN, with covers. A result already on your shelf says so and opens that book (or adds another copy). Pick one and say where it stands: Want to read (with why or who recommended it), Reading, or Read with the finish date and a rating; then the format and tags, with the book’s subjects as one-tap suggestions. The cover is downloaded by the server. A book no catalogue knows is added by hand.

A book

A book’s page has its cover, title and authors (an author opens their page), and the actions that fit where it stands: Start reading, Log page…, Finished…, Abandon, Back to want to read, Read it again. Under them:

• Rating in half stars from ½ to 5, and Favourite.
• My thoughts, with ## lines shown as section titles. Write starts from your thought templates (fiction, non-fiction, or your own from the web app’s settings).
• Quotes with page and note: add, edit, delete, favourite.
• Reading history: every time through the book; add a past read, edit or delete one.
• Details: pages, published, publisher, ISBN, language, format, tags and series, and for a want-to-read book the month it is planned for and the note. Edit details changes them; Delete removes the book with its reads and quotes.

Library, plan, quotes, authors

• Library: the shelf by status (reading, want to read, read, abandoned), searched by the server (title, author, tags, thoughts, ISBN), sorted by recently changed, added, title, author, rating or finish date, and narrowed by tag or favourites.
• Plan: the want-to-read queue. Drag a book to reorder; ⋯ on a row plans it for a month or starts it.
• Quotes: every saved line, searchable, each opening its book.
• Authors: photo, years, how many of their books you read and your average rating; an author’s page has the biography (Read more for the long one), your books and their bibliography from Open Library, where Want or Read it puts a book on your shelf. Edit corrects the name (renamed on every book), biography and dates. + (on the Mac Follow an author) opens Find an author: from three letters, Open Library’s authors are listed as you type, with photo, years, number of works and what they are best known for. Tap one to look first: their biography and books from Open Library, with Follow to add them and open their page. The + on a result follows at once; one already on your shelf says On your shelf and opens directly. With no results, Follow “name” by name adds them as typed.
• Series: how far you are in each, and the books of a series with the ones you do not have yet.
• Stats: per year, books and pages against the goal, books per month, the rating spread, top authors and tags, formats, the longest book and the finished list.

Reading settings

Reading settings edits the server’s own settings as the web app’s Settings tabs do: General (title, yearly goal, the page the web app opens on, the catalogues searched, preferred languages, your Google Books key), Thought templates, AI, People (admins add, edit and remove people), Profile, API tokens (make one, shown once with Copy; revoke one), Backup & data (download the database, export JSON or CSV) and Server (version, sizes, time zone). Imports stay in the web app. On the Mac it is a sidebar of pages; on Android the General settings are a page under the Reading tab.

AI is the OpenAI key with which Pocket Bookshelf writes every novel’s characters itself (a short, spoiler-free note on each, in your preferred languages): paste a key, pick a model (Test key checks the key with OpenAI and lists the models the account may use), choose whether it may look books up on the web, and Save AI settings. The key is kept on the server, never shown again and never stored on the phone. Below it, Characters shows who writes them, how many books are waiting, how many were written and failed, and the last error; Write missing now starts a run and the page follows it. Only an admin changes the key.

On Home

The Reading card shows the books read this year against the goal with how many you are reading and the pace; its choices are Currently reading (the book and its page) and Pages this year. The Home header Reading this year says the same in one line.

The quick action Log reading (floating button, Shortcuts, ⌥⇧⌘B on the Mac) picks one of the books you are reading and takes the page, or marks it finished with a date, rating and a few words; with nothing on the go it offers the first books of the plan with Start. The button shows how many books you are reading.

The round button beside the + on the Reading tab opens the screen’s own menu: Add book, Log reading, the library, plan, quotes, authors, series and stats, Reading settings and the web app.

On the Mac

Reading in the sidebar opens a workspace laid out for the desktop: a bar with Now, Library, Plan, Quotes, Authors, Series and Stats. The library is a sortable table or a cover grid with the selected book at the right; a double-click opens its page. Every page behind it is a desktop page, and the Mac widget shows the year against the goal, the pages, the books being read and the next one up.

On Android

The year and the books being read with Log page, up next, recently finished and a quote; the library with status, sort and search; a book’s page with the status actions, rating, favourite, thoughts, quotes and reads; Add a book from the catalogues; quotes, authors with their pages, stats, and the General settings. Reordering the plan, past reads and the bibliography are on the iPhone, the Mac and the web app.

API

The app uses the server’s /api/v1 with the token in an Authorization: Bearer header: GET /dashboard, /books with its filters and sort, /books/{id}, /quotes, /authors, /authors/search, /authors/{id} and /works, /series, /tags, /stats and /search to read; POST /books, PUT /books/{id}, POST /books/{id}/status and /progress, POST /authors, the read and quote endpoints and PUT /planner/order to write. Covers and author photos are fetched with the token in the header. Nothing is kept on the device.

Tips & troubleshooting

• Test connection says 401: the token must be an API token from Settings → API tokens (pb_…), not your password. A deleted token stops at once.
• The year is off by a day around midnight: the server’s TZ decides what today is.
• No covers or author details: they come from Open Library (and Google Books with a key in the web app’s settings); the server needs to reach them.
• A percentage does not show: the book needs a page count. Set Pages under Edit details.