One container, one port, one media path

Before you start

You need three things, and only two of them are prerequisites.

• A media path that contains your music, or will contain it. Aurral reads and writes there.
• A port, free on the host. The example uses 3001.
• A download client — only if you want Flows to fetch music. You can browse and play without one.

Lidarr is optional at every stage. It is not a dependency, and nothing in the setup below requires it.

Step 1: the compose file

services:
  aurral:
    image: ghcr.io/leonadavinci/aurral:latest
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - ${MEDIA_ROOT:-/srv/media}:/data
      - ./config:/config

Set MEDIA_ROOT to the host path where your music lives. The container path on the right side of the volume mapping should be /data and should be the same container path your music server uses for the same host directory. That matching is what lets Aurral read files that Navidrome or Lidarr wrote.

Step 2: PUID and PGID

These exist so files Aurral writes on disk belong to the user you already are on the host. Find your IDs with id -u and id -g, set them, and everything Aurral downloads is readable and movable by your normal user. Skipping this is why some people end up with files their media server can read but their file manager cannot.

Step 3: start it

docker compose up -d

Then open http://localhost:3001 and create the admin account. That account is the only one that can reach settings, so do it first.

Step 4: the first-run wizard

The wizard sets the Downloads Folder, offers to connect Lidarr, and establishes display preferences. You can decline Lidarr and connect it much later. Connecting or disconnecting Lidarr never moves music: Aurral stops monitoring artists when you connect, and keeps the albums it downloaded until Lidarr takes them over.

Step 5: index the library

Open Library and choose Refresh, then Quick scan. Quick scan checks every folder, reads new and changed files, and marks missing files unavailable. Use Full scan when you have retagged files without changing their size or modification time, or when a quick scan cannot fix stale metadata. A full scan re-reads every file and can take a long time on a large library, but it keeps running if you close the page.

After the first scan Aurral does not run scheduled full scans again. It watches the folders it knows and reads only what changed, skipping files whose size and modification time are identical. Directories such as _playlists, _staging, _fallback, _flows and hidden folders are ignored.

If files do not appear, run the storage checks in settings before anything else. They report the exact path Aurral is failing on, which in mixed Windows and Docker setups is usually a host-versus-container path mismatch that a remote path mapping fixes.

Step 6: connect a download client

This is what turns recommendations into files. Add one of slskd, yt-dlp, deemix, SABnzbd or NZBGet and set a source priority order. That order decides which client is asked first, and it also decides which clients are consulted for quality upgrades.

Step 7: connect a playback server

Optional. Aurral plays in the browser on its own. Connecting Navidrome, Plex or Jellyfin lets Flows publish themselves as playlists so they appear in your existing apps. Playlist naming differs per server, which is worth knowing before you create several.

Step 8: create a Flow

Flows live in the sidebar. Create one, set the track count, choose the days and hour it may run, set the source mix, and switch it on. Nothing happens until the first scheduled slot.

A good first configuration: 30 tracks, one day a week, Discover and Library at half each, Deep Dive on. That combination is a reasonable starting point that will not feel repetitive.

Where to go when something is wrong

Almost every first-install problem is one of four things: the media path does not match between containers, PUID and PGID are wrong so files are unreadable, the port in the browser is not the port you mapped, or the first scan has not finished yet. Settings has a storage health section that checks storage, downloads, Lidarr files, path mappings and playback in one pass.