How to Install and Self-Host Audiobookshelf

Why self-host Audiobookshelf?

Audiobookshelf is a self-hosted audiobook and podcast server with a browser-based client. It can stream audio, maintain progress for individual users, synchronize progress across devices, organize multiple libraries, download podcast episodes, and manage metadata and cover images. Its multi-user model also supports custom permissions, which is useful when a household or small group shares one server without sharing a single user account.

Self-hosting gives the server direct access to media stored on hardware you control. Your audiobook and podcast directories can remain on your workstation, home server, or another storage device that the Docker host can access. Audiobookshelf then indexes those mounted directories and presents them through its web client and supported applications.

The installation has two distinct networking stages. First, Audiobookshelf must run correctly as a local service. Second, if remote access is required, that working local endpoint can be published through an HTTP tunnel. Keeping these stages separate makes problems easier to diagnose. A tunnel cannot correct an inaccessible container, an incorrect volume path, a missing library, or an application that has not started successfully.

Audiobookshelf also supports features such as metadata and cover-art retrieval, chapter editing, metadata backups, podcast feeds, bulk uploads, a Progressive Web App, basic ebook support, and open RSS feeds. Available behavior can change between releases, so application-specific options should always be reviewed after an upgrade.

Prerequisites for this installation

Docker is the recommended installation method in the Audiobookshelf installation documentation. This guide uses Docker Compose because it keeps the image, port, volume, environment, and restart settings in one readable file. It also makes later upgrades repeatable.

Before beginning, prepare a machine that can remain powered on whenever the library should be available. It needs enough local storage for the application data and media you intend to serve, plus permission to read the media directories and write to the configuration and metadata directories.

Required software and access

• Docker installed and running on the host.
• The Docker Compose command available as docker compose.
• Permission to create directories and start containers.
• Host directories for Audiobookshelf configuration and metadata.
• One or more directories containing audiobooks, podcasts, or other media that Audiobookshelf will index.
• Local access to TCP port 13378, unless you deliberately choose a different external host port.
• For the remote-access stage, the Localtonet client installed on a device that can reach the Audiobookshelf service.

Confirm that Docker and Docker Compose are available before creating the deployment:

docker --version
docker compose version

The exact Docker installation procedure depends on the operating system and distribution. This article does not substitute an unverified package command because package names, repositories, service-management commands, and supported Docker versions vary. Install Docker using the procedure appropriate for your host, start the Docker service where required, and then rerun the two checks above.

Choose a deployment location

Create a dedicated deployment directory for the Compose file. The actual location is your choice. Inside or alongside that deployment directory, decide where the persistent configuration and metadata will live. Media can be stored elsewhere, provided the Docker host can access it reliably.

Avoid putting temporary files, the SQLite database, and media into the container's writable layer. Containers are intended to be replaceable. Data that exists only inside a removed container may be lost when the container is recreated.

Plan ports, storage, and image versions

A reliable deployment begins with understanding what each Docker mapping does. Audiobookshelf listens on port 80 inside the container. The official Docker example publishes that internal service on host port 13378. This results in a local endpoint such as http://localhost:13378 when the browser and Docker are on the same machine.

In a Docker port mapping, the value on the left is the host port and the value on the right is the container port. If port 13378 is already occupied, change only the external value on the left. Do not change the container-side port from 80 unless current Audiobookshelf documentation specifically directs you to do so.

Each mount point should be a separate directory and should not be contained inside another mount point. For example, do not make the configuration directory a child of a directory that is also mounted into the container as a separate volume. Overlapping mounts make file visibility and backup behavior difficult to reason about.

Select an image tag

Audiobookshelf publishes several Docker image tag styles. The right choice depends on whether you prefer automatic movement to the newest stable release, a deliberately pinned version, or pre-release testing.

This guide follows the official minimal example and uses :latest. If predictable change control is more important, replace latest with a specific released version and update that value intentionally during each upgrade. Do not copy an old example version without first deciding whether that is the version you actually want to operate.

Install Audiobookshelf with Docker Compose

The following workflow uses the project's documented Compose structure. Replace every host-side placeholder with a real absolute path on your Docker host. The paths on the right side of each volume mapping are the locations visible inside the container.

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    ports:
      - 13378:80
    volumes:
      - </path/to/config>:/config
      - </path/to/metadata>:/metadata
      - </path/to/audiobooks>:/audiobooks
      - </path/to/podcasts>:/podcasts
    environment:
      - TZ=America/Toronto
    restart: unless-stopped

