AudioBookShelf

Self-hosted audiobook and podcast server

Overview

AudioBookShelf is a self-hosted audiobook and podcast server. It organizes your audiobooks and podcasts into libraries, keeps your listening position in sync across the web client and the official iOS and Android apps, subscribes to podcast RSS feeds with automatic episode downloads, and matches rich metadata (covers, narrators, series, chapters) from Audible, iTunes, and Google Books. AudioBookShelf ships its own complete multi-user authentication — you create the admin account in your browser on first visit, and manage additional users with per-library permissions inside the app.

QuickBox Pro installs AudioBookShelf per user, built from source: the installer clones the latest upstream release tag, provisions an isolated Node.js 20 runtime for your user, compiles the native SQLite bindings, and generates the web client with your personal URL path baked in. The result is a single systemd service served at https://your-server/username/audiobookshelf/ through a clean nginx reverse proxy — no rewrites, no path tricks. Docker images and the upstream .deb package are upstream alternatives and are not used by the QuickBox package.

Because the install is a real source build, the first install (and every update) takes noticeably longer than a binary application — expect several minutes while dependencies compile and the web client is generated.

Key features

When to use it

Installation

Install from the QuickBox CLI

qb install audiobookshelf -u username

The install clones the latest stable release tag from the upstream repository, builds a per-user Node.js 20 runtime, installs the server dependencies (including a native SQLite module compile), and generates the web client with your per-user URL path baked in.

CLI commands

Install flags

AudioBookShelf tracks stable tagged releases only — there is no --beta flag. Passing --dns without --dns-provider fails fast before any work is done.

Install from the Dashboard

You can also install AudioBookShelf from the QuickBox Pro dashboard. The dashboard installs for the currently signed-in user — there is no user picker on the install dialog. To install for a different user, use the CLI with an explicit -u <other_user>.

To install from the dashboard:

1. Open App Dashboard → Package Management (/dashboard?mode=packages)
2. Find AudioBookShelf under the Media Servers category
3. (Optional) Switch the Custom Domain toggle to Custom and enter a domain — the install issues an SSL certificate and publishes on that subdomain. Choose HTTP-01 (the default) or DNS-01 as the challenge method; DNS-01 also asks for the DNS provider
4. Submit — a live install log streams in the response modal

The dashboard runs the same install pipeline as the CLI.

Access and authentication

URL

AudioBookShelf is published under the per-user subpath of your QuickBox server by default:

https://your-server/username/audiobookshelf/

The web client is generated with this exact path baked in, so the subpath is served natively — including the socket.io WebSocket connection that powers real-time progress updates. You can also click Open on the AudioBookShelf row in the dashboard’s App Dashboard to launch the UI directly. When AudioBookShelf is published on a custom subdomain (see Custom subdomain with SSL below), the Open link points at https://<your-subdomain>/ instead.

First-run setup

AudioBookShelf manages its own accounts. On your first visit, the app shows an initialization screen where you create the admin (root) account in the browser — pick a username and a strong password. QuickBox does not generate, write, or store any AudioBookShelf credentials; there is no default password and no credentials file to retrieve.

1. Open https://your-server/username/audiobookshelf/
2. On the initialization screen, create the root user — choose a username and a strong password
3. Sign in with the account you just created
4. Create your first library: pick Books or Podcasts, then add one or more folders that hold your media
5. AudioBookShelf scans the folders and matches metadata automatically

Additional accounts, per-library permissions, and all other user management live inside the app under Settings → Users. These AudioBookShelf accounts are separate from QuickBox accounts — every QuickBox user who installs AudioBookShelf gets their own private instance with its own users.

Custom subdomain with SSL

By default AudioBookShelf serves under the per-user subpath of your main server address. You can also publish it on a dedicated subdomain (for example audiobookshelf.example.com) with a Let’s Encrypt certificate. There are three ways to set this up: a single-call install (Path A), a post-install retrofit from the CLI (Path B), and the dashboard SSL Control page (Path C).

Path A — Subdomain at install time

The fastest path is to pass -d <domain> to the install. The certificate is issued, the subdomain vhost is written, and the web client is built for the subdomain on the first try — you never see the subpath URL.

Point a DNS record (A or CNAME) for your chosen subdomain at the server, then run:

qb install audiobookshelf -u username -d audiobookshelf.example.com

The install chain-calls Let’s Encrypt under the hood and auto-detects any saved DNS provider credentials, switching to the DNS-01 challenge automatically when it finds them. To force the DNS-01 challenge explicitly:

qb install audiobookshelf -u username -d audiobookshelf.example.com --dns --dns-provider cloudflare

Path B — Retrofit a subdomain to an existing install

If AudioBookShelf is already running on the per-user subpath and you want to move it to a dedicated subdomain, issue the certificate with the AudioBookShelf-specific lecert flag:

