Filesystem and mounts

Aurral works with several other applications. It uses their APIs to ask them to search, download, manage, or play music. It also opens the files that those applications write.

A passed API test does not prove file access. Aurral can connect to Lidarr, Navidrome, Plex, or a download client and still fail to read or move files because a mount is wrong.

Without Lidarr, Aurral needs one media mount with the Downloads Folder inside it, such as /data/downloads/aurral. Mount the same folder in your playback server. The Lidarr parts of this page apply only when you connect Lidarr.

Use one path everywhere

Docker containers do not share files automatically. A volume shows one folder from the Docker host inside a container. It does not make a copy.

/srv/media:/data

/srv/media is the folder on the Docker host.
/data is the folder inside the container.

Mount the same host folder at the same container path in every service that shares files:

Aurral          /srv/media:/data
Lidarr          /srv/media:/data
Download client /srv/media:/data
Navidrome       /srv/media:/data:ro

Every service then sees one host file at one path:

Host:       /srv/media/downloads/aurral/track.flac
Aurral:     /data/downloads/aurral/track.flac
Lidarr:     /data/downloads/aurral/track.flac
Navidrome:  /data/downloads/aurral/track.flac

The host side of each mount can differ, if it points to the same host folder. The application uses the container side, so keep that side the same.

Keep a service’s own database or configuration mount separate from the media mount. For example, Navidrome can use /config for its database and /data for media.

How one track moves

A track that Lidarr already has

Aurral asks Lidarr for the track.
Lidarr reports a path such as /data/music/Artist/Album/Track.flac.
Aurral checks that the same path exists in its own container.
Aurral reuses that file. It does not download a second copy.
Navidrome scans /data/music and plays the file.

A new track

Aurral asks a download client to find the track.
The download client writes the completed file under /data/downloads/....
Aurral checks the file and moves it into the Downloads Folder. Permanent tracks go to Artist/Album/Track. Flow tracks go to _flows/<flow-id>/Artist/Album/Track.
Aurral writes playlist artwork and sidecar files under aurral-weekly-flow/_playlists. The Library does not include this folder.
Navidrome scans the Downloads Folder and plays the tracks.

If Aurral writes /data/downloads/aurral/track.flac but Navidrome sees the same host folder as /downloads/track.flac, Navidrome cannot find the track. The API connection still works, but the playlist stays empty or the tracks do not play. Use the same container paths, or follow When paths cannot match.

What each connection needs

Connection	Aurral needs	Filesystem setup
Lidarr	URL, API key, and read access to the files that Lidarr reports	Mount the same media root in Aurral and Lidarr at the same container path.
Download clients	API access and read access to completed downloads	Mount the same media root in Aurral and the client at the same container path.
Navidrome	URL, username, password, and a Navidrome view of the Downloads Folder	Mount the Downloads Folder in Navidrome. If the path differs, add a path mapping for Navidrome.
Plex	Plex account, server URL, and a Plex view of the Downloads Folder	Mount the Downloads Folder in Plex. If the path differs, set Plex Aurral Library path.
Jellyfin	URL, API key, user ID, and a Jellyfin library that contains the Downloads Folder	Mount the Downloads Folder in Jellyfin. If the path differs, add a path mapping for Jellyfin.

The built-in yt-dlp source runs inside Aurral and needs no other container. It writes to /config/_staging first, then moves checked files into the Downloads Folder.

The recommended layout

Choose one folder on the Docker host as the media root. The example uses /srv/media.

/srv/media/                         # Docker host
|-- music/                          # Lidarr root folder
\-- downloads/
    |-- slskd/complete/             # optional Soulseek downloads
    |-- usenet/complete/            # optional SABnzbd or NZBGet downloads
    \-- aurral/                     # Aurral Downloads Folder
        |-- Artist/Album/track      # permanent tracks
        |-- _flows/flow-id/...      # temporary flow tracks
        \-- aurral-weekly-flow/     # playlist sidecar files and artwork

Use the same host folder in every media mount:

Container	Docker volume	Access	Why
Aurral	`${MEDIA_ROOT:-/srv/media}:/data`	read and write	Reads Lidarr and client files. Writes downloads.
Lidarr	`${MEDIA_ROOT:-/srv/media}:/data`	read and write	Reads the library. Moves completed downloads into `/data/music`.
slskd, SABnzbd, or NZBGet	`${MEDIA_ROOT:-/srv/media}:/data`	read and write	Writes completed downloads under `/data/downloads`.
Navidrome	`${MEDIA_ROOT:-/srv/media}:/data:ro`	read only	Scans and plays the library and the Downloads Folder.
Plex	`${MEDIA_ROOT:-/srv/media}:/data:ro`	read only	Scans the Downloads Folder.

MEDIA_ROOT is a host path. /data is a path inside each container. In a Docker volume, the left side is the host and the right side is the container.

For example, the host folder /srv/media/downloads/aurral is /data/downloads/aurral inside Aurral, Lidarr, Navidrome, and Plex.

Enter /data/... paths in application settings. Do not enter /srv/media/... in Aurral, because /srv/media exists only on the host.

Docker mounts

Repeat the media volume for every service that reads or writes media:

services:
  aurral:
    volumes:
      - ${MEDIA_ROOT:-/srv/media}:/data
      - ./config:/config

  lidarr:
    volumes:
      - ${MEDIA_ROOT:-/srv/media}:/data

  download-client:
    volumes:
      - ${MEDIA_ROOT:-/srv/media}:/data

  navidrome:
    volumes:
      - ${MEDIA_ROOT:-/srv/media}:/data:ro

  plex:
    volumes:
      - ${MEDIA_ROOT:-/srv/media}:/data:ro

