Setting up
Installing Aurral for the First Time
Aurral installs in a few minutes if the media path is right, and becomes a frustrating afternoon if it is not. This page is the whole path in the order that avoids problems.
Before anything else, check one thing
Compare the media path your music server container uses with what you plan to use for Aurral. If they match, the rest is routine. If they do not, fix that first, because it is the source of nearly every first-install problem and it is much harder to diagnose later with a partially working install.
Both containers should see the same host directory at the same container path, typically /data.
| Host path | Container path in Aurral | Container path in your music server |
|---|---|---|
| /srv/media | /data | /data |
| D:/media | /data | /data |
| /mnt/user/media | /data | /data |
Step 1: compose file
Write one docker-compose.yml. The image, one port, PUID and PGID, and two volumes: the media path and a config directory that persists your settings and database.
Step 2: PUID and PGID
Run id -u and id -g on the host and put those numbers in. This is what makes downloaded files belong to you rather than to root. Skipping it produces files your media server can read but your file manager cannot, which is a confusing symptom to diagnose later.
Step 3: start and create the admin
docker compose up -d, then open the mapped port and create the admin account. That account is the only one that reaches settings, so create it first if more than one person will use the server.
Step 4: the first-run wizard
Set the Downloads Folder, decide about Lidarr, and pick display preferences. You can decline Lidarr here and connect it months later. Connecting or disconnecting never moves files.
Step 5: index the library
Library, then Refresh, then Quick scan. It reads tags and MusicBrainz IDs off every file it can reach. On a large library this takes a while once, and then it only scans what changed afterwards.
If nothing appears, do not proceed to the next step. Run the storage checks in settings first. They report the exact path that failed.
- Open Library and choose Refresh.
- Run a Quick scan first; it reads new and changed files.
- Use Full scan only if you retagged files without changing size or modification time.
- If a track shows as unavailable, its file is missing rather than its metadata being wrong.
Step 6: add a download client
This is what turns recommendations into files. Add slskd, yt-dlp, deemix, SABnzbd or NZBGet and set the source priority. Without one, a Flow can only reuse what you already own.
Step 7: add a playback server, optionally
Navidrome, Plex or Jellyfin lets Flows publish as playlists. Skip it if the browser player is enough. Adding it later needs no reinstall.
Step 8: your first Flow
Pick 30 tracks, one day a week, half Discover and half Library, Deep Dive on. Switch it on and wait for the first scheduled run. Nothing happens until then, which is normal rather than broken.
Frequently asked questions
Do I need Lidarr before starting?
No. Aurral manages artists and albums itself when Lidarr is absent, and connecting Lidarr later moves management without moving files.
The library is empty after the scan. What now?
Run the storage checks in settings. They name the exact path that failed, which is nearly always a media path mismatch or a permissions problem.
How long does a first scan take?
It reads tags off every file, so it scales with size. A few thousand tracks takes a couple of minutes. After that only changed files are read.
My Flow ran and produced nothing. Why?
Either no download client is configured, or every candidate was already in your library and filtered out. Check Activity to see whether searches were attempted.
Ready to set it up
One container and one media path is genuinely all it takes. Everything else in this page is something you add when the need appears.