Deploy Calibre-Web | (Just Updated) Ebook Server and OPDS Library, Default Login Replaced, Data Survives Redeploys
Calibre-Web ebook server and OPDS library, admin login, data kept
calibre-web
Just deployed
/config
Deploy and Host Calibre-Web on Railway
Built for an LLM agent to deploy and use. The deploy form has no fields to fill: the library is created on a volume, the admin password is generated, public registration and anonymous browsing are off, and the server binds Railway's port. Calibre-Web is the open-source web reader and OPDS server for a Calibre ebook library: browse, search, read in the browser, download, send to an e-reader and sync to Kobo or any OPDS app.
About Hosting Calibre-Web
This template runs one service, calibre-web (the LinuxServer.io image, with a volume at /config holding the settings database and an empty Calibre library at /config/library), so books, shelves, users and settings survive redeploys.
Upstream starts open, this template does not. A fresh Calibre-Web signs in as admin with a published default password and opens on a setup screen that asks for a library path. The wrapper creates an empty library (upstream's own metadata.db), points the app at it, replaces the default password with ADMIN_PASSWORD on every start, and keeps public registration and anonymous browsing off. The container refuses to start if ADMIN_PASSWORD is empty or shorter than 12 characters. It also writes Railway's injected PORT into the app's port setting, which upstream otherwise fixes at 8083, so the healthcheck and the public domain reach the same listener. Railway allows one volume per service, so the library sits under the config volume instead of a separate /books mount.
Using it. Open https://YOUR_DOMAIN, sign in as admin with ADMIN_PASSWORD, then upload books from the web UI (uploads are enabled for admin) or copy an existing Calibre library over the one in /config/library. Add reader accounts under Admin, Users. The OPDS feed is at /opds/ with the same login. Ebook conversion needs Calibre's binaries, which this image leaves out; reading, downloading, shelves, metadata editing and Kobo sync work without them. Upstream is Calibre-Web 0.6.27 on LinuxServer.io build 410.
Agent contract
- Public URL:
https://RAILWAY_PUBLIC_DOMAIN(the generated domain of thecalibre-webservice) - Private URL:
http://calibre-web.railway.internal:8080 - Credentials: the variable
ADMIN_PASSWORDon thecalibre-webservice; the user name isadmin - Auth:
GET /loginreturns a form with acsrf_token;POST /loginwithcsrf_token,username=adminandpassword=$ADMIN_PASSWORDanswers302and sets the session cookie. A wrong password answers401. Browser and API calls then send that cookie. The OPDS feed/opds/takes HTTP basic auth with the same login and answers401without it. A write without a session answers302to/login, and a POST with no CSRF token answers400. Registration is off:POST /registeranswers404. Logins are throttled per user name (3 a minute); a throttled login answers401. - Health:
GET /loginreturns 200
#!/bin/sh
# Login attempts are throttled per user name (3 a minute, a throttled attempt answers 401): run this once a minute at most.
# needs: RAILWAY_PUBLIC_DOMAIN, ADMIN_PASSWORD (variables of the calibre-web service); also curl, sed. Writes one throwaway shelf.
R="https://$RAILWAY_PUBLIC_DOMAIN"; J=$(mktemp); K=$(mktemp)
csrf() { sed -n 's/.*name="csrf_token" value="\([^"]*\)".*/\1/p' | head -1; }
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/login")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/login"
T=$(curl -s -c "$J" -b "$J" "$R/login" | csrf)
curl -s -c "$J" -b "$J" -o /dev/null -w "login: %{http_code}\n" --data-urlencode "csrf_token=$T" --data-urlencode "username=admin" --data-urlencode "password=$ADMIN_PASSWORD" -d "next=" "$R/login"
curl -s -b "$J" -o /dev/null -w "session read: %{http_code}\n" "$R/"
curl -s -o /dev/null -w "opds basic auth: %{http_code}\n" -u "admin:$ADMIN_PASSWORD" "$R/opds/"
# write with the session: create a uniquely named shelf and read it back
S="railway-check-$(date +%s)"
T=$(curl -s -c "$J" -b "$J" "$R/shelf/create" | csrf)
curl -s -c "$J" -b "$J" -o /dev/null -w "write shelf: %{http_code}\n" --data-urlencode "csrf_token=$T" -d "title=$S" "$R/shelf/create"
curl -s -b "$J" "$R/" | grep -o "$S" | head -1 | sed 's/^/shelf read back: /'
# refusals: wrong key, no session, no token, registration, upstream default login (each failed POST resets the cookie jar's token, so fetch a fresh one every time)
tok() { curl -s -c "$K" -b "$K" "$R/login" | csrf; }
curl -s -c "$K" -b "$K" -o /dev/null -w "write wrong key: %{http_code}\n" -d "csrf_token=$(tok)" -d "username=admin" -d "password=not-the-secret-0000" -d "next=" "$R/login"
curl -s -c "$K" -b "$K" -o /dev/null -w "write without session: %{http_code}\n" -d "csrf_token=$(tok)" -d "title=no-session" "$R/shelf/create"
curl -s -o /dev/null -w "write without key: %{http_code}\n" -d "title=no-key" "$R/shelf/create"
curl -s -o /dev/null -w "read without session: %{http_code}\n" "$R/"
curl -s -o /dev/null -w "opds wrong key: %{http_code}\n" -u "admin:not-the-secret-0000" "$R/opds/"
curl -s -c "$K" -b "$K" -o /dev/null -w "public signup: %{http_code}\n" -d "csrf_token=$(tok)" -d "name=visitor" -d "email=visitor@example.com" "$R/register"
curl -s -c "$K" -b "$K" -o /dev/null -w "upstream default login: %{http_code}\n" -d "csrf_token=$(tok)" -d "username=admin" -d "password=$(printf 'admin%s' 123)" -d "next=" "$R/login"
rm -f "$J" "$K"
Expected output against a fresh deploy (measured on a Railway deploy of this template):
health: 200
login: 302
session read: 200
opds basic auth: 200
write shelf: 302
shelf read back: railway-check-TIMESTAMP
write wrong key: 401
write without session: 302
write without key: 400
read without session: 302
opds wrong key: 401
public signup: 404
upstream default login: 401
The refusals are the contract: write wrong key: 401, write without session: 302 (to /login), write without key: 400 (no CSRF token), public signup: 404 and upstream default login: 401. Logins are throttled per user name (3 a minute) and a throttled login also answers 401, so run the script at most once a minute.
Why Deploy Calibre-Web on Railway?
Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.
By deploying Calibre-Web on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.
- Agent-ready - no deployer fields, a contract block and one script that proves login, a write, and the refusal of a wrong password, a write with no session, a registration and the upstream default login.
- Default login replaced - the published
adminpassword is overwritten at every boot by a generated one. - Data survives redeploys - the settings database and the library sit on one volume.
- Pinned - the LinuxServer.io image is pinned by digest and the wrapper by tag and digest.
- Your books stay yours - a private library on a domain you control, with an OPDS feed for any reader app.
Common Use Cases
- Personal ebook server - keep a Calibre library online and read it from any browser.
- OPDS catalog for e-readers - point KOReader, Moon+ Reader, Marvin or a Kobo at
/opds/. - Family or book-club library - one library, a login per reader, shelves per person.
- Agent-driven library tooling - give an agent a session to upload books, edit metadata and manage shelves.
Dependencies for Calibre-Web Hosting
- The calibre-web service with its volume, created by the template. A custom domain is optional.
Deployment Dependencies
Template Content
calibre-web
ghcr.io/bon5co/calibre-web-railway:0.6.27