Documentation

Everything you need to deploy, configure, and extend Crate.

Overview

Crate is a self-hosted music manager for collectors. It connects to music metadata providers (MusicBrainz, Deezer, or your own) to search and browse artists, then downloads tracks from Soulseek via slskd. Downloaded files are automatically organized, tagged with full metadata and cover art, and placed in your library.

The stack is a Go backend with SQLite, a React frontend, and standalone gRPC provider binaries — all shipped in a single Docker image.

Deployment

The recommended deployment is via Docker Compose with slskd as a sidecar. Crate needs a Soulseek account (provided through slskd) to download music.

# docker-compose.yml
services:
  crate:
    image: ghcr.io/theoutdoorprogrammer/crate:latest
    ports:
      - "6969:6969"
    volumes:
      - ./crate-data:/app/data        # databases (crate.db, cache.db, activity.db)
      - ./slskd/downloads:/app/downloads
      - ./library:/app/library
    environment:
      - CRATE_SLSKD_URL=http://slskd:5030
      - CRATE_SLSKD_API_KEY=your_api_key
      - CRATE_DOWNLOADS_DIR=/app/downloads
      - CRATE_LIBRARY_PATH=/app/library
      - CRATE_DB_PATH=/app/data/crate.db
      - CRATE_CACHE_PATH=/app/data/cache.db
      - CRATE_ACTIVITY_PATH=/app/data/activity.db
    depends_on:
      - slskd
    restart: unless-stopped

  slskd:
    image: slskd/slskd:latest
    ports:
      - "5030:5030"
    volumes:
      - ./slskd:/app
      - ./library:/crate
    environment:
      - SLSKD_REMOTE_CONFIGURATION=true
      - SLSKD_API_KEY=your_api_key
      - SLSKD_SOULSEEK_USERNAME=your_username
      - SLSKD_SOULSEEK_PASSWORD=your_password
    restart: unless-stopped

Volumes

Three volume mounts are important:

• Data directory — where Crate stores its SQLite databases. Map to a persistent path.
• Downloads directory — shared with slskd. Crate reads completed downloads from here. Must be the same path slskd writes to.
• Library directory — where organized, tagged music files end up. Point your media server (Navidrome, Plex, etc.) here.

Authentication

Crate does not include built-in authentication. It's designed to run behind your existing auth layer — a reverse proxy with basic auth, Authelia, Authentik, Cloudflare Access, a VPN, or whatever you prefer. If it's only accessible on your local network, no auth may be necessary.

Environment Variables

These are set at startup and control core paths, ports, and provider configuration. All have sensible defaults — only CRATE_SLSKD_API_KEY is required.

UI Settings

These settings are stored in the database and configurable from the Settings page in the web UI. Changes take effect immediately without restarting.

Providers

Providers supply music metadata (artist search, discography browsing, album/track details, cover art). Crate ships with two built-in providers and supports adding custom ones via gRPC.

Built-in Providers

How Providers Work

• Default provider — set in settings as provider_primary. Used for search and browse unless the user switches providers in the search UI.
• Entity tracking — every artist, album, and track stores which provider and provider ID it came from. This is how Crate knows where to check for new releases.
• Provider switching — you can change the default provider at any time. Existing entities keep their original provider association.
• Relinking — any entity can be relinked to a different provider via the API. Useful if you switch primary providers and want to unify your library.
• Orphan detection — if a provider goes offline, entities from that provider show as “orphaned” in the UI.
• Caching — provider responses are cached in a separate SQLite database (cache.db) with configurable TTL. The cache can be cleared from the Settings page.

Provider Configuration

The CRATE_PROVIDERS environment variable defines which providers to load. Format:

# Built-in providers (binary path relative to crate binary)
CRATE_PROVIDERS=musicbrainz:./provider-musicbrainz:50051,deezer:./provider-deezer:50052

# External provider (network address instead of binary path)
CRATE_PROVIDERS=musicbrainz:./provider-musicbrainz:50051,spotify:external:192.168.1.10:50053

