Align Kima Hub stack with live deployment
This commit is contained in:
Fizzlepoof
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user