Self-hosted music discovery and request management for Lidarr with library-aware recommendations, granular monitoring controls, and optional Weekly Flow playlists powered by Soulseek + Navidrome.

• Search for artists via MusicBrainz and add them to Lidarr with the monitoring behavior you want
• Browse your existing library in a clean UI
• Discover new artists using recommendations derived from your library and (optionally) Last.fm
• Track requests and download/import progress
• Generate weekly playlists and download the tracks into a separate “Weekly Flow” library

Aurral is designed to be safe for your collection: it does not write into your main music library directly. Library changes go through Lidarr’s API, and Weekly Flow writes into its own directory.

Create a docker-compose.yml:

services:
  aurral:
    image: ghcr.io/lklynet/aurral:latest
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      - DOWNLOAD_FOLDER=${DL_FOLDER:-./data/downloads}
    volumes:
      - ${DL_FOLDER:-./data/downloads}:/app/downloads
      - ${STORAGE:-./data}:/app/backend/data

You can optionally set DL_FOLDER and STORAGE in a .env file next to your compose file. If you leave them unset, Aurral uses ./data/downloads and ./data.

Start it:

docker compose up -d

Open: http://localhost:3001

• Lidarr (reachable from Aurral)
• Last.fm API key (api key required, username needed for scrobbling)
• A MusicBrainz contact email (used for the MusicBrainz User-Agent policy)

• Lidarr Nightly
• Tubifarry
• slskd
• Navidrome

• Navidrome (optional but recommended if you want playlist/library integration)
• A downloads directory mounted into the container (for the Weekly Flow library)

• Daily Discover recommendations based on your library, tags, and trends

• Add artists with granular monitor options (None / All / Future / Missing / Latest / First)
• Add specific albums from release groups
• Library view with quick navigation into artist details
• Request tracking with queue/history awareness

Weekly Flow generates playlists from your library and listening context, then downloads tracks via a built-in Soulseek client into a dedicated folder.

• Multiple flows with adjustable mix (Discover / Mix / Trending) and size
• Automatic weekly refresh scheduling
• Optional Navidrome smart playlists and a dedicated “Aurral Weekly Flow” library

Mount a downloads folder for Weekly Flow and optional Navidrome integration:

• Container path: /app/downloads
• Weekly Flow output: /app/downloads/aurral-weekly-flow/<flow-id>/<artist>/<album>/<track>

Aurral does not write to your root music folder directly. Changes to your main collection happen via Lidarr (add/monitor/request/import).

If you want Weekly Flow to appear as a separate library inside Navidrome:

1. In Aurral: Settings → Integrations → Navidrome (URL, username, password)
2. Ensure your compose config maps a host folder into /app/downloads
3. Set DL_FOLDER once and use it for both DOWNLOAD_FOLDER and the /app/downloads volume

Example:

• DL_FOLDER=/data/downloads/tmp
• Volume: ${DL_FOLDER}:/app/downloads
• Env: DOWNLOAD_FOLDER=${DL_FOLDER}

Aurral will:

• Create a Navidrome library pointing to <DOWNLOAD_FOLDER>/aurral-weekly-flow
• Write smart playlist files (.nsp) into the Weekly Flow library folder

Navidrome should be configured to purge missing tracks so Weekly Flow rotations don’t leave stale entries:

• ND_SCANNER_PURGEMISSING=always (or full)

Aurral uses local user accounts created in onboarding. Authentication is HTTP Basic Auth at the API layer. Use HTTPS when exposing it publicly.

If you forget your admin password, you can reset it from the terminal:

npm run auth:reset-admin-password -- --password "new-password"

Or generate a random password:

npm run auth:reset-admin-password -- --generate

The -- after npm run auth:reset-admin-password tells npm to pass the remaining flags to the reset script.

If you want SSO, place Aurral behind an auth-aware reverse proxy and forward the authenticated username in a header.

Environment variables:

AUTH_PROXY_ENABLED=true
AUTH_PROXY_HEADER=X-Forwarded-User
AUTH_PROXY_TRUSTED_IPS=10.0.0.1,10.0.0.2
AUTH_PROXY_ADMIN_USERS=alice,bob
AUTH_PROXY_ROLE_HEADER=X-Forwarded-Role
AUTH_PROXY_DEFAULT_ROLE=user

If you are behind a reverse proxy, set TRUST_PROXY so Aurral interprets X-Forwarded-* correctly:

TRUST_PROXY=true

Most configuration is done in the web UI, but some settings are controlled by environment variables.

• Lidarr connection fails: confirm Lidarr URL is reachable and API key is correct (Settings → Integrations → Lidarr)
• Discovery looks empty: add some artists to Lidarr and/or configure Last.fm; initial discovery refresh can take a bit
• MusicBrainz is slow: MusicBrainz is rate-limited; Aurral respects it and may take longer on first runs
• Weekly Flow does not show in Navidrome: verify DOWNLOAD_FOLDER matches your host path mapping and Navidrome purge settings
• Permission errors writing ./data: set PUID/PGID to match your host directory ownership

• Community + questions: https://discord.gg/cpPYfgVURJ
• Troubleshooting + help: https://github.com/lklynet/aurral/discussions
• Bugs + feature requests: https://github.com/lklynet/aurral/issues