Getting Started

DeepCrate is a self-hosted music discovery pipeline. It surfaces music through your listening history and existing collection, lets you preview and approve recommendations, then downloads via Soulseek.

Prerequisites

• Docker and Docker Compose
• slskd running with API enabled
• Subsonic-compatible server (Navidrome, Gonic, Airsonic, etc.) for catalog discovery
• ListenBrainz account + Last.fm API key

Installation

1. Create configuration

mkdir -p deepcrate/data && cd deepcrate

Create config.yaml:

listenbrainz:
  username: "your_username"

slskd:
  host: "http://slskd:5030"
  api_key: "your_api_key"

catalog_discovery:
  enabled: true
  subsonic:
    host: "http://subsonic-server:4533"
    username: "your_username"
    password: "your_password"
  lastfm:
    api_key: "your_lastfm_api_key"

ui:
  auth:
    enabled: true
    username: "admin"
    password: "changeme"

See the Configuration guide for all options.

2. Run with Docker Compose

Create docker-compose.yaml:

services:
  deepcrate:
    image: ghcr.io/jordojordo/deepcrate:latest
    container_name: deepcrate
    volumes:
      - ./config.yaml:/config/config.yaml:rw
      - ./data:/data
    ports:
      - "8080:8080"
    restart: unless-stopped

docker compose up -d

3. Access the UI

Open http://localhost:8080 and log in with your configured credentials.

Minimal Configuration

The bare minimum to run DeepCrate with ListenBrainz only:

listenbrainz:
  username: "your_username"
  # token not required for weekly_playlist mode (default)

slskd:
  host: "http://slskd:5030"
  api_key: "your_api_key"

How It Works

Your Library ──┐
               ▼
Scrobbles ──> Discovery ──> Preview & Approve ──> Soulseek
                                                     │
                                                     └──> Your Library

1. Discovery jobs run on schedule -- ListenBrainz every 6 hours, catalog discovery weekly, slskd downloader hourly
2. Discovered albums go to the queue with status pending
3. Web UI shows pending items for manual approval or rejection, with 30-second audio previews
4. Approved items go to the wishlist for download via slskd

Development

git clone https://github.com/jordojordo/deepcrate.git && cd deepcrate
pnpm install && pnpm dev  # Starts on http://localhost:5173

See CONTRIBUTING.md for guidelines.

Next Steps

• Configuration Reference -- All configuration options
• Authelia Integration -- Advanced authentication with SSO/2FA
• Architecture -- How the system works internally
• API Reference -- Interactive API explorer