Built-in providers are started as child processes by Crate. External providers connect to a remote gRPC server you run separately.

Download Flow

When you watch an artist, album, or track, here's what happens:

1. Queuing — watched items are saved with status wanted. The scheduler checks for new wanted tracks every scan interval.
2. Search — Crate searches slskd (Soulseek) for each wanted track, scoring results by quality tier, file format, and bitrate.
3. Selection — the best result is selected based on your quality tiers. Blacklisted sources are excluded.
4. Download — the file is downloaded via slskd. Track status changes to downloading. The downloader checks progress every 10 seconds.
5. Organize — completed downloads are moved into the library with the naming convention Artist/Album/Track.ext.
6. Tag — metadata (artist, album, track name, track number, year) and cover art are embedded into the file.
7. Notify — if Navidrome is configured, a library scan is triggered. Track status becomes owned.

Retry & Blacklist

Not every download succeeds on the first try. Crate handles failures automatically:

• No results — track stays wanted. The scheduler will try again on the next cycle.
• Transfer failure (rejected, errored, cancelled) — the specific username + filename pair is blacklisted. Future searches skip that source but can still find the track from other users.
• Retry backoff — failed downloads retry with increasing delays: 5m → 15m → 30m → 1h. After 4 attempts (~2 hours), the track reverts to wanted for the next scheduler cycle.

Concurrency

The max_concurrent_slskd setting (default 10) limits how many downloads run simultaneously. The max_auto_queue setting (default 50) caps how many tracks the scheduler adds per cycle, preventing the queue from growing unbounded.

Quality Upgrades

Crate continuously improves your library quality. The quality system works as follows:

1. Quality tiers are priority-ordered in settings (default: FLAC > MP3 320 > MP3 256). Higher in the list = better.
2. When a track is downloaded, its format and bitrate are recorded.
3. The scheduler scans one artist per day (round-robin), checking if any owned tracks can be upgraded to a higher quality tier.
4. Upgradeable tracks are re-queued automatically. The new download replaces the old file.

The requeue_cooldown_days setting (default 7) prevents the scheduler from re-queuing the same track too frequently if better quality isn't available yet.

Navidrome Integration

Crate can trigger a Navidrome library scan after each successful download, so new music appears in your streaming library immediately.

Setup

Configure these three settings in the Crate UI (Settings page):

All three fields are required. If any are empty, the Navidrome integration is silently disabled. Crate authenticates via the Subsonic API token+salt scheme.

Supported Formats

The downloader recognizes all these formats when scoring search results. The tagger embeds metadata into FLAC (Vorbis comments) and MP3 (ID3v2) files. Cover art is embedded in both formats.

API Reference

Crate exposes a REST API on the same port as the web UI. All endpoints return JSON.

Status

Search & Browse

Library

Watching

Downloads

Providers

Settings & Activity

Custom Providers

You can build your own metadata provider by implementing the gRPC service defined in proto/provider/provider.proto. The service interface includes:

• SearchArtists — search by name, return ranked results
• GetArtist — full artist details with discography
• GetAlbum — album details with track listing
• GetTrack — individual track details

Run your provider as a standalone gRPC server and add it to the CRATE_PROVIDERS env var:

CRATE_PROVIDERS=musicbrainz:./provider-musicbrainz:50051,my-provider:external:my-host:50053

Use the external keyword as the binary path to tell Crate it should connect to a remote server instead of launching a child process. Community-built providers and the database schema are documented in DATABASE.md.

Database

Crate uses three SQLite databases:

• crate.db — main database. Artists, albums, tracks, settings, download queue, blacklist. WAL mode, single writer connection. Schema migrations via goose (embedded SQL files, run automatically on startup).
• cache.db — provider response cache with TTL. Can be safely deleted to force re-fetching, or cleared from the Settings page.
• activity.db — event log. Download completions, errors, scheduler actions. Auto-pruned based on activity_retention_days.

The full database schema is documented in DATABASE.md in the repository.