fizzlepoof/truenas-stacks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Align Kima Hub stack with live deployment

Browse Source
This commit is contained in:
Fizzlepoof
2026-05-15 03:08:03 +00:00
parent 5783963816
commit ff2e13a16f
2 changed files with 107 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
docs/planning/DEPLOY_KIMA_HUB.md
View File

@@ -1,91 +1,125 @@
# Kima-Hub Deployment Plan # Kima-Hub Deployment / Repair Reference
**Host:** PlausibleDeniability (PD) **Host:** PlausibleDeniability (PD)
**Port:** 3333 **Stack dir in repo:** `media/kima-hub/`
**Stack dir:** `/mnt/docker-ssd/docker/compose/media-extra/` **Live stack dir on host:** `/mnt/docker-ssd/docker/compose/media/kima-hub/`
**Status:** Pending **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) ## Canonical live `.env` shape
- [ ] 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`
## 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 ```yaml
services: services:
kima-hub: kima:
image: chevron7locked/kima:latest image: ghcr.io/chevron7locked/kima:latest
container_name: kima-hub container_name: kima
restart: unless-stopped
ports:
- "3333:3030"
volumes:
- /mnt/tank/docker/appdata/kima-hub:/data
- /mnt/unraid/data/media/music:/music:ro
environment: environment:
- TZ=${TZ} - TZ=${TZ}
healthcheck: - SESSION_SECRET=${SESSION_SECRET:-}
test: ["CMD-SHELL", "cat /proc/net/tcp6 | grep -q 0BD6 || exit 1"] - SETTINGS_ENCRYPTION_KEY=${SETTINGS_ENCRYPTION_KEY:-}
interval: 30s - KIMA_CALLBACK_URL=${KIMA_CALLBACK_URL:-http://host.docker.internal:3333}
timeout: 10s - DISABLE_CLAP=${DISABLE_CLAP:-}
retries: 3 - 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: networks:
- pangolin - pangolin
extra_hosts:
- "host.docker.internal:host-gateway"
restart: unless-stopped
networks: networks:
pangolin: pangolin:
external: true external: true
``` ```
> **Note:** Internal port is `3030`, mapped to `3333` on the host. Hex `0BD6` = port 3030 for healthcheck. ## Validate before deploy
> **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
```bash ```bash
cd /mnt/docker-ssd/docker/compose/media-extra cd /mnt/docker-ssd/docker/compose/media/kima-hub
sudo docker compose --env-file .env config # validate sudo docker compose --env-file .env config
sudo docker compose --env-file .env up -d
sudo docker logs kima-hub --tail 30
``` ```
## Post-Deploy ## Deploy / repair
1. Open `http://10.5.1.6:3333` and create your account ```bash
2. Point Kima at your music directory (`/music`) cd /mnt/docker-ssd/docker/compose/media/kima-hub
3. In Lidarr: Settings → Connect → add Kima-Hub webhook sudo docker compose --env-file .env up -d
4. In Audiobookshelf: verify Kima can reach it at `http://10.5.1.6:13358` sudo docker compose --env-file .env ps
5. Add Pangolin resource: `kima.paccoco.com` → port 3333 sudo docker logs --tail 60 kima
```
## Pangolin Resource ## Post-deploy checks
Add in Pangolin dashboard: 1. Open `http://10.5.1.6:3333`
- **Subdomain:** `kima.paccoco.com` 2. Confirm the app starts and initial setup loads
- **Target:** `http://10.5.1.6:3333` 3. Confirm `/music` is visible to Kima
- **Auth:** Enable (personal use only) 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 | ## Optional integrations / secrets
|------|------|--------|
| `/mnt/tank/docker/appdata/kima-hub` | tank | Config, DB, playlists — not write-heavy | Not required just to boot:
| `/mnt/unraid/data/media/music` | Unraid NFS (read-only) | Source library stays on Serenity |
- **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 ## Notes
- NFS mount must be up before starting (`sudo bash /mnt/tank/docker/scripts/mount-unraid-nfs.sh`) - 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.
- If you transcode on the fly, CPU load on PD will spike; Kima-Hub is CPU-bound for transcoding - KitchenOwl already lives in the `home/` stack; Kima lives in its own `media/kima-hub/` stack.
- Kima-Hub has no GPU acceleration — pure CPU transcoding - Keep compose-managed runtime under `/mnt/docker-ssd/docker/compose/...` per SOP.

22
media/kima-hub/docker-compose.yaml
View File

@@ -1,18 +1,24 @@
services: services:
kima-hub: kima:
image: ghcr.io/chevron7locked/kima:latest image: ghcr.io/chevron7locked/kima:latest
container_name: kima container_name: kima
environment: environment:
- TZ=${TZ} - TZ=${TZ}
- PUID=${PUID} - SESSION_SECRET=${SESSION_SECRET:-}
- PGID=${PGID} - SETTINGS_ENCRYPTION_KEY=${SETTINGS_ENCRYPTION_KEY:-}
- KIMA_MUSIC_PATH=/music - 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: volumes:
- /mnt/docker-ssd/docker/appdata/kima-hub/config:/app/config - /mnt/docker-ssd/docker/appdata/kima-hub/data:/data
- /mnt/docker-ssd/docker/appdata/kima-hub/data:/app/data - /mnt/unraid/data/media/music:/music
- /mnt/unraid/data/media:/music
ports: ports:
- "3333:3333" - "3333:3030"
networks: networks:
- pangolin - pangolin
extra_hosts: extra_hosts: