Deploy Audiobookshelf | (Just Updated) Audiobook and Podcast Server, Root Login Generated, Data Survives Redeploys
Audiobookshelf audiobook and podcast server, admin login, data kept
audiobookshelf
Just deployed
/data
Deploy and Host Audiobookshelf on Railway
Built for an LLM agent to deploy and use. The deploy form has no fields to fill: the root login is generated, the two libraries are created, data sits on a volume, and the server is never reachable before its root user exists. Audiobookshelf is the open-source audiobook and podcast server: stream and download audiobooks, subscribe to podcasts, track progress across devices, and use the REST API or the Android and iOS apps.
About Hosting Audiobookshelf
This template runs one service, audiobookshelf (the upstream image, with a volume at /data holding the database, metadata cache and both library folders), so books, podcasts, users, listening progress and settings survive redeploys.
Upstream starts open, this template does not. A fresh Audiobookshelf answers POST /init from anyone until a root user exists, so whoever reaches a new domain first becomes root. The wrapper starts the server on 127.0.0.1 only, creates the root user from ADMIN_PASSWORD, creates an Audiobooks library (/data/audiobooks) and a Podcasts library (/data/podcasts), then starts the public listener on Railway's PORT. The container refuses to start if ADMIN_PASSWORD is empty, shorter than 12 characters, or the volume already holds a root user with another password. Railway allows one volume per service, so config, metadata and library folders all live under /data.
Using it. Open https://YOUR_DOMAIN, sign in as root with ADMIN_PASSWORD, then upload audiobooks from the web UI into the Audiobooks library or add podcasts by RSS feed. Add listener accounts under Settings, Users. Mobile apps connect to the same URL with the same login. Upstream is Audiobookshelf 2.37.2.
Agent contract
- Public URL:
https://RAILWAY_PUBLIC_DOMAIN(the generated domain of theaudiobookshelfservice) - Private URL:
http://audiobookshelf.railway.internal:8080 - Credentials: the variable
ADMIN_PASSWORDon theaudiobookshelfservice; the user name isroot - Auth:
POST /loginwith JSON{"username":"root","password":"$ADMIN_PASSWORD"}returns the user with atoken; send it asAuthorization: Bearer TOKENon every/apicall. A wrong password answers401;/apiwithout a token or with a bad one answers401. Registration is closed:POST /api/userswithout a token answers401, and a secondPOST /initis refused (500, no second root is created). - Health:
GET /healthcheckreturns 200
#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, ADMIN_PASSWORD (variables of the audiobookshelf service); also curl, sed. Creates and deletes one throwaway library.
R="https://$RAILWAY_PUBLIC_DOMAIN"; J="Content-Type: application/json"
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/healthcheck")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/healthcheck"
TOKEN=$(curl -s -H "$J" -d "{\"username\":\"root\",\"password\":\"$ADMIN_PASSWORD\"}" "$R/login" | sed -n 's/.*"token":"\([^"]*\)".*/\1/p' | head -1)
if [ -n "$TOKEN" ]; then echo "login: token received"; else echo "login: FAILED"; fi
curl -s -o /dev/null -w "read with key: %{http_code}\n" -H "Authorization: Bearer $TOKEN" "$R/api/libraries"
# write with the key: create a uniquely named library, read it back, delete it
S="railway-check-$(date +%s)"
ID=$(curl -s -H "Authorization: Bearer $TOKEN" -H "$J" -d "{\"name\":\"$S\",\"mediaType\":\"book\",\"folders\":[{\"fullPath\":\"/data/$S\"}]}" "$R/api/libraries" | sed -n 's/^{"id":"\([^"]*\)".*/\1/p')
if [ -n "$ID" ]; then echo "write library: created"; else echo "write library: FAILED"; fi
curl -s -H "Authorization: Bearer $TOKEN" "$R/api/libraries" | grep -o "$S" | head -1 | sed 's/^/library read back: /'
curl -s -o /dev/null -w "delete library: %{http_code}\n" -X DELETE -H "Authorization: Bearer $TOKEN" "$R/api/libraries/$ID"
# refusals: wrong key, no key, registration, a second root
curl -s -o /dev/null -w "login wrong key: %{http_code}\n" -H "$J" -d '{"username":"root","password":"not-the-secret-0000"}' "$R/login"
curl -s -o /dev/null -w "read wrong key: %{http_code}\n" -H "Authorization: Bearer not-a-token" "$R/api/libraries"
curl -s -o /dev/null -w "read without key: %{http_code}\n" "$R/api/libraries"
curl -s -o /dev/null -w "write wrong key: %{http_code}\n" -H "Authorization: Bearer not-a-token" -H "$J" -d '{"name":"x"}' "$R/api/libraries"
curl -s -o /dev/null -w "write without key: %{http_code}\n" -H "$J" -d '{"name":"x"}' "$R/api/libraries"
curl -s -o /dev/null -w "public signup: %{http_code}\n" -H "$J" -d '{"username":"visitor","password":"visitor-pass-0000","type":"admin"}' "$R/api/users"
curl -s -o /dev/null -w "second root via init: %{http_code}\n" -H "$J" -d '{"newRoot":{"username":"visitor","password":"visitor-pass-0000"}}' "$R/init"
Expected output against a fresh deploy (measured on a Railway deploy of this template):
health: 200
login: token received
read with key: 200
write library: created
library read back: railway-check-TIMESTAMP
delete library: 200
login wrong key: 401
read wrong key: 401
read without key: 401
write wrong key: 401
write without key: 401
public signup: 401
second root via init: 500
The refusals are the contract: write wrong key: 401, write without key: 401, read without key: 401, public signup: 401 and login wrong key: 401. The last line shows a second root cannot be created through /init.
Why Deploy Audiobookshelf 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 Audiobookshelf 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 with the key, and the refusal of a wrong password, a missing key, a registration and a second root.
- No open window - the root user exists before the public listener starts, so nobody can claim a new server.
- Data survives redeploys - database, metadata and both libraries sit on one volume.
- Pinned - the upstream image is pinned by digest and the wrapper by tag and digest.
- Your audio stays yours - a private library on a domain you control, with the official apps.
Common Use Cases
- Personal audiobook server - stream a private audiobook collection from any browser or phone.
- Podcast manager - subscribe to RSS feeds and keep episodes and listening progress in one place.
- Family library - one server, a login per listener, progress tracked per person.
- Agent-driven media tooling - give an agent a token to create libraries, scan folders and read the REST API.
Dependencies for Audiobookshelf Hosting
- The audiobookshelf service with its volume, created by the template. A custom domain is optional.
Deployment Dependencies
Template Content
audiobookshelf
ghcr.io/bon5co/audiobookshelf-railway:2.37.2