Replace </path/to/config>, </path/to/metadata>, </path/to/audiobooks>, and </path/to/podcasts> with paths that exist on your host. Replace America/Toronto with the appropriate time zone. Do not leave angle-bracket placeholders in the file.

Then run the deployment commands from the same directory:

docker compose config
docker compose pull
docker compose up --detach
docker compose ps
docker compose logs

If you need additional media libraries, add additional volume mappings. Audiobookshelf permits as many or as few extra media mounts as your design requires. Give each one a distinct host directory and a distinct in-container path.

Docker CLI alternative

Docker Compose is easier to review and maintain, but the official installation documentation also provides a direct Docker command. Replace all path placeholders and the example time zone before running it:

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

On Windows, the documented command must be entered as one line after removing the backslash line continuations. Host path syntax also depends on the shell and Docker environment, so use paths that Docker can access rather than copying Unix-style placeholders literally.

Verify Audiobookshelf locally

Local verification should cover more than whether the container appears in a process list. Confirm that the container is running, the HTTP interface responds, persistent directories are writable, and mounted media can be selected from inside Audiobookshelf.

Check the container state

docker compose ps
docker compose logs --tail 100

The service should remain running rather than repeatedly restarting or exiting. Read the application logs for actionable path, database, permission, or startup errors. A restart loop usually indicates a local deployment problem and should be fixed before configuring a tunnel.

Open the browser interface

From the Docker host, open:

http://localhost:13378

If the browser is on another machine in the same local network, use the Docker host's reachable local address with port 13378. Whether that connection is allowed depends on the host firewall, Docker networking, and local network policy. Do not disable the entire firewall merely to make the service reachable. Add only the access needed for the intended local clients.

Complete the setup flow presented by the installed Audiobookshelf version. The supplied evidence does not establish the exact labels or sequence of every first-run screen, so this guide does not invent them. Use unique credentials, then create libraries that point to the in-container media paths you mounted, such as /audiobooks and /podcasts.

Test the actual media workflow

• Confirm that the intended mounted directories are visible when creating or editing a library.
• Scan the library and verify that expected media appears.
• Open an item and begin playback.
• Pause and resume to confirm the application is functioning beyond its landing page.
• If multiple users are required, create and test them through the current application interface with appropriate permissions.
• Restart the container and verify that the configured users, libraries, metadata, and progress remain available.

The restart test is especially important. If data disappears after recreation or restart, the volume mappings are incorrect, inaccessible, or pointing to temporary locations.

docker compose restart
docker compose ps
docker compose logs --tail 100

Operate, back up, and upgrade Audiobookshelf

A self-hosted media server needs a repeatable operating routine. At minimum, know how to view logs, stop and start the service, update the image, and protect the persistent data.

Common Docker Compose operations

docker compose ps
docker compose logs
docker compose logs --tail 100
docker compose restart
docker compose stop
docker compose start
docker compose down
docker compose up --detach

docker compose down removes the Compose-managed container and network, but the bind-mounted host directories remain outside the container. Avoid adding volume-removal options unless you understand exactly which storage Docker will delete.

Upgrade the container

The documented Compose upgrade sequence pulls the selected image, stops and removes the existing container, and creates a new container from the updated image:

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

After the upgrade, inspect the status and logs, then repeat a playback test:

docker compose ps
docker compose logs --tail 100

If the Compose file uses a fixed version tag, update that tag to the intended release before pulling. If it uses :latest, pulling retrieves the image currently associated with the stable tag. Review application release notes and maintain recoverable copies of persistent data before significant upgrades.

Back up persistent data

The /config mount contains the SQLite database and migration information. The /metadata mount contains metadata, images, logs, and backups. Both should be included in the host's backup strategy. Media directories should also be protected according to how replaceable the source files are.

The exact snapshot or file-copy method depends on the host filesystem, backup product, and storage design. For a consistent external backup, avoid copying a database while it is being changed unless the chosen backup method is designed for that purpose. A simple conservative approach is to stop the service during the copy window, back up the persistent host directories, and start it again. Validate restoration procedures on a separate test location rather than assuming that the existence of backup files guarantees recovery.

Avoid noisy container health checks

Audiobookshelf does not recommend health checks unless external monitoring is already in place. Continuously pinging the server and restarting it after a failed check is generally redundant when a restart policy is configured, and it can add unnecessary log noise. If a health check is deliberately implemented, note that the Audiobookshelf container includes wget but not curl.

