Audiobookshelf Docker Guide: Host Your Own Audiobook and Podcast Server

1. Directory Structure and Pre-flight Setup

For a resilient Audiobookshelf (ABS) deployment, organize your host directory structure to isolate persistent configuration, metadata, and media directories. This separation ensures straightforward backups and prevents permissions conflicts.

Create the required directories on your VPS:

mkdir -p ~/audiobookshelf/{config,metadata,media/{audiobooks,podcasts,books}}

Directory Roles:

• config/: Stores database, user settings, and site configuration.
• metadata/: Holds scraped metadata, author images, and cover art. Keep this separate from config as it can grow extremely large.
• media/: Organized by library type. Audiobookshelf requires separate directories for different library types (e.g. Audiobooks and Podcasts should not be mixed).

2. Docker Compose Configuration

The following docker-compose.yml configures Audiobookshelf alongside a PostgreSQL database (optional, but recommended for large instances) or uses the embedded SQLite database. Audiobookshelf's default embedded SQLite is highly optimized, so this stack focuses on the standard container configuration with optimal environment variables.

Create ~/audiobookshelf/docker-compose.yml:

version: "3.8"

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    container_name: audiobookshelf
    restart: unless-stopped
    ports:
      - "13378:80"
    environment:
      - TZ=Etc/UTC
      - AUDIOBOOKSHELF_UID=1000
      - AUDIOBOOKSHELF_GID=1000
    volumes:
      - ./config:/config
      - ./metadata:/metadata
      - ./media/audiobooks:/audiobooks
      - ./media/podcasts:/podcasts
      - ./media/books:/books

Environment Variables & Permissions Configuration

• AUDIOBOOKSHELF_UID and AUDIOBOOKSHELF_GID: Crucial for avoiding file permission issues when accessing media files stored on the host. Match these to the UID/GID of the user running Docker on your host (find yours by running the id command).
• TZ: Sets the system timezone for scheduling podcast updates and library scans.

3. Reverse Proxy & SSL Configuration

To securely access Audiobookshelf externally and enable progress syncing for mobile apps, you must configure a reverse proxy with SSL/TLS.

Caddy Server Configuration

If you use Caddy, add the following block to your Caddyfile:

abs.yourdomain.com {
    reverse_proxy localhost:13378
}

Nginx Configuration

If you use Nginx, create a server block configured for WebSockets, which Audiobookshelf relies on for real-time progress syncing:

server {
    listen 80;
    server_name abs.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name abs.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/abs.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/abs.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:13378;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

Run docker compose up -d within ~/audiobookshelf to initialize the container.

4. Media Library Organization and Mounting Rules

Audiobookshelf is highly sensitive to folder structures. Incorrect nesting will result in failed matching and split books.

Audiobook Structure Requirements

Each audiobook must reside in its own folder, nested under the author's folder:

media/audiobooks/
└── Brandon Sanderson/
    └── Mistborn - The Final Empire/
        ├── 01 - Prologue.mp3
        ├── 02 - Chapter 1.mp3
        └── cover.jpg

• Single-file Audiobooks: .m4b or .mka files should still follow the Author/Book Title/book.m4b convention.
• Multi-file Audiobooks: Tag files sequentially (01 - Title.mp3, 02 - Title.mp3) to ensure correct playback order.

5. Metadata Scraping and Scanner Settings

Once the container is online, access the web UI at http://<your-vps-ip>:13378 to configure metadata agents.

Recommended Providers

1. Audible: The most reliable source for audiobook metadata, descriptions, and high-resolution cover art. Install the Audible scraper via Settings > Metadata Providers.
2. Open Library / Google Books: Best for eBook metadata.
3. MusicBrainz: Excellent for indexing author biographies and discographies.

Embedded Metadata extraction

Under Settings > Libraries > [Your Library] > Manage, enable Prefer Embedded Metadata if your library is already meticulously tagged via tools like MP3Tag or beets. If untagged, leave this disabled and rely on Audiobookshelf's automated scrapers.

6. Client Syncing & Automation

Audiobookshelf provides native Android and iOS client applications (available via TestFlight/Google Play).

Sync Settings

• Because you configured WebSockets in the reverse proxy step, the client app will automatically sync playback progress down to the millisecond when switching between the web client and mobile device.
• Enable Offline Sync in the mobile app settings to cache transcripts and audio files locally; progress will sync back to the VPS host server the next time the app reconnects.