Get started

#Configuration

Shelf works with no settings at all. Everything here is optional, for when you want email, a reverse proxy, different folders, or to turn something off.

#How to set things

Settings can come from environment variables, from appsettings.json beside the app, or from the command line. Names are written here as Section:Name; as an environment variable, use two underscores instead of the colon.

#Accounts

#Cloudflare Turnstile

Turnstile asks a visitor's browser to show it is one a person is using before signing in, signing up, or asking for a password reset goes through, usually without them doing anything. It is off until both keys are set. Make a widget in the Cloudflare dashboard, under Turnstile, for the host names the shelf is reached at, and copy its keys here.

With Turnstile on, a form whose check fails, or cannot reach Cloudflare, is refused, so a shelf that cannot reach challenges.cloudflare.com cannot be signed in to with a password; passkeys and single sign-on still work. Scripts signing in with a password stop working too: give them an API token. Server health says whether Turnstile is on, or set up only partly, and why the last form was refused, until a check passes: most often a token made on a host that isn't in Turnstile:Hostnames (or, without it, isn't the host of Email:PublicAddress), such as an address inside your network or one with www.. The widget shows its tick either way, since it has no way of knowing what the shelf expects.

#Single sign-on

Off unless Oidc:Authority and Oidc:ClientId are set. See Single sign-on.

#Upload limits

The largest file Shelf takes, in megabytes. A larger one is refused with a note saying how large it may be.

In Docker, as environment variables:

environment:
  - Uploads__MaxEbookMegabytes=500
  - Uploads__MaxAudioMegabytes=4096

A reverse proxy in front of Shelf has a limit of its own, which refuses a large file before Shelf sees it; raise it to match (for nginx, client_max_body_size 4g;). See HTTPS and a reverse proxy.

#Where things are kept

#PostgreSQL

Shelf keeps its database in SQLite, one file beside everything else, which suits a shelf of any size a household has. To keep it in PostgreSQL instead (13 or newer), say for a server that runs one for everything:

The keys, backups, and files stay in the folders above, so /data is still wanted in Docker. A few things differ:

• Search finds a phrase anywhere, ignoring case, but doesn't rank the places it finds or overlook accents, as SQLite's full-text index does.
• Snapshots hold pg_dump's copy of the database when pg_dump is on the server (or at Database__PgDump), and otherwise the library as JSON, which Restore takes. Back the database up with PostgreSQL's own tools as well.

Moving an existing shelf. With PostgreSQL set up and empty, run Shelf once with the move command; it copies every reader, book, note, and setting from the SQLite file, ids and all, then stops:

docker run --rm -v shelf-data:/data -e Database__Provider=Postgres -e ConnectionStrings__Postgres="Host=db;Database=shelf;Username=shelf;Password=…" ghcr.io/doodersrage/shelf:latest --move-to-postgres true

Then start Shelf with the same two settings. The SQLite file stays as it was, to go back to.

#Running behind a proxy

#Email

Without a mail server, an admin resets forgotten passwords and notifications come only by the other ways a reader sets up. Set at least Email:Host and Email:From, and Email:PublicAddress for password resets; then Forgot the password? on the sign-in page sends a reader a link, to the email address on their account.

#Nightly backups

#Trash, history, and file checks

#Calibre

#Import folder

#Scanned PDFs (OCR)

#Books from elsewhere

#Recaps

The text of the chapters a reader has read is sent to Anthropic to be summed up; see Previously in this book.

| Ask:UseModel | true | With a key set, lets Ask your shelf send the question alone to the model to understand it. false keeps questions on the server, read by simple rules. |

#Money and updates

#Read-along

#Linked shelves

Linking needs Email:PublicAddress, as the other shelf calls this one at that address. See Linked shelves.

#Notifications and webhooks

Links in ntfy and Gotify notifications need the shelf's own address, Email:PublicAddress; without it, they come without a link.

#Logging

Shelf logs with ASP.NET Core's usual settings, such as Logging:LogLevel:Default. In Docker, docker logs shelf shows them.

#Source code link