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.

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
    # ...
  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: Use host.docker.internal (Docker 20.10+) or 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 running. Use this for container orchestration, monitoring, or load balancer health probes:

services:
  narratorr:
    image: narratorr/narratorr:latest
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      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

Tip

Automate backups with a cron job or your preferred backup tool. The SQLite database is safe to copy while Narratorr is running (WAL mode handles concurrent access).

Environment Variables

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

Common Issues

• Container can’t write to volumes — check file permissions. Narratorr runs as root in the default image.
• 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.