Install

Armarium ships as one Docker image, ghcr.io/r0adkll/armarium, with Libation’s command-line tool inside. It needs three folders: its own config, its own data, and the Audiobookshelf library folder.

Mount the library at the same path Audiobookshelf uses

If Audiobookshelf sees its library at /audiobooks, mount the same host folder at /audiobooks inside Armarium too (and set ARMARIUM_LIBRARY_DIR=/audiobooks). Then the paths both apps talk about match.

Setup wizard

Run it in the folder you want to deploy from. It asks four questions, generates the keys, writes .env and docker-compose.yml, starts the container, and then walks you through the browser steps.

mkdir -p /opt/armarium && cd /opt/armarium
curl -fsSL https://raw.githubusercontent.com/r0adkll/armarium/main/scripts/setup.sh | bash

It asks for:

• the public URL people will open Armarium at, e.g. https://armarium.example.com;
• the host path of the Audiobookshelf library folder, e.g. /mnt/media/audiobooks;
• a folder for Armarium’s state, e.g. /mnt/media/armarium (it creates config/ and data/ there);
• the container path Audiobookshelf uses for that library (look in its library settings), e.g. /audiobooks.

By hand

1. Create the folders. The container runs as uid 1001, so give it ownership:

   mkdir -p /mnt/media/armarium/{config,data}
   chown -R 1001:1001 /mnt/media/armarium

   It also needs to write to the Audiobookshelf library folder.

2. Write a .env next to your compose file:

   .env

   ARMARIUM_PUBLIC_URL=https://armarium.example.com
   ARMARIUM_HOME=/mnt/media/armarium
   ARMARIUM_LIBRARY_PATH=/mnt/media/audiobooks
   ARMARIUM_LIBRARY_DIR=/audiobooks
   # Downloads wait on the library's own disk, so a finished book moves into place in one step
   ARMARIUM_STAGING_DIR=/audiobooks/.armarium
   # Two keys; make each with: openssl rand -base64 32
   # Keep them safe, see "Backups and keys"
   LIBATION_MASTER_KEY=paste-a-generated-key
   ARMARIUM_SESSION_SECRET=paste-another-generated-key

3. And the compose file:

   docker-compose.yml

   services:
     armarium:
       image: ghcr.io/r0adkll/armarium:main
       container_name: armarium
       restart: unless-stopped
       env_file: .env
       volumes:
         - ${ARMARIUM_HOME}/config:/config
         - ${ARMARIUM_HOME}/data:/data
         - ${ARMARIUM_LIBRARY_PATH}:${ARMARIUM_LIBRARY_DIR}
       ports:
         - "8080:8080"

4. Start it:

   docker compose up -d
   curl -fsS localhost:8080/healthz

Behind a reverse proxy

Point your proxy (Caddy, Traefik, nginx, Nginx Proxy Manager…) at port 8080 and serve it at the address you put in ARMARIUM_PUBLIC_URL. That address matters: single sign-on sends people back to it, and Armarium marks its cookie secure when it starts with https://.

If Armarium reaches Audiobookshelf through a proxy as well, that proxy must allow WebSocket upgrades; Armarium listens to Audiobookshelf’s live updates over one. On a shared Docker network you can skip the proxy and use the container name, e.g. http://audiobookshelf:80.

Which image tag

:main follows every change to the main branch. Once releases start, version tags like :0.1 and :0.1.0 are published too; pin one if you’d rather choose when to upgrade. See Upgrading.

Next: first run.