From ff2e13a16f45e3112cb1c45485d54af967559b09 Mon Sep 17 00:00:00 2001 From: Fizzlepoof Date: Fri, 15 May 2026 03:08:03 +0000 Subject: [PATCH] Align Kima Hub stack with live deployment --- docs/planning/DEPLOY_KIMA_HUB.md | 152 ++++++++++++++++++----------- media/kima-hub/docker-compose.yaml | 22 +++-- 2 files changed, 107 insertions(+), 67 deletions(-) diff --git a/docs/planning/DEPLOY_KIMA_HUB.md b/docs/planning/DEPLOY_KIMA_HUB.md index 0a06cdb..ab8612f 100644 --- a/docs/planning/DEPLOY_KIMA_HUB.md +++ b/docs/planning/DEPLOY_KIMA_HUB.md @@ -1,91 +1,125 @@ -# Kima-Hub Deployment Plan +# Kima-Hub Deployment / Repair Reference **Host:** PlausibleDeniability (PD) -**Port:** 3333 -**Stack dir:** `/mnt/docker-ssd/docker/compose/media-extra/` -**Status:** Pending +**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 -## What It Is +## Current canonical stack -Kima-Hub is a self-hosted music streaming platform — think personal Spotify. Point it at your music library and it handles cataloging, artist discovery, AI-powered playlists, podcast subscriptions, and seamless integration with Lidarr and Audiobookshelf. +The upstream all-in-one Kima image expects this shape: -## Pre-Deploy Checklist +- **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` -- [ ] Confirm music library path on Unraid NFS (`/mnt/unraid/data/media/music` or similar) -- [ ] Create appdata directory: `sudo mkdir -p /mnt/tank/docker/appdata/kima-hub` -- [ ] Create stack directory: `sudo mkdir -p /mnt/docker-ssd/docker/compose/media-extra` +## Canonical live `.env` shape -## docker-compose.yaml +```env +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 ```yaml services: - kima-hub: - image: chevron7locked/kima:latest - container_name: kima-hub - restart: unless-stopped - ports: - - "3333:3030" - volumes: - - /mnt/tank/docker/appdata/kima-hub:/data - - /mnt/unraid/data/media/music:/music:ro + kima: + image: ghcr.io/chevron7locked/kima:latest + container_name: kima environment: - TZ=${TZ} - healthcheck: - test: ["CMD-SHELL", "cat /proc/net/tcp6 | grep -q 0BD6 || exit 1"] - interval: 30s - timeout: 10s - retries: 3 + - 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 ``` -> **Note:** Internal port is `3030`, mapped to `3333` on the host. Hex `0BD6` = port 3030 for healthcheck. -> **Music path:** Adjust `/mnt/unraid/data/media/music` to match your actual Unraid music library path. -> **Read-only mount:** Music library is mounted `:ro` — Kima-Hub should not need write access to source files. - -## .env.example - -```env -TZ=America/New_York -``` - -## Deploy +## Validate before deploy ```bash -cd /mnt/docker-ssd/docker/compose/media-extra -sudo docker compose --env-file .env config # validate -sudo docker compose --env-file .env up -d -sudo docker logs kima-hub --tail 30 +cd /mnt/docker-ssd/docker/compose/media/kima-hub +sudo docker compose --env-file .env config ``` -## Post-Deploy +## Deploy / repair -1. Open `http://10.5.1.6:3333` and create your account -2. Point Kima at your music directory (`/music`) -3. In Lidarr: Settings → Connect → add Kima-Hub webhook -4. In Audiobookshelf: verify Kima can reach it at `http://10.5.1.6:13358` -5. Add Pangolin resource: `kima.paccoco.com` → port 3333 +```bash +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 +``` -## Pangolin Resource +## Post-deploy checks -Add in Pangolin dashboard: -- **Subdomain:** `kima.paccoco.com` -- **Target:** `http://10.5.1.6:3333` -- **Auth:** Enable (personal use only) +1. Open `http://10.5.1.6:3333` +2. Confirm the app starts and initial setup loads +3. Confirm `/music` is visible to Kima +4. Confirm Kima creates and uses `/data` persistence correctly +5. Add Pangolin resource for `kima.paccoco.com` if desired +6. Confirm the NFS-backed Serenity media mount at `/mnt/unraid/data/media` is present on PD and contains the music library Kima should scan -## Storage Decision +Verified on 2026-05-15: +- container `kima` running and healthy +- `http://10.5.1.6:3333/api/health` returned status OK +- live mount narrowed to `/mnt/unraid/data/media/music:/music` -| Path | Tier | Reason | -|------|------|--------| -| `/mnt/tank/docker/appdata/kima-hub` | tank | Config, DB, playlists — not write-heavy | -| `/mnt/unraid/data/media/music` | Unraid NFS (read-only) | Source library stays on Serenity | +## 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 -- NFS mount must be up before starting (`sudo bash /mnt/tank/docker/scripts/mount-unraid-nfs.sh`) -- If you transcode on the fly, CPU load on PD will spike; Kima-Hub is CPU-bound for transcoding -- Kima-Hub has no GPU acceleration — pure CPU transcoding +- 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. diff --git a/media/kima-hub/docker-compose.yaml b/media/kima-hub/docker-compose.yaml index 09a98fa..44c3c67 100644 --- a/media/kima-hub/docker-compose.yaml +++ b/media/kima-hub/docker-compose.yaml @@ -1,18 +1,24 @@ services: - kima-hub: + kima: image: ghcr.io/chevron7locked/kima:latest container_name: kima environment: - TZ=${TZ} - - PUID=${PUID} - - PGID=${PGID} - - KIMA_MUSIC_PATH=/music + - 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/config:/app/config - - /mnt/docker-ssd/docker/appdata/kima-hub/data:/app/data - - /mnt/unraid/data/media:/music + - /mnt/docker-ssd/docker/appdata/kima-hub/data:/data + - /mnt/unraid/data/media/music:/music ports: - - "3333:3333" + - "3333:3030" networks: - pangolin extra_hosts: