Self-host Kima

Kima README

How to install Kima

docker run -d \
  --name kima \
  -p 3030:3030 \
  -v /path/to/your/music:/music \
  -v kima_data:/data \
  chevron7locked/kima:latest

MUSIC_PATH, PORT, VERSION, DOCKERHUB_USERNAME

services:
    kima:
        image: chevron7locked/kima:latest
        container_name: kima
        ports:
            - "3030:3030"
        volumes:
            - /path/to/your/music:/music
            - kima_data:/data
        extra_hosts:
            - "host.docker.internal:host-gateway"
        restart: unless-stopped

volumes:
    kima_data:

How to configure Kima

• ACOUSTID_CLIENT_KEY=a shared keyYour own AcoustID key, if you want to lift the shared key's rate limit. Also settable in Settings under AI & Artwork.

  Your own AcoustID key, if you want to lift the shared key's rate limit. Also settable in Settings under AI & Artwork.

• ADMIN_RESET_PASSWORD=unsetSet it and restart to reset an administrator's password. Remove it afterwards, or the password resets again on every start. The reset signs that account out everywhere.

  Set it and restart to reset an administrator's password. Remove it afterwards, or the password resets again on every start. The reset signs that account out everywhere.

• ALLOWED_ORIGINS=unsetComma-separated list of origins allowed to call the API from a browser. Unset means any origin; login still protects the API. The split stack's Compose file sets it to `http://localhost:3000,http://localhost:3030` unless you override it.

  Comma-separated list of origins allowed to call the API from a browser. Unset means any origin; login still protects the API. The split stack's Compose file sets it to `http://localhost:3000,http://localhost:3030` unless you override it.

• AUDIO_ANALYSIS_THREADS_PER_WORKER=1Threads per analysis worker.

  Threads per analysis worker.

• AUDIO_ANALYSIS_WORKERS=2Audio analysis workers, until you set a number in Settings. Each needs about 1 to 1.5 GB of memory, up to 2 to 3 GB at peak.

  Audio analysis workers, until you set a number in Settings. Each needs about 1 to 1.5 GB of memory, up to 2 to 3 GB at peak.

• AUDIO_BRPOP_TIMEOUT=30Seconds the analyzer waits for work before checking again.

  Seconds the analyzer waits for work before checking again.

• AUDIO_MODEL_IDLE_TIMEOUT=300Seconds before an idle analyzer unloads its models. `0` keeps them loaded.

  Seconds before an idle analyzer unloads its models. `0` keeps them loaded.

• CLAP_MODEL_IDLE_TIMEOUT=300Seconds before an idle vibe analyzer unloads its model.

  Seconds before an idle vibe analyzer unloads its model.

• CLAP_THREADS_PER_WORKER=1Threads per vibe embedding worker.

  Threads per vibe embedding worker.

• CLAP_WORKERS=2Vibe embedding workers.

  Vibe embedding workers.

• DATABASE_URL=postgresql://kima:kima@localhost:5455/kimaDatabase Configuration

  Database Configuration

• DISABLE_CLAPCLAP Audio Analyzer (AI vibe/mood matching) Set to 'true' to disable the CLAP embedding analyzer on startup. Useful for low-memory deployments or when AI vibe matching is not needed. Only applies to the all-in-one container (docker-compose.prod.yml). For split containers (docker-compose.yml), simply don't start the audio-analyzer-clap service.

  CLAP Audio Analyzer (AI vibe/mood matching) Set to 'true' to disable the CLAP embedding analyzer on startup. Useful for low-memory deployments or when AI vibe matching is not needed. Only applies to the all-in-one container (docker-compose.prod.yml). For split containers (docker-compose.yml), simply don't start the audio-analyzer-clap service.

• DOCKERHUB_USERNAME=chevron7lockedDockerHub username (for pulling images) Your DockerHub username (same as GitHub: chevron7locked)

  DockerHub username (for pulling images) Your DockerHub username (same as GitHub: chevron7locked)

• KIMA_CALLBACK_URLThe address Lidarr uses to send download events to Kima. Lidarr resolves it, not Kima. Default: http://host.docker.internal:3030 (the all-in-one image's port). Saving the Lidarr settings sends a test event; if Lidarr cannot reach this address, admins get a "Lidarr cannot reach Kima" notification. Same Docker network as the split backend: http://backend:3006 Anything else: an address Lidarr can rea

  The address Lidarr uses to send download events to Kima. Lidarr resolves it, not Kima. Default: http://host.docker.internal:3030 (the all-in-one image's port). Saving the Lidarr settings sends a test event; if Lidarr cannot reach this address, admins get a "Lidarr cannot reach Kima" notification. Same Docker network as the split backend: http://backend:3006 Anything else: an address Lidarr can rea

• KIMA_PUBLIC_VIBEServes one user's library map and live listening to an outside server at /api/public/vibe. Every request needs "Authorization: Bearer <token>".

  Serves one user's library map and live listening to an outside server at /api/public/vibe. Every request needs "Authorization: Bearer <token>".

• KIMA_PUBLIC_VIBE_TOKEN
• KIMA_PUBLIC_VIBE_USER
• LOG_LEVEL=debugLogging level (default: debug in development, warn in production) Options: debug, info, warn, error, silent

  Logging level (default: debug in development, warn in production) Options: debug, info, warn, error, silent

• MUSICBRAINZ_BASE_URLCustom MusicBrainz API base URL (default: https://musicbrainz.org/ws/2) Useful for self-hosted MusicBrainz mirrors to avoid rate limiting

  Custom MusicBrainz API base URL (default: https://musicbrainz.org/ws/2) Useful for self-hosted MusicBrainz mirrors to avoid rate limiting

• MUSIC_PATH=/path/to/your/musicREQUIRED: Path to your music library

  REQUIRED: Path to your music library

• NUM_WORKERSWorker counts are set in Settings (Library Enrichment) and saved in the database; NUM_WORKERS only applies before the first save (default: 2).

  Worker counts are set in Settings (Library Enrichment) and saved in the database; NUM_WORKERS only applies before the first save (default: 2).

• PORT=3030Port to access Kima (default: 3030)

  Port to access Kima (default: 3030)

• REDIS_URL=redis://localhost:6390Redis Configuration The dev Redis from docker-compose.dev.yml listens on 6390.

  Redis Configuration The dev Redis from docker-compose.dev.yml listens on 6390.

• SECURE_COOKIES=falseSet to `true` when Kima is served over HTTPS, so the session cookie is only sent over HTTPS.

  Set to `true` when Kima is served over HTTPS, so the session cookie is only sent over HTTPS.

• SESSION_SECRETSession secret (auto-generated if not set) Generate with: openssl rand -base64 32

  Session secret (auto-generated if not set) Generate with: openssl rand -base64 32

• SETTINGS_ENCRYPTION_KEYEncryption key for sensitive data (API keys, passwords, 2FA secrets) CRITICAL: You MUST set this before starting Kima Generate with: openssl rand -base64 32

  Encryption key for sensitive data (API keys, passwords, 2FA secrets) CRITICAL: You MUST set this before starting Kima Generate with: openssl rand -base64 32

• TRANSCODE_CACHE_MAX_GB=10Size limit for cached transcoded audio.

  Size limit for cached transcoded audio.

• VERSION=latestVersion tag (use 'latest' or specific like 'v1.0.0')

  Version tag (use 'latest' or specific like 'v1.0.0')