How to Deploy Audiobookshelf on a VPS

#Install Audiobookshelf (Docker Compose)

Upstream's compose file maps four folders, and they have distinct jobs:

• /config — the SQLite database: users, libraries, listening progress, settings. Upstream requires it to be on the same machine as the server; don't put it on a network share.
• /metadata — covers, cache, streams, downloads, logs, and the built-in backups.
• /audiobooks and /podcasts — your media. Upstream asks that these be separate directories, not nested inside each other or inside config.

Create the project directory and the folders:

copymkdir -p ~/audiobookshelf && cd ~/audiobookshelf
mkdir -p config metadata audiobooks podcasts

Write the compose file. It is upstream's example with the port bound to loopback so only the reverse proxy can reach it:

copycd ~/audiobookshelf
cat > docker-compose.yml <<'YAML'
services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    container_name: audiobookshelf
    ports:
      # Loopback only — Caddy is the sole route in from outside.
      - "127.0.0.1:13378:80"
    volumes:
      - ./audiobooks:/audiobooks
      - ./podcasts:/podcasts
      - ./metadata:/metadata
      - ./config:/config
    environment:
      - TZ=Etc/UTC
    restart: unless-stopped
YAML
docker compose up -d

The container listens on port 80 internally; 13378 is only the host-side port, and upstream's advice is to change only that side if you need a different one. Set TZ to your own timezone so scheduled tasks (podcast checks, backups) run when you expect.

Check it answers:

copycd ~/audiobookshelf
for i in $(seq 1 30); do curl -fsS -o /dev/null http://127.0.0.1:13378/ && break; sleep 2; done
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:13378/
docker compose ps

#HTTPS + domain

Point an A record for books.example.com at the server's public IP and wait for it to resolve. Then terminate TLS with Caddy — the full setup is in Automatic HTTPS with Caddy:

books.example.com {
    reverse_proxy 127.0.0.1:13378
}

Upstream is explicit that Audiobookshelf requires a WebSocket connection through the proxy. Caddy's reverse_proxy forwards WebSocket upgrades on its own, so the block above is complete. If you use nginx instead, you must add the Upgrade and Connection headers yourself — a missing upgrade is the usual reason the web player works but progress doesn't sync.

Serving it under a path instead of a subdomain is supported, but only at /audiobookshelf — upstream doesn't allow a different subfolder name. A dedicated subdomain is simpler.

If Caddy runs as a container, 127.0.0.1 is the proxy's own loopback; put both services in one compose file and use reverse_proxy audiobookshelf:80.

#First run

Open https://books.example.com. On first launch Audiobookshelf asks you to create the root user — the administrator account. Do it immediately; until then, whoever loads the page first sets that password.

Then create a library: choose Books or Podcasts and add the folder path as the container sees it — /audiobooks or /podcasts, not the host path. Audiobookshelf reads a folder per book, so Author/Book Title/files is the layout that scans cleanly.

To get files onto the server, either upload through the web UI or copy them from your computer with rsync into ~/audiobookshelf/audiobooks, then run a library scan.

#Securing it

• Create a user per listener. Progress is tracked per user, so a shared login mixes everyone's position in the same book.
• Keep the root account for administration and use a normal account in the apps.
• Keep the port on loopback. The compose file never publishes 13378 to the internet; everything arrives over HTTPS.

#Backups

The database is in ./config; covers and the built-in backups are in ./metadata. The media folders you should back up the way you back up any other files. For a consistent copy of the database, stop the container briefly:

copycd ~/audiobookshelf
docker compose stop
tar czf audiobookshelf-$(date +%F).tar.gz config metadata docker-compose.yml
docker compose start

Audiobookshelf can also make scheduled backups itself (Settings → Backups); they are written to metadata/backups. Those are useful for rolling back a bad upgrade, but they live on the same disk — copy archives off the box. Upstream's restore procedure for current versions is: stop the server, unzip the backup from metadata/backups, copy its audiobookshelf.sqlite over config/audiobookshelf.sqlite, restore the authors and items metadata folders, and start the server again.

#Upgrades

Upstream's upgrade for a compose install:

copycd ~/audiobookshelf
docker compose pull
docker compose down
docker compose up --detach

The latest tag moves to each new release. To stay on a specific version, replace latest with that version number. Back up config and metadata first: database migrations run at startup.

#Troubleshooting

The web player works, but progress doesn't sync and the apps can't connect. The WebSocket isn't getting through the proxy. With Caddy that usually means the request isn't reaching Caddy at all (check DNS); with nginx it means the upgrade headers are missing.

A library scan finds nothing. The library points at a host path. Inside the container the folders are /audiobooks and /podcasts. Also check that the files are readable:

copycd ~/audiobookshelf
ls -la audiobooks podcasts
docker compose logs --tail 50 audiobookshelf

The server won't start after an upgrade, and the log mentions the database. config is on a network filesystem, or a migration failed. Move config to local disk; if a migration failed, restore the pre-upgrade backup.

Books split into many single-file entries. The folder layout is flat. Put each book in its own folder, then rescan.

#Verification + next steps

You're done when you can load https://books.example.com over a valid certificate, sign in as a non-root user, play a chapter in the browser, then open the same book in the mobile app and find it at the same position.

From there, put the rest of your media library next to it: Jellyfin for films and TV, and Navidrome for music.