Kolumi Server

Setup guide

Kolumi Server is an optional add-on for families. It runs as one Docker container next to your Audiobookshelf and Navidrome and adds households with profiles, kids’ rules (bedtime, daily listening time, what’s on the shelf), wishes and listening together. The app works without it.

What you need

• Docker with Compose
• Audiobookshelf and/or Navidrome (version 0.64.1 or newer), reachable from the container
• An admin API key for Audiobookshelf and a Navidrome admin with a password
• Optional: an OpenID Connect provider such as Authentik for single sign-on

1. Compose file

services:
  kolumi-server:
    image: ghcr.io/xnycrofox/kolumi-server:latest
    container_name: kolumi-server
    restart: unless-stopped
    user: "1000:1000"
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
    env_file: .env

Create the data folder first and give it to the container user: mkdir data && sudo chown 1000:1000 data. Put the container in the same Docker network as Audiobookshelf and Navidrome, or use their full addresses below. Behind a reverse proxy, drop ports and route your domain to port 8080.

2. Settings (.env)

# Address the apps and browsers use (QR codes, sign-in redirects)
KOLUMI_PUBLIC_URL=https://kolumi.example.org
KOLUMI_NAME=Kolumi Server
TZ=Europe/Berlin

# Audiobookshelf: API key of an admin (Settings → API Keys)
ABS_URL=http://audiobookshelf:80
ABS_ADMIN_TOKEN=...

# Navidrome: admin with password, header sign-in (see step 3)
ND_URL=http://navidrome:4533
ND_ADMIN_USER=admin
ND_ADMIN_PASSWORD=...
ND_USER_HEADER=Remote-User

# Who may create a household without an invite: sso | invite | closed
KOLUMI_SIGNUP=invite

3. Navidrome header sign-in

Kolumi Server signs people in to Navidrome with a trusted header. Add this to Navidrome and restart it:

ND_EXTAUTH_USERHEADER: Remote-User          # same name as ND_USER_HEADER
ND_EXTAUTH_TRUSTEDSOURCES: 172.16.0.0/12    # network Kolumi Server connects from

If Navidrome already uses a header for your reverse proxy (for example X-authentik-username), set ND_USER_HEADER to that name instead. Kolumi Server strips the header from client requests, and its web interface checks under Services that Navidrome accepts it.

4. First start

1. docker compose up -d, then docker compose logs kolumi-server | grep adminToken. The one-time admin token (KOLUMI-XXXX-XXXX-XXXX) is shown while there is no admin yet and changes on every restart.
2. Open the web interface at KOLUMI_PUBLIC_URL and sign in with the token. English and German are available at the bottom of the sidebar.
3. Services should show Audiobookshelf and Navidrome as connected.
4. Libraries: sync with your servers, then set who each library is for (kids, teens, adults, mixed).
5. Households: invite your family. Each person redeems the code in the app under Connect to Kolumi Server.

Single sign-on (optional)

With an OpenID Connect provider, create two applications: a public client for the app with redirect kolumi://auth/callback, and a confidential client for the web interface with redirect <KOLUMI_PUBLIC_URL>/auth/callback. Then set:

KOLUMI_OIDC_ISSUER=https://auth.example.org/application/o/kolumi/
KOLUMI_OIDC_CLIENT_ID=kolumi
KOLUMI_OIDC_LABEL=Authentik
KOLUMI_OIDC_WEB_CLIENT_ID=kolumi-web
KOLUMI_OIDC_WEB_CLIENT_SECRET=...
KOLUMI_ADMIN_GROUP=kolumi-admin

Members of the admin group become instance admins. In Audiobookshelf, set OpenID “Match existing users by” to email so people are linked to their existing accounts.

Updates and backups

Update with docker compose pull && docker compose up -d. Back up the data folder: it holds the database and secret.key, which encrypts stored credentials.

Upgrading from Kobel

Kolumi Server used to be called Kobel. Old KOBEL_ settings still work, kobel.db is taken over on first start, and existing KOBEL- codes stay valid. Change the image to ghcr.io/xnycrofox/kolumi-server and the healthcheck to /usr/local/bin/kolumi-server healthcheck.

Questions

Write to hello@kolumi.app.