Documentation

DroppedNeedle runs as a single Docker container. You bring a music folder and a running slskd instance; DroppedNeedle handles the rest: scanning your library, searching for releases, importing downloads, and serving a web player.

Before you start, make sure you have Docker, a directory for your music library, and a working slskd 0.25.0+ instance with a Soulseek account, at least one shared folder, and an API key configured. If you haven’t set slskd up yet, read slskd Setup first.

Prerequisites

  • Docker (with Compose v2)
  • A writable directory for your music library on the host
  • A running slskd instance (0.25.0+) reachable from the DroppedNeedle container, with:
    • A Soulseek account configured
    • At least one shared folder (slskd.yml -> shares.directories)
    • An API key (slskd.yml -> web.authentication.api_keys)

docker-compose.yml

services:
  droppedneedle:
    image: ghcr.io/habirabbu/droppedneedle:latest
    container_name: droppedneedle
    environment:
      - PUID=1000
      - PGID=1000
      - PORT=8688
      - TZ=Etc/UTC
      - SLSKD_DOWNLOADS_PATH=/slskd-downloads
    ports:
      - "8688:8688"
    volumes:
      - ./config:/app/config
      - ./cache:/app/cache
      - /path/to/music:/music:rw
      - /path/to/slskd/downloads:/slskd-downloads:rw
    restart: unless-stopped

Replace /path/to/music with your actual music library path and /path/to/slskd/downloads with the directory slskd writes finished downloads into. Both must be on the same filesystem. See slskd Setup for why this matters.

Run id on your host to find the correct PUID and PGID values for your user. The image is also available on Docker Hub as habirabbu/droppedneedle:latest.

Start the container

docker compose up -d

First-run setup

Open http://localhost:8688. On first launch DroppedNeedle prompts you to create an admin account (username and password; email is optional). This only happens once.

After that, work through four steps in the web UI:

1. Add your library path. Go to Settings > Library and add your music directory using its in-container path (for example /music). DroppedNeedle validates the path and reports any access issues immediately.

2. Configure the download client. Go to Settings > Download Client. Enter your slskd URL (for example http://slskd:5030) and the API key you created in slskd. Click Test, then Save. The page shows the downloads-mount health; confirm it reads “set, exists, writable, same filesystem” before continuing.

3. Connect streaming and scrobbling services. Optionally connect Jellyfin, Navidrome, Plex, local files, or YouTube for playback. Connect ListenBrainz or Last.fm from your profile to enable scrobbling and personalised discovery. All of this is in-app; no extra environment variables are needed.

4. Run a library scan. On Settings > Library, click Scan. The scan walks your paths, identifies files through a four-tier identification strategy, and populates the library. Progress streams live. Files that can’t be confidently identified go into a manual-review queue for you to resolve.

Make a request

Browse or search the MusicBrainz catalogue, open an album, and click Request. You can also request a single track from an album’s tracklist.

Watch the Downloads page: the task steps through searching -> downloading -> processing -> completed live over SSE. When it finishes, the files appear under Library.

Admin and Trusted users’ requests start immediately. Standard User requests wait for admin approval first.

Next steps

  • Native Engine: how identification, scoring, and import work under the hood
  • slskd Setup: detailed slskd configuration and the downloads bind-mount requirement
  • Configuration: all environment variables and in-app settings