Enable remote access with Localtonet

Once http://localhost:13378 works on the Docker host, remote access can be added as a separate layer. With Localtonet, the client application establishes an outbound connection to one of our relay servers. This provides a public URL without requiring inbound router port forwarding, firewall-wide changes, VPN setup, or a public IP address.

An HTTP tunnel is the relevant tunnel family because Audiobookshelf exposes a browser-based HTTP service. The Localtonet client must run on the Docker host or on another device that can reach the host and port selected as the local target.

For the current product workflow and available options, consult the Localtonet HTTP tunnel documentation. Do not copy a relay server code, authentication token, domain setting, or endpoint from someone else's configuration.

HTTP tunnels may use a generated subdomain, a selected subdomain where supported, or a custom domain. The available process types are Random Sub Domain, Custom Sub Domain, and Custom Domain, and each serves the same local content through a public HTTPS address. Availability can depend on the current product configuration or plan. Custom-domain DNS instructions should be taken from current Localtonet documentation rather than guessed.

Verify the remote path independently

Do not test only from a device that might still be using the local address. Disable Wi-Fi on a phone or use another external network, then open the assigned public URL. A complete test should include authentication, library navigation, playback, seeking, and any client behavior that depends on real-time updates.

If the page loads but interactive features fail, inspect the browser developer console and Audiobookshelf logs for failed WebSocket upgrades or repeated reconnect attempts. Also confirm that the tunnel targets the service directly and that no additional reverse proxy between the tunnel client and Audiobookshelf is stripping upgrade headers.

Secure the Audiobookshelf deployment

Publishing a private media server creates an internet-reachable login surface. Treat remote access as a deliberate security decision, not merely a connectivity setting. Use the smallest practical exposure, maintain the application, and stop the tunnel when remote access is no longer required.

The Docker example publishes host port 13378. Control local reachability with deliberate host and network rules instead of broad firewall disablement. If only the Localtonet client on the Docker host needs local access, there is usually no reason to make the service generally available to untrusted local networks. Exact binding and firewall configuration varies by operating system and is outside the verified project-specific evidence supplied for this guide.

Keep the administrative account for administration. If family members or other users only need playback access, use Audiobookshelf's multi-user permissions to avoid granting unnecessary control. Review users periodically and remove access that is no longer required.

Troubleshooting common installation and access problems

The container exits or repeatedly restarts

Start with the current container state and logs:

docker compose ps
docker compose logs --tail 200

Check for malformed YAML, an unavailable image, inaccessible host paths, permission failures, or a port conflict. Run docker compose config again after editing the Compose file.

Port 13378 is already in use

Change only the external side of the port mapping. For example, select an unused host port while retaining container port 80. Then use that new host port in the local browser address and Localtonet tunnel target. The exact replacement port is a local administrative choice, so this guide does not guess which port is available on your host.

A mounted library appears empty

Verify that the left side of the volume mapping points to the intended host directory. Then verify that Audiobookshelf is configured to use the right-side container path, such as /audiobooks. Confirm that the container can read the files and that mount points do not overlap.

Directory structure and folder names are important to Audiobookshelf's media organization. If files are visible but identified incorrectly, review the library's directory organization and media metadata rather than repeatedly recreating the container.

Settings disappear after recreation

This normally indicates that /config or /metadata was not mapped to the intended persistent host directory, or that the mapping changed between starts. Compare the active Compose configuration with the actual directories, and check whether those directories contain the expected application data.

The web page works locally but not through Localtonet

Confirm that the Localtonet client device can open the exact local target independently of the tunnel. Verify the target IP address and port, confirm that the client is connected, and confirm that the tunnel has been started. Remember that creating a tunnel alone does not make it active.

The remote login page loads but playback or updates fail

Audiobookshelf requires WebSocket connectivity. A partially working page can indicate that ordinary HTTP requests succeed while the WebSocket upgrade does not. Test from an external network, inspect browser errors, inspect Audiobookshelf logs, and confirm current Localtonet HTTP tunnel compatibility. If another reverse proxy is present, check its documented WebSocket settings as well.

An upgrade reports a missing /index.js module

Audiobookshelf documents Error: Cannot find module '/index.js' as a common problem when some container managers cache an old version during an update. Recreate the container from the newly pulled image. In Synology Container Manager, the documented remedy is to stop and reset the container. In Portainer, recreate the container or stack.

Frequently asked questions