Audiobookshelf

Listen to audiobooks and podcasts, manage libraries and synchronize playback.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Audiobookshelf

Editable Compose files in your own directory.

Persistent /data contains config and metadata. Mount audiobook and podcast libraries separately and create libraries in Audiobookshelf.
Automatic app setup creates the first root account and verifies initialization.

selfhost app --directory ./audiobookshelf init audiobookshelf

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./audiobookshelf start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd audiobookshelf
docker compose -f compose.yaml up -d

Before configuring integrations

Environment settings expose timezone, routing prefix, backup path and media tool paths. Additional paths must refer to mounted container directories.
Keep the SQLite configuration database on local storage. Back up config, metadata and your media.
OIDC configuration, API tokens, libraries and scheduled backups are managed in Audiobookshelf; Selfhost does not automate these runtime settings yet.
Existing initialized servers are never reset by onboarding.

Audiobookshelf integrations

Compose service: audiobookshelf. These operations use the profile saved when this deployment is created.

Initialize and connect

Supported setup modes: bootstrap.

Creates the first administrator only. Existing installations are never reset. Library paths and media access remain under your control.

Setup fields

Administrator username username: string · requiredDefault: "admin"Length: 1 to 64 characters
Administrator password password: secret · requiredLength: 12 to 128 characters

Save onboarding.json, replace example values and supply env: secrets privately through your shell. Empty apps adds no links; add explicit links when this profile supports them.

{
  "mode": "bootstrap",
  "inputs": {
    "username": "admin",
    "password": "env:SELFHOST_PASSWORD"
  },
  "apps": []
}

selfhost app --directory ./audiobookshelf setup audiobookshelf
selfhost app --directory ./audiobookshelf setup-plan audiobookshelf onboarding.json
selfhost app --directory ./audiobookshelf setup-apply audiobookshelf onboarding.json --revision REVIEWED_REVISION

Setup modes, secret references and recovery

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (8)

TZ tz: string · advanced
ALLOW_IFRAME allow-iframe: string · advanced
BACKUP_PATH backup-path: string · advanced
FFMPEG_PATH ffmpeg-path: string · advanced
FFPROBE_PATH ffprobe-path: string · advanced
ROUTER_BASE_PATH router-base-path: string · advanced
HOST host: string · advanced
PORT port: string · advanced

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./audiobookshelf config audiobookshelf
selfhost app --directory ./audiobookshelf plan audiobookshelf changes.json
selfhost app --directory ./audiobookshelf apply audiobookshelf changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

App actions

Check HTTP health

Check the local Audiobookshelf HTTP server.

selfhost app --directory ./audiobookshelf action audiobookshelf check-health

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

audiobookshelf: ghcr.io/advplyr/audiobookshelf:2.36.1

2.36.1 ghcr.io/advplyr/audiobookshelf:2.36.1
Local Docker HTTP startup, native configuration roundtrip, declared read-only actions and container recreation with persistent volumes passed. First administrator setup and initialized state after recreation passed. External provider login and version upgrades require separate validation.

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Audiobookshelf documentation