Skip to main content

Docker

Docker is the recommended way to run Audiobookshelf. If you are unfamiliar with Docker, check out the Docker Getting Started guides.

The following docker tags are available for use:

  • :latest is the most recent stable release found at https://github.com/advplyr/audiobookshelf/releases
  • :edge is updated for every commit to the master branch, usually available within 15 minutes. This tag allows you to help test new features before a release and is generally safe to use. If you are using :edge and encounter a problem with a new feature, please report this on GitHub and include the commit hash.
  • :v#.#.# is a specific released version number. For example, to use v2.19.0, use the :v2.19.0 tag.

Audiobookshelf uses the /config and /metadata folders by default to store all Audiobookshelf data. Additional folders can be used to access your media files. Most users use two additional mounts, one for /audiobooks and one for /podcasts, but you can create as many or as few of these additional mounts as you want.

  • /config stores the SQLite database and database migration scripts.
  • /metadata stores the book metadata, cover/author images, logs, and backups.

Docker Compose​

A minimal docker compose example is included below. Make sure to update the external paths to point to the correct external directory.

docker-compose.yml
services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    # ABS runs on port 13378 by default. If you want to change
    # the port, only change the external port
    ports:
      - 13378:80
    volumes:
      # These volumes are needed to keep your library persistent
      # and allow media to be accessed by the ABS server.
      - </path/to/config>:/config
      - </path/to/metadata>:/metadata
      # The path to the left of the colon is the path on your computer,
      # and the path to the right of the colon is where the data is
      # available to ABS in Docker. You can change these lines freely
      # or add additional mounts for additional libraries.
      - </path/to/audiobooks>:/audiobooks
      - </path/to/podcasts>:/podcasts
    environment:
      - TZ=America/Toronto
      # Add other environment variables here
    restart: unless-stopped
    # Audiobookshelf does not use PUID or GUID environment variables.
    # To run as a different user, use the following directive.
    #user: 1000:1000
Mount Points

Each mount point should be a separate directory that is not contained within another mount point.

Network Mounts

The /config mount contains the SQLite database used by the server. This must be accessible directly on the same machine running the Audiobookshelf server and not be stored and accessed over the network, such as on a different NAS. The server may appear to work correctly if the database is accessed over the network, but performance will suffer and you will eventually encounter database corruption. https://www.sqlite.org/useovernet.html

Healthchecks​

Audiobookshelf does not recommend the use of health checks unless you have external monitoring set up. Using a health check to continously ping the server and restart the container when the server crashes is generally redundant to setting a restart policy and adds noise to your logs.

If you do use a healthcheck, the Audiobookshelf container includes wget but does not include curl.

Docker Run Command​

If you prefer to use the Docker CLI, an example docker run command is shown below. For beginners, we recommend using Docker Compose to make management easier.

docker pull ghcr.io/advplyr/audiobookshelf

docker run -d \
 -p 13378:80 \
 -v /path/to/config:/config \
 -v /path/to/metadata:/metadata \
 -v /path/to/audiobooks:/audiobooks \
 -v /path/to/podcasts:/podcasts \
 --name audiobookshelf \
 -e TZ="America/Toronto" \
 ghcr.io/advplyr/audiobookshelf:latest
Windows users

If you're on Windows, remove the \ line breaks and run this as a single line.

Upgrading​

To upgrade your Audiobookshelf docker container, pull the new image and restart the container.

If you manually specified a server version number, you will need to update the server version number to ensure you are pulling the correct version.

This can be done using the following commands for Docker Compose.

docker compose pull
docker compose down
docker compose up --detach

Common Upgrade Problems​

Some docker managers do not perform updates correctly, such as Container Manager, Portainer, or other managers installed on some systems. This is usually caused by the manager caching old versions of the container. Some of the common startup errors are:

  • Error: Cannot find module '/index.js'
  • code: 'MODULE_NOT_FOUND',

You can force your container manager to reset the container and use the new image. Note this will delete any files that are not accessible outside of the container in volumes (see setup above).

  • Container Manager on Synology: Stop the container and then "Reset" the container under "Actions".
  • Portainer: "Recreate" the container or stack.