Audiobookshelf

The stack

Generated output

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:2.35.1@sha256:1eef6716183c52abafe5405e7d6be8390248ecd59c7488c44af871757ac8fc4d
    restart: unless-stopped
    environment:
      PORT: "13378"
      TZ: ${TZ}
    volumes:
      - audiobookshelf-config:/config
      - audiobookshelf-metadata:/metadata
      - ${AUDIOBOOKS_PATH}:/audiobooks
      - ${PODCASTS_PATH}:/podcasts
volumes:
  audiobookshelf-config: {}
  audiobookshelf-metadata: {}

# Caddyfile for Audiobookshelf
# Replace audiobooks.example.com with your real domain. Caddy issues TLS automatically.

audiobooks.example.com {
	encode zstd gzip
	reverse_proxy audiobookshelf:13378
}

# Traefik labels for Audiobookshelf
# Merge into the audiobookshelf service in docker-compose.yml.
# Assumes an external Traefik network named "proxy" and a
# certresolver named "letsencrypt". Replace audiobooks.example.com.

services:
  audiobookshelf:
    labels:
      traefik.enable: "true"
      traefik.http.routers.audiobookshelf.rule: Host(`audiobooks.example.com`)
      traefik.http.routers.audiobookshelf.entrypoints: websecure
      traefik.http.routers.audiobookshelf.tls: "true"
      traefik.http.routers.audiobookshelf.tls.certresolver: letsencrypt
      traefik.http.services.audiobookshelf.loadbalancer.server.port: "13378"
    networks:
      - proxy
      - default
networks:
  proxy:
    external: true

Replace audiobooks.example.com with your domain. Generate secrets below.

Environment

.env with generated secrets

# Host directory that holds your audiobook files. Mounted read-write at /audiobooks and scanned as a Books library.
AUDIOBOOKS_PATH=./audiobooks

# Host directory for podcasts. Mounted at /podcasts and scanned as a Podcasts library; auto-downloaded episodes land here.
PODCASTS_PATH=./podcasts

# Timezone for scheduled podcast downloads, backups, and log timestamps (IANA tz name).
TZ=UTC

Requirements

Before you start

• 1 GB RAM is comfortable. Audiobookshelf itself is light, but scanning large libraries and embedding metadata is CPU- and I/O-heavy.
• Docker 24+ and Docker Compose v2.
• Storage for your media, plus a persistent disk for the config and metadata volumes — the config volume is your user database and listening progress.
• Your audiobook and podcast files in host directories that are readable by the container. Audiobookshelf scans the paths mounted at /audiobooks and /podcasts.

Deploy

How to deploy

1. Point `AUDIOBOOKS_PATH` and `PODCASTS_PATH` in `.env` at the host folders that already hold your media (they default to `./audiobooks` and `./podcasts`).
2. Optionally set `TZ` so scheduled podcast downloads and backups run on your local clock.
3. Start the stack: `docker compose up -d`.
4. Open `https://audiobooks.example.com` and create the root (admin) account in the first-run setup — there is no default password; the first account you make is the admin.
5. Add a library: choose the Books type and point it at `/audiobooks`, then add a second Podcasts library pointed at `/podcasts`. Audiobookshelf scans and matches metadata.
6. Install the Audiobookshelf app (iOS or Android), set the server address to `https://audiobooks.example.com`, and log in.

Errors

Common errors & fixes

Limitations

Honest limitations

• No server-side transcoding. Unlike Plex or Jellyfin, Audiobookshelf streams the original files and relies on the client to decode them — fine for common formats (MP3, M4B, AAC, FLAC, Opus), but unusual codecs depend on what the player supports.
• The initial scan of a large collection can take a long time and is I/O-intensive, especially while matching metadata and reading chapters; expect the first index to run for a while before everything appears.
• Ebook support is secondary to audio. There is an in-browser EPUB/PDF reader, but this is not a Calibre-class ebook manager.
• Single instance only — no built-in clustering or high availability. Back up the config and metadata volumes to protect against host loss.

FAQ

Frequently asked

Related

Related stacks