qb install lecert --audiobookshelf -d audiobookshelf.example.com -u username

This uses the same shape as every other lecert-managed application (--emby, --jellyfin, --plex, --komga, etc.). QuickBox:

1. Requests a Let’s Encrypt certificate for the supplied domain (HTTP-01 challenge by default)
2. Writes the subdomain vhost into /etc/nginx/sites-enabled/username.audiobookshelf.conf with your assigned port filled in
3. Stops the service, rebuilds the web client for the subdomain root, and starts it again
4. Reloads nginx and registers the certificate for automatic renewal

Wildcard or DNS challenge: add --dns --dns-provider cloudflare (or another supported provider). See the Let’s Encrypt application reference for the full list of supported DNS providers.

Testing without rate-limit exposure: add --staging to issue against the Let’s Encrypt staging CA, or --dry-run to validate the ACME challenge without writing any certificate or nginx changes. Combine the two to fully exercise the flow with zero side effects.

Removing the subdomain: qb remove lecert --audiobookshelf -d <domain> -u username deletes the subdomain vhost. If AudioBookShelf is still installed, QuickBox rebuilds the web client for the per-user subpath and restores the subpath nginx config, so subpath access continues to work.

Path C — Dashboard SSL Control

The dashboard’s SSL Control page at System → SSL Control (/system/ssl) exposes the same flow. The form fields, in order, are:

1. Target — pick AudioBookShelf from the dropdown
2. Domain — your chosen subdomain (for example audiobookshelf.example.com)
3. Challenge Method — HTTP-01 (the default) or DNS-01
4. DNS Provider — only shown when DNS-01 is selected
5. DNS credentials — only shown when DNS-01 is selected and no credentials are saved for that provider yet
6. Username — the QuickBox user that owns the install

The SSL Control page runs the same qb install lecert --audiobookshelf pipeline under the hood.

Configuration and files

AudioBookShelf keeps the application install and your library state in two separate trees. Everything that matters to you — the database, covers, cached metadata, and logs — lives under /home/username/.config/audiobookshelf/. The install tree under /opt/username/audiobookshelf/ is disposable and is rebuilt on every update.

AudioBookShelf has no text settings file — all in-app settings live in the SQLite database and are managed through the web UI. The only file QuickBox manages is env.conf, which carries the runtime environment the systemd unit loads (port, bind address, data paths, and serving base). It is kept in sync automatically by installs, updates, and SSL flips.

Service management

AudioBookShelf runs as a single per-user systemd unit:

# Check status
sudo systemctl status audiobookshelf@username
 
# Restart / stop / start
sudo systemctl restart audiobookshelf@username
sudo systemctl stop audiobookshelf@username
sudo systemctl start audiobookshelf@username
 
# Follow the service log
sudo journalctl -u audiobookshelf@username -f

The service starts automatically at boot. The application’s SQLite database migrates itself on start after an update — no manual migration step is ever needed. In-app daily logs are also written to /home/username/.config/audiobookshelf/config/logs/, but the systemd journal carries the full output and is the first place to look.

Common tasks

Add an audiobook library

1. Sign in and click the library switcher in the top bar, then Add Library (or go to Settings → Libraries)
2. Choose Books as the media type and add the folder(s) that hold your audiobooks
3. Save — AudioBookShelf scans the folders and matches covers, series, narrators, and chapters automatically

Subscribe to a podcast with auto-download

1. Create a library with the Podcasts media type pointed at a folder for episode storage
2. In the podcast library, click Add → Podcast and search by name or paste an RSS feed URL
3. On the podcast’s page, enable Auto Download Episodes and set the check interval and retention to taste

Update AudioBookShelf

qb update audiobookshelf -u username

The update backs up your database, fetches the newest stable release tag, rebuilds the server dependencies and the web client with the same serving base the install is using, and restarts the service. Your library, users, and progress are untouched — all state lives outside the install tree. Like the install, the update is a source build and takes a few minutes.

Check the logs

# Service output (the canonical log stream)
sudo journalctl -u audiobookshelf@username -f
 
# In-app daily logs
ls /home/username/.config/audiobookshelf/config/logs/
 
# QuickBox install/update build log
tail -f /opt/quickbox/logs/audiobookshelf.log

Back up your library state

Everything worth keeping lives in one tree. Back it up while the service is stopped for a clean snapshot:

sudo systemctl stop audiobookshelf@username
tar -czf ~/audiobookshelf-backup.tar.gz -C /home/username/.config audiobookshelf
sudo systemctl start audiobookshelf@username

QuickBox also snapshots absdatabase.sqlite into /home/username/.QuickBox/software/audiobookshelf/ during installs and updates.

Remove AudioBookShelf

qb remove audiobookshelf -u username

Troubleshooting

Best practices

FAQ

Resources