./config:/config holds Aurral’s database, settings, users, and jobs. Do not share /config with Lidarr, Navidrome, Plex, or a download client.

The containers can use different Docker networks and service URLs. They still need compatible mounts to see the same files.

Set the paths in each application

After you add the mounts, use these container paths:

Application	Setting	Recommended value
Lidarr	Root folder	`/data/music`
slskd	Completed download folder	`/data/downloads/slskd/complete`
SABnzbd or NZBGet	Completed download folder	`/data/downloads/usenet/complete`
Aurral	Settings > Download clients > Downloads Folder > Path	`/data/downloads/aurral`
Navidrome	Aurral library	Aurral creates the library at the Downloads Folder through the API.
Plex	Aurral library	Aurral creates the library through the API, at the path where Plex sees the Downloads Folder.

The folder names for download clients do not matter. These rules do:

The client writes completed files under the shared media mount.
Aurral can read the path that the client reports.
The Downloads Folder is writable by Aurral and mounted in your playback server.

Setup order

Follow this order to check each connection separately.

Choose the host media root, such as /srv/media.
Mount that host folder in Aurral, every download client, your playback server, and Lidarr if you use it.
Use /data/... paths inside the containers. Set the Lidarr root folder and the completed download folders.
Start the services.
If you use Lidarr, open Settings > Lidarr in Aurral. Enter the URL and API key, then select Test connection.
Open Settings > Download clients and set Downloads Folder > Path to a writable folder under /data, such as /data/downloads/aurral.
Connect and test each download client that you use.
Open Settings > Storage health and select Run checks. Fix each failed check.
Open Settings > Playback and connect Navidrome, Plex, or Jellyfin.

Check the connections

Do these checks in order:

API check. The Test connection button for each integration passes.
File check. Settings > Storage health > Run checks passes the Aurral downloads section, and the Lidarr library section if you use Lidarr.

Output check. After a flow or playlist downloads a track, the file exists under one of these paths:

/data/downloads/aurral/Artist/Album/Track.flac
/data/downloads/aurral/_flows/<flow-id>/Artist/Album/Track.flac

Playback check. Your playback server has the Downloads Folder in its own filesystem and scans it.

If the API check passes but the file check fails, do not change the API URL. Fix the volume, the permissions, or the path mapping.

When paths cannot match

Different container paths can work, but each difference needs its own setting. A path mapping translates a path. It does not mount a folder or give access to it.

Paths reported by Lidarr or download clients

Open Settings > Download clients > Remote path mappings and select Add path mapping. Enter:

Applies to: the application that reports the path, such as Lidarr, slskd, NZBGet, SABnzbd, or deemix. Select All sources to apply the mapping to every application.
Remote path: the absolute path that the other application reports.
Local path: the path to the same folder inside Aurral.

Example:

Field	Value
Applies to	Lidarr
Remote path	`/downloads/music`
Local path	`/data/music`

The local path must exist inside the Aurral container. If it does not, add or fix the Docker mount first.

A native Windows service can report a path such as N:\ServerFolders\Music. Mount that host folder in Aurral, then map the Windows path to the Aurral container path. After you save the mapping, run Settings > Storage health > Run checks.

Navidrome sees a different path

Aurral publishes Navidrome playlists through the Subsonic API. If Navidrome sees the Downloads Folder at a different path, add a remote path mapping with Applies to set to Navidrome.

For example, if Aurral sees /data/aurral and Navidrome sees /music-aurral, set Remote path to /music-aurral and Local path to /data/aurral. Both containers must mount the same host folder. Aurral uses the mapping to manage the Aurral Playlists library and publish its tracks. Add another Navidrome mapping if reused Lidarr tracks also have different paths.

Plex sees a different path

Plex Aurral Library path is separate from Remote path mappings.

Open Settings > Playback > Plex.
Set Plex Aurral Library path to the Downloads Folder path as Plex sees it. Do not add /aurral-weekly-flow.
Wait for the setting to save, then select Sync to Plex now.

Example:

Aurral uses	Plex sees	Plex Aurral Library path
`/data/downloads/aurral`	`/music/aurral`	`/music/aurral`

If Aurral and Plex use the same path, leave Plex Aurral Library path blank.

Playback servers report a different path

Before Aurral deletes a file during automatic cleanup, it asks each connected playback server which files its playlists use. If Navidrome, Plex, or Jellyfin reports a different path for the same file, add a remote path mapping with Applies to set to that server. Without the mapping, Aurral cannot tell that the server still uses the file.

Windows and mixed Docker setups

The same rules apply when a service runs on Windows:

Mount the Windows media folder into Aurral.
Add a remote path mapping from the Windows path that Lidarr or the download client reports to the Aurral container path.
If Navidrome also runs on Windows, add the matching folders as Navidrome music libraries.
If Plex sees a different path, set Plex Aurral Library path to the Plex path.

A remote path mapping, a Navidrome library, and Plex Aurral Library path each solve a different problem. One setting cannot replace the others.

Common mistakes

Only the Lidarr music folder is mounted in Aurral. Aurral can read the library but cannot read completed downloads or write to the Downloads Folder.
Only the Downloads Folder is mounted in Navidrome or Plex. The server cannot play reused Lidarr tracks. Mount the Lidarr library too, or add it as a separate library.
Aurral settings use a host path. Aurral needs the container path, such as /data/downloads/aurral.
A path mapping points to a folder that is not mounted. A mapping cannot make a missing folder readable.
A Navidrome or Plex library uses a host path. Each service must use the path inside its own container, such as /data/downloads/aurral or /music/aurral.

For permissions and hardlinks, see the Servarr Docker Guide.

Next: First run