Docker setup

Aurral runs in Docker. It needs two mounts:

/config for Aurral’s database, settings, users, and jobs.
A media mount for the Downloads Folder, completed downloads, and the Lidarr library if you use Lidarr.

Read Filesystem and mounts before you write the Compose file. Every service that shares files with Aurral must see those files at the same path.

Minimal Compose file

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

Replace /srv/media with your host media folder. If you use Lidarr, use the host folder that Lidarr already mounts. Keep /data as the container side of the mount, so that every media service sees the same paths.

For example, the host folder /srv/media/downloads/aurral is /data/downloads/aurral inside Aurral. In Aurral settings, always enter the container path.

Do not share /config with another service.

Start Aurral

docker compose up -d

Open http://localhost:3001.
Create the admin account.
Connect Lidarr, or select Skip for now and set the Downloads Folder.
Run the storage checks.

Continue with First run.

Choose an image tag

Tag	Contents	Use it when
`latest`	The newest stable release	You want a tested release.
`2.10.0`, `2.10`, `2`	An exact version, or the newest release in that line	You pin versions or need to roll back.
`nightly`	The newest successfully published nightly build	You want fixes and features early and can report bugs.
`pr-<number>`	The preview image for an open pull request	A maintainer asked you to test a proposed change.

Aurral checks for a newer build in your channel. When one exists, an update icon appears in the top-right corner. Select it to read the changes and open the GitHub release or commit list.

On nightly, the update check uses the image published to GHCR. Changes still building, or whose builds failed or were cancelled, do not trigger the icon. Nightly checks run every two hours and require access to GHCR and GitHub. If either service cannot be checked, the nightly update icon stays hidden.

On a nightly or preview image, the sidebar shows artwork for that channel. To hide it, turn off Profile > Appearance > Environment art.

The Release Readiness issues track the current nightly. The pinned issue lists the nightly candidate and the changes it includes.

Prepare for Aurral 3.0

Aurral 3.0 removes support for data and settings from older versions. Before you update to 3.0, open Settings > System > Aurral 3.0 and check that it shows Ready for Aurral 3.0.

Each item under Blocks the update names what Aurral still needs to finish. Most items finish on their own in the background after Aurral starts. Select Check again to run the remaining tasks.
Files to review lists older files in the Downloads Folder that Aurral could not move safely, with the reason for each. Move or delete each file yourself, then select Check again.
Still in use lists settings and requests that 3.0 no longer accepts, such as the WEEKLY_FLOW_FOLDER variable or a data folder at /app/backend/data. They do not block this check, but Aurral 3.0 refuses to start while any of them is in use. Change them before you update.

If you skip from an older 2.x version straight to 3.0, Aurral 3.0 will stop without changing anything. Run the 2 image tag once, wait for the check to pass, then change to latest.

Test a pull request preview

The pull request conversation on GitHub gives the pr-<number> tag and the test steps.

Back up ./config.
Change the Aurral image to the preview tag.
Run docker compose pull aurral && docker compose up -d aurral.
Test the behavior that the pull request changes.
Change the image back to the tag that you used before.

Full stack example

docker-compose.example.yml runs Aurral, Lidarr, slskd, and Navidrome. All four services use the same ${MEDIA_ROOT:-/srv/media}:/data mount.

For Plex, see the Plex guide.

Next: Filesystem and mounts