Docker setup

Aurral runs in Docker. It needs two mounts:

• /config for Aurral’s database, settings, users, and jobs. Do not share it with another service.
• /data for your music. Aurral keeps its Library folder here, at /data/downloads/aurral by default.

Compose file

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

Set PUID and PGID to the user and group that should own your music. Run id on the host to find them.

If Lidarr, a download client, or a playback server shares files with Aurral, mount the same host folder at /data in each of them. See Filesystem and mounts.

Start Aurral

docker compose up -d

Open http://localhost:3001, create the admin account, and 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.

Every hour, Aurral checks aurral.org for a newer build in your channel. It sends only its version. When a newer build 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 icon only offers images that finished publishing to GHCR, so changes still building or whose builds failed do not trigger it. If aurral.org cannot be reached, the icon stays hidden.

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

Caution

nightly is not a stable release. Back up ./config before you switch to it.

Nightly and preview images support linux/amd64 only. On ARM, use latest or a version tag.

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

Test a pull request preview

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

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