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 a download client and still fail to read or move files because a mount is wrong.

Aurral needs one media mount with the Library folder inside it, such as /data/downloads/aurral. Mount the same folder in your media server. A read-only folder, such as a Lidarr root folder, needs a mount too.

Caution

Use one shared media mount, with the same container path in every service that shares files. Use path mappings only when you cannot use the same path.

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
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
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 in a read-only folder

1. Aurral scans the read-only folder, such as /data/music, and finds /data/music/Artist/Album/Track.flac.
2. A playlist or flow that wants the track uses that file. Aurral does not download a second copy.
3. Navidrome scans /data/music and plays the file.

A new track

1. Aurral asks a download client to find the track.
2. The download client writes the completed file under /data/downloads/....
3. Aurral checks the file and moves it into the Library folder. Permanent tracks go to Artist/Album/Track. Flow tracks go to _flows/<flow-id>/Artist/Album/Track.
4. Aurral writes a playlist file and artwork for each flow and static playlist under _playlists. The Library does not include this folder.
5. Navidrome scans the Library folder, imports the playlist files, and plays the tracks.

Playlist files list each track by its full path in Aurral, such as /data/downloads/aurral/Artist/Album/Track.flac or /data/music/Artist/Album/Track.flac. A media server finds the tracks only when it sees those folders at the same paths.

What each connection needs

Connection	Aurral needs	Filesystem setup
Read-only folders	Read access to the folder	Mount the folder in Aurral.
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.
Media servers	Nothing. Navidrome, Plex, and Jellyfin read the Library folder themselves.	Mount the Library folder and your read-only folders at the same container paths as Aurral.

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 Library 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/                          # optional read-only folder, such as a Lidarr root folder
\-- downloads/
    |-- slskd/complete/             # optional Soulseek downloads
    |-- usenet/complete/            # optional SABnzbd or NZBGet downloads
    \-- aurral/                     # Aurral Library folder
        |-- Artist/Album/track      # permanent tracks
        |-- _flows/flow-id/...      # temporary flow tracks
        \-- _playlists/             # playlist 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 client files and read-only folders. Writes downloads.
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 Library folder.
Plex	${MEDIA_ROOT:-/srv/media}:/data:ro	read only	Scans the Library 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, 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

  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 a media server or a download client.

Mount a read-only folder

A read-only folder is music that Aurral indexes but never changes. Mount it in Aurral with :ro, at a path outside the Library folder:

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

Then add /music in Settings > Library > Read-only folders. To pick it with Browse folders, set FILE_BROWSE_ROOTS=/data,/music. You can also type the path.

Aurral plays the folder’s music itself and serves it to Subsonic clients. A media server plays a read-only track from a playlist file only when it also has the folder in a library, mounted at the same path as in Aurral.

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
slskd	Completed download folder	/data/downloads/slskd/complete
SABnzbd or NZBGet	Completed download folder	/data/downloads/usenet/complete
Aurral	Settings > Library > Library folder > Path	/data/downloads/aurral
Media server	Music library	The Library folder, such as /data/downloads/aurral, and your read-only folders

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 Library folder is writable by Aurral and mounted in your media server.

Setup order

Follow this order to check each connection separately.

1. Choose the host media root, such as /srv/media.
2. Mount that host folder in Aurral, every download client, and your media server.
3. Use /data/... paths inside the containers. Set the completed download folders.
4. Start the services.
5. Open Settings > Library and set Library folder > Path to a writable folder under /data, such as /data/downloads/aurral.
6. Connect and test each download client that you use.
7. Open Settings > Status > Storage and select Run checks. Fix each failed check.
8. Add the Library folder to a music library in Navidrome, Plex, or Jellyfin. To import plays from them, open Settings > Listening.

Check the connections

Do these checks in order:

1. API check. The Test connection button for each integration passes.

2. File check. Settings > Status > Storage > Run checks passes the Aurral downloads section.

3. 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

4. Playback check. Your media server has the Library 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 download clients

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

• Applies to: the application that reports the path, such as slskd, NZBGet, SABnzbd, Tidarr, qBittorrent, 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	slskd
Remote path	/downloads/complete
Local path	/data/downloads/slskd/complete

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 > Status > Storage > Run checks.

Media servers see a different path

Navidrome, Plex, and Jellyfin have no path mappings. Playlist files list each track by its full path in Aurral, so mount the Library folder and any read-only folders at the same container paths as in Aurral. A server that sees them at other paths imports each playlist without its tracks.

Windows and mixed Docker setups

The same rules apply when a service runs on Windows:

1. Mount the Windows media folder into Aurral.
2. Add a remote path mapping from the Windows path that the download client reports to the Aurral container path.
3. If your media server also runs on Windows, add the matching folders as music libraries.

A remote path mapping only helps Aurral read files. It does not change what a media server can see.

Common mistakes

• Only a read-only folder is mounted in Aurral. Aurral can read that music but cannot read completed downloads or write to the Library folder.
• Only the Library folder is mounted in Navidrome or Plex. The server cannot play playlist tracks that come from a read-only folder. Mount the read-only folder too, and add it as a 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.
• The Library folder is mounted in a media server but is not in a music library. The server’s playlists stay empty, because it only adds tracks from its libraries. Add the folder to a music library. A path mapping cannot fix this.
• 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