From 5ac56de09d99d28ac67a7d43b49d998b00f2f2f2 Mon Sep 17 00:00:00 2001 From: Timothy Allen Date: Sat, 3 Oct 2026 11:13:51 +0200 Subject: [PATCH] Document the OPDS catalog Cover the catalog, its logins in each mode, and the paths that the proxy must let through. --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d101336..5e0a721 100644 --- a/README.md +++ b/README.md @@ -135,6 +135,17 @@ Each build without a saved CWA book ID then puts a plain ePub in that folder, in or publish the port of Bindery only on the host, as `127.0.0.1:8085:8085` in the Compose file. `TRUST_PROXY` does not change this check. It is only for the lockouts. + #### Paths without the proxy login + + An OPDS reader cannot use the login page of the proxy, such as OIDC. Set the proxy to skip its login + for `/opds` and each path below it. If you set `URL_BASE`, put it before the path. As a regular + expression, this is `^/opds([/?].*)?$`. In Authelia, add an `access_control` rule with + `policy: bypass` and this expression in `resources`. In Authentik, add it to "Unauthenticated + Paths" of the proxy provider. + + On these paths, Bindery checks the OPDS login itself. See "OPDS catalog". Keep the proxy login on + `/api` and on all other paths. The health check at `/api/health` needs no login. + **If the login settings are incomplete or wrong, Bindery refuses every request**, also with the API key, and shows the reason. @@ -298,6 +309,39 @@ The answer lists the queued jobs and the unsupported URLs: `{"jobs": [...], "err If Bindery runs under `URL_BASE`, put the prefix before `/api`. +### OPDS catalog + +OPDS lets a reader app browse and download books from Bindery. An admin turns it on with "Enable OPDS" +under Settings > Book Downloads. The catalog URL is `http://localhost:8085/opds`, with your server +address in place of `localhost`. If Bindery runs under `URL_BASE`, put it before `/opds`. + +The catalog has three lists, with 50 books per page: + +- By Title, in title order without a leading "The", "A" or "An". +- By Author, in surname order. Each author leads to their books. A book shows under each of its authors. +- By Last Changed, with the newest change first. + +A book appears when it has a stored, included chapter. It shows its authors, series, description, tags, +language and cover, with your kept values in place of the site values. A reader can search by title, +author, series and tag. A download uses the stored chapters, the current ePub rules and the download +template for the file name. + +`AUTH_METHOD` sets how a reader logs in: + +- `none`: The reader needs no login. +- `local`: The reader sends your Bindery user name and password with HTTP Basic authentication. + A browser with a Bindery session works too. +- `cwa`: The reader sends your CWA user name and password with HTTP Basic authentication. + A browser with a Bindery session works too. +- `proxy`: Each user sets an OPDS password under Settings > Book Downloads. Settings shows the user + name for the reader, which is the name in `PROXY_AUTH_USER_HEADER`. The reader sends that name and + password with HTTP Basic authentication. The password has 8 to 256 characters, and Bindery keeps a + hash of it. Set the proxy to skip its login for the catalog. See "Paths without the proxy login". + +Bindery keeps a good login for five minutes. Wrong passwords count toward the lockouts in +"Lockouts and sessions". With `TRUST_PROXY=true`, each reader has its own lockout. +Use HTTPS outside a trusted local network, because HTTP Basic sends the password with each request. + ### FanFicFare settings On first start, Bindery copies `data/personal.ini` to `/config/personal.ini`. It uses the format of @@ -447,9 +491,9 @@ downloaded before. ## File names of downloaded books -"Download ePub" on a story page sends the book to your browser with a file name. A template gives -the name. The default template is `{title_sort} - {authors}`. For "The Book" by Ann Writer, it gives -`Book, The - Ann Writer.epub`. That is the name that Calibre's default template gives. +"Download ePub" on a story page and each download from the OPDS catalog send the book with a file +name. A template gives the name. The default template is `{title_sort} - {authors}`. For "The Book" +by Ann Writer, it gives `Book, The - Ann Writer.epub`. That is the name that Calibre's default template gives. An admin can change the template under "Book Downloads" in Settings. To go back to the default, clear the field and save. The template follows