Docker

Volumes

Narratorr uses three key directories, typically mapped as Docker volumes:

Container Path	Purpose	Back Up?
/config	Database, settings, configuration files	Yes
/audiobooks	Your audiobook library	Optional (media can be re-downloaded)
/downloads	Shared with download client for import	No

volumes:
  - ./config:/config       # Persist between container recreations
  - /data/audiobooks:/audiobooks
  - /data/downloads:/downloads

Caution

If you don’t mount /config, your database and settings are lost when the container is removed.

Note

The image ships with ffmpeg bundled for audio post-processing (M4B conversion, chapter embedding, cover-art embedding), so no external ffmpeg install is required.

Networking

Connecting to Other Containers

When Narratorr and your download client are in the same docker-compose.yml, use the service name as the hostname:

services:
  narratorr:
    image: narratorr/narratorr:latest
    environment:
      - PUID=1000   # default: 911
      - PGID=1000   # default: 911
      - TZ=America/New_York
    # ...
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    # ...

In Narratorr’s download client settings, set host to qbittorrent (the service name), not localhost.

Connecting to Host Services

If a service runs on the host machine (not in Docker):

• Linux: host.docker.internal doesn’t resolve by default — add extra_hosts: ["host.docker.internal:host-gateway"] to the narratorr service (Docker 20.10+) to enable it, or use the host’s LAN IP
• Windows/macOS: Use host.docker.internal (built-in)

Custom Networks

If services are in separate compose files, create a shared network:

# In both docker-compose files:
networks:
  shared:
    external: true

services:
  narratorr:
    networks:
      - shared

Create the network first: docker network create shared

Health Check

Narratorr exposes a health check endpoint:

GET /api/health

Returns 200 OK when the server is up and its database responds; if the database probe fails, it returns 503 even though the process is still running. Use this for container orchestration, monitoring, or load balancer health probes.

The image already defines its own HEALTHCHECK (with a built-in start period), so no manual configuration is needed. If you do want to override it — for example in a load balancer or external monitor — match what the image does so it keeps working under a reverse-proxy subpath:

services:
  narratorr:
    image: narratorr/narratorr:latest
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:3000${URL_BASE:-}/api/health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3

Updating

1. Pull the latest image:

   docker compose pull

2. Recreate the container:

   docker compose up -d

Your data persists in the mounted volumes. Database migrations run automatically on startup.

Backups

Back up the /config directory. It contains:

• narratorr.db — your database (books, settings, indexer configs, download history)
• Any other configuration files

# Simple backup
cp -r ./config ./config-backup-$(date +%Y%m%d)

# Or with a Docker volume
docker run --rm -v narratorr_config:/config -v $(pwd):/backup alpine \
  tar czf /backup/narratorr-config-$(date +%Y%m%d).tar.gz /config

Caution

Copying narratorr.db while Narratorr is running is not guaranteed to produce a consistent snapshot — stop the container first if you copy the raw database file. Better: rely on the built-in scheduled backups (Settings > System), which use VACUUM INTO for a consistent snapshot. The backup zips in config/backups/ are always safe to copy while running, so an automated copy of /config still works — just restore from the zips, not the copied live database. See Backup & Restore.

Environment Variables

See Environment Variables for the complete reference. The Docker image sets production defaults automatically.

Because the image is based on LinuxServer.io, it also honors these standard variables:

• PUID / PGID — the runtime UID/GID used for file ownership of everything Narratorr writes (config database, imported audiobooks). Default 911; set them to match the owner of your host directories. See the volume-permissions note under Common Issues.
• TZ — the container timezone (e.g. America/New_York), used for log timestamps and scheduling.

Common Issues

• Container can’t write to volumes — Narratorr runs as the unprivileged abc user (LinuxServer.io base image). Set PUID/PGID to match the UID/GID that owns your host directories (default 911). Run id on the host to find the right values.
• Can’t connect to download client — use service names, not localhost. See Troubleshooting.
• Downloads complete but don’t import — the /downloads volume must be accessible to both containers with matching paths. See Remote Path Mappings.