Audiobookshelf Docker Compose: Preserve Books, Metadata, and Listening Progress

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    ports:
      - "127.0.0.1:13378:80"
    volumes:
      - ./config:/config
      - ./metadata:/metadata
      - ./audiobooks:/audiobooks
      - ./podcasts:/podcasts
    environment:
      TZ: America/Detroit
    restart: unless-stopped

How should a first library be organized?

Start with a small sample whose folder structure and metadata you understand. Correct grouping problems before a large scan turns them into hundreds of confusing entries.

The book directory guide describes how directories, tags and accompanying metadata influence identification. Keep tracks for one book together. Include a single-file book and a book with multiple tracks in your trial, then inspect title, author, narrator, chapters and playback order.

Do not fix a grouping mistake only by renaming a directory and assuming every existing database relationship will follow. Inspect the resulting item after rescanning and follow the documented correction procedure when necessary. Preserve originals before any bulk rename or metadata edit.

Keep a short record of the naming convention you chose. It should be understandable to the next person adding a book. Consistency beats an elaborate scheme that only its creator remembers.

A library is also a boundary: the library overview explains that moving files between libraries creates different items and does not automatically move listening progress. Plan categories before listeners accumulate history.

What proves that playback and progress work?

A successful test includes the real listening device, a pause and resume, and a second account. Checking only the administrator's browser misses the behavior people depend on every day.

Use this practical sequence with the sample books:

1. Sign in as an ordinary listener and start playback.
2. Seek into a later chapter, pause, and close the client.
3. Reopen it and inspect the saved position.
4. Repeat through the remote access route you intend to use.
5. Sign in as a different listener and verify their independent state.
6. Restart the server and repeat the resume check.

These are acceptance steps to perform on your installation, not reported benchmark results. Record any client-specific limitation instead of generalizing one successful browser session to every device.

If playback fails, separate a missing file from a decoding problem and a remote networking problem. The server FAQ discusses codec and scanning limitations. Try another permitted sample file before rebuilding the whole stack.

For a broader home media deployment, the Jellyfin Compose guide follows the same separation between readable media, persistent application state and actual client acceptance.

How do you protect access and backups?

Keep administrative access private and protect original audio independently of application backups. A backup directory located on the same failed disk will not rescue the library.

Choose a VPN or an HTTPS proxy that supports the application's required connections. Test the phone's real route, including login and seeking through a long file. Keep the direct container port from bypassing the access policy.

Docker's volume documentation explains why persistent storage survives container replacement. Persistence alone does not protect against host loss, accidental deletion or unreadable backups. Define the separate recovery copy explicitly.

Estimate media and retained backup capacity with the backup storage calculator. Keep configuration and metadata in the plan even if they occupy far less space than the audio. Their value is not proportional to their size.

Restrict access to backups because they can reveal user information and library details. Review the contents of an application-generated backup before assuming it contains every mounted media file. Retain a separate inventory of the directories your recovery process actually covers.

How do you restore and upgrade safely?

Rehearse restoration into a separate, private instance using matching software before changing the working server. Verify listening progress as carefully as file visibility.

For a straightforward small installation, stop writes and create a coherent copy of the application directories together with the media backup. Restore copies into distinct paths, use another host port, and ensure the trial cannot modify the live library. Never point two test and production instances at the same writable database.

Compare the restored library with your acceptance list: accounts, sample books, covers, chapters and known listening positions. Keep the original server available until the exercise succeeds.

For updates, read the official upgrade instructions and release notes, capture a fresh backup, then replace the container. Retaining an old image alone is not enough for rollback if a newer release changes stored data; retain the matching pre-update state too.

FAQ

Does an application backup include every audiobook?

Do not assume so. Inspect its contents and protect the media directories independently.

Can the database live on my NAS?

Keep /config on storage local to the server process. A NAS running the container with local storage differs from a server accessing its database over a network share.

Why do PUID and PGID not change permissions?

The official image uses a different documented user configuration. Check the container identity and directory ownership together.

Will moving books between libraries preserve progress?

Not automatically. Treat a library move as a migration and validate user history before reorganizing a working collection.