Kima-Hub Deployment / Repair Reference

Host: PlausibleDeniability (PD)
Stack dir in repo: media/kima-hub/
Live stack dir on host: /mnt/docker-ssd/docker/compose/media/kima-hub/
Status: Repo stack corrected to match upstream all-in-one Kima layout and live service verified healthy on PD

Current canonical stack

The upstream all-in-one Kima image expects this shape:

Image: ghcr.io/chevron7locked/kima:latest
Container name: kima
Host port: 3333
Container port: 3030
Persistent data:
- /mnt/docker-ssd/docker/appdata/kima-hub/data:/data
Media mount:
- /mnt/unraid/data/media/music:/music
Network: pangolin
Host gateway alias: host.docker.internal:host-gateway

Canonical live `.env` shape

TZ=America/New_York
SESSION_SECRET=
SETTINGS_ENCRYPTION_KEY=
KIMA_CALLBACK_URL=http://host.docker.internal:3333
DISABLE_CLAP=
LIDARR_API_KEY=
FANART_API_KEY=
LASTFM_API_KEY=
OPENAI_API_KEY=
SOULSEEK_USERNAME=
SOULSEEK_PASSWORD=

Notes:

SESSION_SECRET and SETTINGS_ENCRYPTION_KEY can be left blank; current upstream all-in-one image will generate and persist them under /data/secrets on first start.
DISABLE_CLAP=true is the low-memory / no-AI-vibe fallback if the analyzer proves too heavy.
KIMA_CALLBACK_URL should point at the host-facing Kima URL Lidarr can reach.

Canonical compose file

services:
  kima:
    image: ghcr.io/chevron7locked/kima:latest
    container_name: kima
    environment:
      - TZ=${TZ}
      - SESSION_SECRET=${SESSION_SECRET:-}
      - SETTINGS_ENCRYPTION_KEY=${SETTINGS_ENCRYPTION_KEY:-}
      - KIMA_CALLBACK_URL=${KIMA_CALLBACK_URL:-http://host.docker.internal:3333}
      - DISABLE_CLAP=${DISABLE_CLAP:-}
      - LIDARR_API_KEY=${LIDARR_API_KEY:-}
      - FANART_API_KEY=${FANART_API_KEY:-}
      - LASTFM_API_KEY=${LASTFM_API_KEY:-}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      - SOULSEEK_USERNAME=${SOULSEEK_USERNAME:-}
      - SOULSEEK_PASSWORD=${SOULSEEK_PASSWORD:-}
    volumes:
      - /mnt/docker-ssd/docker/appdata/kima-hub/data:/data
      - /mnt/unraid/data/media/music:/music
    ports:
      - "3333:3030"
    networks:
      - pangolin
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

networks:
  pangolin:
    external: true

Validate before deploy

cd /mnt/docker-ssd/docker/compose/media/kima-hub
sudo docker compose --env-file .env config

Deploy / repair

cd /mnt/docker-ssd/docker/compose/media/kima-hub
sudo docker compose --env-file .env up -d
sudo docker compose --env-file .env ps
sudo docker logs --tail 60 kima

Post-deploy checks

Open http://10.5.30.6:3333
Confirm the app starts and initial setup loads
Confirm /music is visible to Kima
Confirm Kima creates and uses /data persistence correctly
Add Pangolin resource for kima.paccoco.com if desired
Confirm the NFS-backed Serenity media mount at /mnt/unraid/data/media is present on PD and contains the music library Kima should scan

Verified on 2026-05-15:

container kima running and healthy
http://10.5.30.6:3333/api/health returned status OK
live mount narrowed to /mnt/unraid/data/media/music:/music

Optional integrations / secrets

Not required just to boot:

Lidarr API key — for Lidarr integration
Fanart API key — for artist images
Last.fm API key — for enrichment/recommendations
OpenAI API key — optional AI features documented upstream; current upstream docs only explicitly mention OpenAI for that part
Soulseek username/password — if Soulseek features are used

Do not commit live secrets into the repo copy of .env.

Notes

The previous repo/live shape using /app/config, /app/data, PUID, PGID, KIMA_MUSIC_PATH, and 3333:3333 did not match current upstream all-in-one docs.
KitchenOwl already lives in the home/ stack; Kima lives in its own media/kima-hub/ stack.
Keep compose-managed runtime under /mnt/docker-ssd/docker/compose/... per SOP.

4.0 KiB Raw Blame History