DroppedNeedle stores its configuration in config/config.json inside the mapped config volume. Almost everything is managed through the web UI. The only things that must be set at container level are the environment variables below.

Environment variables

Unraid and NAS users: if you see chown: Operation not permitted at startup, your volume mounts are on a filesystem that rejects ownership changes (FUSE/shfs, NFS, CIFS). The container skips chown when the directories are already writable, so this is usually harmless as long as the host paths are owned by the correct UID/GID.

In-app settings

All of the following are configured through the DroppedNeedle web UI. No config files or additional environment variables are needed.

Library

Settings > Library

• Library paths (in-container paths, for example /music)
• Naming template for imported files (see Native Engine for template variables and the default)
• Scan schedule
• AcoustID API key (optional; enables Tier-3 fingerprint identification)
• Quality tiers and verification options

Download client

Settings > Download Client (admin only)

• slskd URL (for example http://slskd:5030)
• slskd API key
• Test and Save buttons
• Downloads-mount health indicator (set, exists, writable, same filesystem)

Playback sources

Each source is configured independently:

Scrobbling and discovery

Admin, once per instance:

• Last.fm app key and shared secret, via Settings > Last.fm. Register an app at last.fm/api/account/create.

Each user, from their profile:

• Profile > Scrobbling & Discovery: connect Last.fm (OAuth) and ListenBrainz (paste token from listenbrainz.org/profile), per-service scrobble toggles, default discovery source.

Authentication

Settings > Security and Settings > Users (admin only)

• Username/password login: on by default
• Jellyfin login: toggle on/off
• Plex login: toggle on/off
• OIDC provider: Issuer URL, Client ID, Client Secret. The redirect URI to register in your provider is https://your-droppedneedle-url/api/v1/auth/oidc/callback. Works with Authelia, Keycloak, Authentik, and any provider that supports the authorization code flow.
• User management: roles (Admin/Trusted/User), user import from Jellyfin or Plex
• Sessions: 30 days from login, not extended by activity

Security

Settings > Security (admin only)

HIBP password breach checking: checks new passwords against the Have I Been Pwned database using the k-anonymity API (only the first 5 characters of the password’s SHA-1 hash are sent; the full password never leaves the server). On by default. Can be disabled, or pointed at a local offline copy of the HIBP hash file for air-gapped installs (download the “ordered by hash” version from haveibeenpwned.com/Passwords).

HSTS: optional Strict-Transport-Security header. Only relevant when serving DroppedNeedle over HTTPS via a reverse proxy. Leave disabled for plain HTTP. Enabling it on HTTP will cause browsers to refuse to connect until the HSTS entry expires.

API keys: stored encrypted, masked on settings reads, never written to logs.

Advanced

Settings > Advanced

• AudioDB toggle, proxied vs. direct CDN loading, name-based search fallback for niche artists, cache TTLs
• Home page layout preferences (Settings > Preferences)

Volumes

Map /app/config and /app/cache to persistent host directories so they survive container restarts.

REST API

Interactive documentation (Swagger UI) is at /api/v1/docs on your DroppedNeedle instance. The raw OpenAPI spec is at /api/v1/openapi.json.

All /api/v1/* routes require authentication, except a small public allowlist covering setup, login, and provider discovery. Routes under /api/v1/settings/* additionally require the Admin role. Auth is via a Bearer token in the Authorization header, or the droppedneedle_session cookie set on login.

A health check endpoint is at /health.

See the API Reference for full endpoint documentation.