126 lines
4.0 KiB
Markdown
126 lines
4.0 KiB
Markdown
# 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
|
|
|
|
```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:
|
|
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
|
|
|
|
```bash
|
|
cd /mnt/docker-ssd/docker/compose/media/kima-hub
|
|
sudo docker compose --env-file .env config
|
|
```
|
|
|
|
## Deploy / repair
|
|
|
|
```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
|
|
```
|
|
|
|
## Post-deploy checks
|
|
|
|
1. Open `http://10.5.30.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
|
|
|
|
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.
|