# 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.