Keep your music on your server and listen remotely through your browser
Aurral brings music discovery, library management, playlists, downloads, and browser playback into one self-hosted application. This guide covers Docker Compose installation, persistent storage, first-run setup, and local playback verification before adding remote access. Once the application works locally, we connect it to a Localtonet HTTP tunnel without inbound router port forwarding or a public IP address. You will also learn how to choose the right Docker port binding, protect authentication, maintain backups, and troubleshoot each layer independently.
📋 What's in this guide
How Aurral and Localtonet fit together
Aurral is a self-hosted application for music discovery, downloads, library management, playlists, and playback. It indexes music from its Library folder, read-only folders you add, and optionally connected Lidarr root folders. Its built-in player streams Library tracks in a browser, and its Subsonic-compatible service is available at /rest for compatible clients.
Lidarr is optional, not a prerequisite. Without it, Aurral manages music in its own Library folder. Navidrome, Plex, and Jellyfin are also optional: you do not need another media server to hear music in Aurral's browser player. Listening-history services and download clients can be connected later, after the basic deployment works.
We separate installation from remote connectivity. Docker first publishes Aurral's web service on host port 3001. You create an administrator account, configure storage, and play an indexed track. Only then does the Localtonet client connect outward to our relay infrastructure and forward requests from a public HTTPS address to the working local service.
/config and /data.
Distinguish documentation, releases, and your installed image
The supplied official Aurral website displays v2.10.0, while the official GitHub release evidence includes v2.13.0. Neither label proves what is installed on your machine. The documented Compose file uses ghcr.io/lklynet/aurral:latest, a moving tag whose image can change between pulls. An already-running container does not automatically update when that tag changes.
The installation and onboarding instructions below follow the supplied official website and first-run documentation. Backup behavior and certain integration details are explicitly attributed to v2.13.0 release notes. Check your installed version before relying on those features. A future or previously cached latest image should not be assumed to have exactly the same menus or restore behavior.
The supplied documentation confirms the Compose environment variables but does not describe their full runtime implementation. It also does not establish how Aurral classifies requests arriving through Localtonet for local-network auto-login. We therefore avoid assuming either behavior and use explicit storage checks and authentication tests below.
Prepare the host and storage layout
This tutorial uses Docker Compose, the installation path shown on Aurral's official website. Have Docker and its Compose plugin installed using the supported method for your operating system. The supplied Aurral evidence does not establish universal CPU architecture, memory, or operating-system requirements, so confirm image compatibility with your host rather than assuming every device can run it.
docker --version
docker compose versionBoth commands should succeed before proceeding. The commands in this guide run from the directory containing compose.yaml. On systems where Docker requires additional permissions, use the host's approved Docker access method rather than changing permissions broadly to make an error disappear.
| Requirement | What to prepare | Why it matters |
|---|---|---|
| Docker with Compose | A working Docker engine and docker compose | Starts and maintains the documented container |
| Persistent storage | A dedicated project directory and media storage | Preserves data across container replacement |
| Available host port | TCP port 3001, with a deliberate bind address | Avoids conflicts and unnecessary network exposure |
| Browser access | A browser that can reach the chosen local endpoint | Completes onboarding and verifies playback |
| Authorized music | Readable existing files or a writable Library destination | Provides content for a meaningful playback test |
| Localtonet client device | A connected device with its private device token | Forwards requests to Aurral's reachable address |
Keep host paths and container paths distinct
The minimal configuration maps ./config to /config and ./data to /data. These relative host paths are resolved from the Compose project directory. Aurral uses paths inside its container, not arbitrary paths visible to the host operating system.
If another service writes media that Aurral needs to read, mount the same host media directory into both containers at the same container path, commonly /data. If Lidarr is connected, mount its root folder into Aurral at the same container path Lidarr uses. Keep Aurral's configuration mount separate from shared media.
During onboarding, Read in place plays existing files where they are and does not change them. Import copies files into Aurral's Library folder and leaves the originals in place. Import therefore requires space for another copy. Plan for audio, artwork, downloads, application data, backups, and temporary growth rather than only the current library size.
PUID and PGID are not permission verification
The official Compose example includes PUID=1000 and PGID=1000. Retain these as the published example, but do not assume that user or group 1000 owns your storage. On a Linux host, id shows the current account's numeric identity:
idThe supplied official extracts do not explain whether the image applies these variables to every process, changes ownership at startup, or handles existing files recursively. Do not treat them as proof of access or add an unverified user: override. Inspect host ownership, mount permissions, and actual storage-check results. Use the intended storage identity and current image guidance when adjusting values.
Read-only source folders need separate writable storage
For a collection Aurral should only read, Docker's :ro bind-mount suffix provides a filesystem-level restriction. That is distinct from selecting Read in place in Aurral. An additional mount could look like this, after replacing the host path with a real existing directory:
- /absolute/path/to/existing-music:/music:roAdd this under the existing volumes list and use /music in Aurral. Keep /config and the managed Library destination writable. Do not make the entire /data mount read-only if downloads, imports, or the Library folder must write there. The v2.13.0 release notes explicitly say its artwork-writing behavior does not write to Lidarr or read-only folders, but that does not make all application storage read-only compatible.
Self-hosting does not change copyright, licensing, privacy, or acceptable-use obligations. Import, download, stream, and share only content you have the necessary rights to use.
Install Aurral with Docker Compose
Create a dedicated directory on persistent storage and save the following official configuration as compose.yaml. Review the port-binding alternatives immediately below before starting it.
services:
aurral:
image: ghcr.io/lklynet/aurral:latest
restart: unless-stopped
ports:
- "3001:3001"
environment:
- PUID=1000
- PGID=1000
volumes:
- ./config:/config
- ./data:/dataChoose the port binding for your deployment
3001:3001 does not mean localhost-only access. Docker normally publishes that port on all host addresses unless constrained. Actual reachability also depends on routing and host configuration. Do not rely on the absence of a router forwarding rule as proof that other networks cannot reach it.
If the Localtonet client runs directly on the same host as Docker, replace the port entry with this standard Docker loopback binding:
ports:
- "127.0.0.1:3001:3001"Then use http://127.0.0.1:3001 for host-local checks and configure Localtonet with target IP 127.0.0.1, port 3001. Other LAN devices should not reach this binding directly. Verify that behavior on your actual Docker version and network setup.
If the Localtonet client runs on another LAN device, a loopback-only binding will not work. Keep a LAN-reachable publication, either the original mapping or an explicit binding to the Docker host's actual LAN address. Restrict access according to your network policy and test from the selected client device. Do not add router port forwarding.
A Localtonet client running inside a separate container has its own network namespace: its 127.0.0.1 is not the Docker host. The same-host loopback example assumes a client running directly on the host, not an arbitrary container networking configuration.
Start and inspect the container
docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100 aurraldocker compose config checks the Compose configuration. Startup may take time while Docker downloads the image and Aurral initializes. Inspect status and logs if the service does not remain running. Do not publish logs containing credentials or integration secrets.
Open http://127.0.0.1:3001 on the host. For a LAN-reachable binding, a browser on another device can use the Docker host's LAN address with port 3001. For loopback-only deployment, complete onboarding from a browser on the host; do not expose an unfinished administrator setup merely to reach it remotely.
The unless-stopped policy allows Docker to restart the container unless an operator deliberately stopped it. It does not ensure that Docker itself, the Localtonet client, or the tunnel starts after every reboot. Replacing the container preserves bind-mounted host directories, but it does not protect them from deletion, disk failure, or accidental overwrites.
Complete Aurral's first-run setup
The official first-run sequence creates the administrator account, offers local-network auto-login, chooses music locations, and offers optional connections. Everything after account creation can be revisited in Settings. The sequence below keeps those choices together and performs the documented storage check afterward.
Create the administrator account
Open Aurral and enter a username and a strong, unique password. This account is separate from Localtonet and any connected media-service account.
Leave local-network auto-login disabled
Aurral offers Auto-login on local network for single-user home use. For this publicly tunneled deployment, leave it off. The supplied documentation does not establish how reverse-tunneled requests are classified.
Choose existing music
Under Your music, select Read in place or Import if you already have music. Use the container-visible path. Import copies files into the Library folder while leaving originals intact.
Set the Library folder
Choose a writable mounted location, such as the documented example /data/downloads/aurral. Aurral keeps music it adds in this folder.
Choose optional connections
Under Connect, you can add Last.fm, ListenBrainz, or Spotify listening history, import plays from Navidrome, Plex, or Jellyfin, and connect Lidarr. Each opens its Settings page. Skip services you do not use.
Finish onboarding
Select Go to Aurral when the initial choices are complete.
Run storage health checks
Open Settings > Status > Storage and select Run checks. Resolve failed checks before remote exposure.
Storage health verifies that Aurral can read files and write to its Library folder. The Lidarr section checks Lidarr library files and is skipped when Lidarr is not connected. The Aurral-native playback section checks whether the built-in player can read indexed media. A visible folder or album cover is not proof that the underlying tracks are readable.
Add integrations only when needed
Download clients are configured under Settings > Downloads. The current first-run documentation lists slskd, SABnzbd, NZBGet, Tidarr, and deemix; built-in yt-dlp needs no separate service. For Tidarr specifically, the v2.13.0 release notes require Tidarr 1.2.9 or later. Confirm compatibility with your installed Aurral version before adding it.
Completed downloads must land beneath storage Aurral can see. Mount folders before adding path mappings. If a service reports /data/music/album/track.flac, that path must resolve correctly inside Aurral, not merely exist on the host.
For Navidrome, Plex, or Jellyfin, add the Aurral Library folder to that server's music library. Navidrome and Jellyfin can also import Aurral playlist files. Listening integrations are under Settings > Listening; optional Lidarr management is under Settings > Library > Lidarr.
Verify local playback before adding a tunnel
A successful login page proves that the web interface responds, not that the music service is ready. Test the complete path from browser to application, index, and audio file.
- Reload the local interface. Use the address permitted by your chosen binding, then sign in and navigate through the application.
- Run storage checks. Confirm file readability, writable Library storage, and native playback access.
- Find an indexed track. Open Library or Search and select music that exists in a mounted folder.
- Play and seek. Listen long enough to confirm continuous audio, then test seeking if it is part of your normal workflow.
- Test from the tunnel device. If Localtonet runs elsewhere, open the exact Aurral LAN address and port from that device before configuring a tunnel.
If the library is empty, revisit the music selection and container mount. If tracks appear but playback fails, inspect storage health and logs. Metadata can remain visible even when a media directory is missing or unreadable.
Optional Subsonic testing can follow successful browser playback. Aurral serves the protocol at /rest using an Aurral account. Some clients expect the server's base address and construct protocol paths themselves, so follow that client's URL format rather than blindly appending /rest to every configuration.
Create a Localtonet HTTP tunnel to Aurral
Use our HTTP tunnel family for Aurral's browser interface. The target is the published Aurral service, not a Docker management port or a filesystem folder. With Localtonet, you do not need inbound router port forwarding, a public IP address, or VPN setup for this workflow.
The following sequence uses the supported Localtonet device, relay, configuration, and start lifecycle. The supplied evidence does not include a current HTTP dashboard capture or the full live HTTP documentation text, so exact field captions and screen grouping cannot be independently confirmed here. The configuration values below are complete for this deployment; use their corresponding controls in the current dashboard rather than assuming a particular screen layout.
Install and run our client
Install the Localtonet application for the device's operating system using our current installation guidance. Run it on the Aurral host or another device that already reaches Aurral. Platform-specific installation commands are not included in the supplied evidence, so no unverified installer command is prescribed here.
Authenticate and select the device
Use that device's private token and select the associated connected device for the tunnel. A token identifies the client device; it is not an Aurral password.
Select an available relay
Choose a server or region offered in your dashboard. Do not copy a server code from another installation.
Configure the HTTP tunnel
Choose HTTP and an available Process Type. Random Sub Domain is suitable for an initial test. Set the local IP to 127.0.0.1 for a host-native same-host client, or the Aurral host's reachable LAN address for a separate client. Set the local port to 3001.
Start and use the tunnel
Press Start after creating the configuration. Use the assigned public HTTPS URL to test login and playback from an external network.
Stop unused access
Stop the tunnel when remote access is not needed, or delete it when the configuration is obsolete.
| Configuration item | Value for this guide | Important distinction |
|---|---|---|
| Tunnel family | HTTP | Publishes the Aurral web service |
| Process Type | Random Sub Domain for initial testing | Custom Sub Domain and Custom Domain are alternatives where supported |
| Device/auth token | The connected client device | Keep the token private |
| Relay/server | An available dashboard selection | Availability can vary |
| Local IP | 127.0.0.1 or the reachable host LAN address | Interpret the address from the client device |
| Local port | 3001 | Use the published host port, not an unrelated service port |
| Lifecycle | Start after configuration | A saved tunnel is not necessarily running |
Our HTTP tunnel documentation supplements these values with the current interface workflow. Use the current dashboard for available process types and relay selections. Custom-domain DNS requirements must also come from current documentation, not copied values from another account.
Test authentication before sharing the address
Use a mobile connection or another external network and open the public URL in a private browser session. Confirm that protected content requires an Aurral login. Sign in, play the same track tested locally, and test seeking. A previously authenticated browser is not sufficient to verify anonymous access restrictions.
If a fresh remote session receives authenticated access without credentials, stop the tunnel and investigate Aurral's auto-login and account settings. A reverse tunnel changes the immediate network path; do not assume Aurral sees the remote visitor as a conventional internet client.
The public address is available only while the selected client device is connected and the tunnel is running. Aurral must also remain reachable at the configured target. Check all three conditions when access stops.
Secure the remotely accessible application
A public tunnel simplifies connectivity, but it does not make application vulnerabilities or weak credentials harmless. Treat Aurral as internet-facing while the tunnel is running. Keep local-network auto-login disabled for this deployment, maintain strong passwords, and review access before sharing links.
- Separate administration from listening. Aurral supports multi-user profiles and permissions. Use individual ordinary accounts where practical and reserve administrator privileges for maintenance.
- Protect secrets. Keep Localtonet tokens, integration API keys, SSO credentials, and download-client passwords out of screenshots, repositories, and shared logs.
- Limit mounted storage. Expose only the directories Aurral needs. Use a separate read-only source mount where appropriate, while retaining writable application storage.
- Review shares. Aurral share links are a separate access mechanism from account login. Remove access that is no longer intended.
- Maintain the host. Update Docker, the operating system, Aurral, and the Localtonet client through their supported workflows.
Aurral supports SSO and native OIDC, but those integrations require their own configuration and testing. They are not necessary for this local-account tutorial. Never grant administrator access merely because someone needs music playback.
Sharing behavior is version-sensitive. In v2.13.0, stopping a track, album, or artist share ends file access immediately, but its link can continue displaying details and previews. Do not promise that stopping a share removes every public trace of it.
The HTTP tunnel targets Aurral; it does not automatically publish SSH, Docker management, or unrelated containers. It can, however, make the web application's own routes reachable, including supported APIs and sharing endpoints. Review application permissions accordingly.
Standard Localtonet HTTP tunneling is not a VPN. Our VPN Manager is the separate feature for private mesh networking. Use the architecture that matches your access requirements rather than assuming a public application URL creates a private network.
Operate, update, and back up Aurral
Routine container operations
Run these standard Compose commands from the project directory:
docker compose ps
docker compose logs --tail=100 aurral
docker compose restart aurral
docker compose stop
docker compose up -dUse status and logs before restarting repeatedly. Stopping Aurral removes the tunnel's working target, while stopping Localtonet removes remote access without necessarily affecting local listening. After a host reboot, verify Docker, Aurral, the client connection, and the running tunnel independently.
Record the installed deployment before updating
Check the version reported by the running application and retain the Compose file used to deploy it. Standard Docker commands can also record the running container and image identity:
docker compose images
docker inspect "$(docker compose ps -q aurral)" --format '{{.Image}}'The second command uses a POSIX-style shell and records the image ID, not a human-readable Aurral version. Keep both the application version and image identity in maintenance notes. If you need reproducible deployments, use a registry-confirmed tag or digest; do not infer that every GitHub release name exists as an image tag.
After reviewing release notes and making a backup, the normal moving-tag update workflow is:
docker compose pull
docker compose up -dRunning up -d alone does not necessarily fetch a newer image. After updating, repeat storage checks, local playback, anonymous remote login verification, and remote playback. Do not assume restoring an older image alone reverses database or configuration migrations.
Protect persistent files independently
Back up the host directories mounted at /config and /data, every separate media mount, and the Compose configuration. Include ownership and permissions in the recovery plan. For a straightforward filesystem backup, stop Aurral before copying its mutable application data, then restart after the copy completes. Coordinate other services that write shared media if consistency requires it.
Keep backups on storage independent of the live directories. A copy on the same failing disk is not a complete recovery strategy. Test restoration into an isolated deployment before depending on it, and avoid letting a test restore trigger downloads or modify production media.
Application backup behavior confirmed for v2.13.0
The official v2.13.0 release notes describe an administrator backup and restore interface at Settings > General > Backup. Its single ZIP contains settings, users, playlists, flows, history, and custom artwork. Restoring restarts Aurral and retains replaced data at /config/before-restore-<date>. The release notes state that a Docker restart policy such as unless-stopped brings Aurral back afterward.
These are confirmed v2.13.0 behaviors, not a guarantee for an unknown installed image. Verify the feature and restore instructions for your version. The retained before-restore directory is a local recovery aid, not an independent backup, and the release notes do not establish unrestricted cross-version restore compatibility.
The listed backup contents do not include the underlying audio collection. Protect music and separately mounted media with filesystem or storage backups. Treat the application ZIP as sensitive because it includes settings and user data.
Verify recovery, not just backup creation
After a restore, confirm accounts, settings, playlists, storage mounts, file readability, and actual playback. Preserve the container-visible paths expected by the restored data. Check free space before restoring because retained replaced data and the restored copy may coexist.
Monitor space routinely, especially when importing music or retaining local backup files. Run storage checks after changing mounts, permissions, or connected services. Review users, active shares, integration credentials, and unused tunnel configurations on a regular schedule.
Troubleshoot from the container outward
Use this order: container health, local HTTP access, storage, playback, reachability from the Localtonet device, then public access. Change one layer at a time so a working tunnel is not reconfigured to compensate for a missing audio file.
| Symptom | Likely area | Next check |
|---|---|---|
| Local page will not open | Container or port | Inspect Compose status, logs, port conflicts, and the selected bind address |
| Container exits repeatedly | Initialization or storage | Inspect logs, mount availability, permissions, and recent changes |
| Library is empty | Mount or library selection | Confirm Aurral uses a container-visible music path |
| Tracks appear but fail to play | Unreadable or missing files | Run storage and native playback checks |
| Library writes fail | Permissions or read-only mount | Check host ownership and whether the destination is writable |
| Lidarr files are missing | Path mismatch | Mount its root folder at the same container path |
| Separate tunnel device cannot connect | Binding or routing | Check for a loopback-only publication and test the host LAN address |
| Saved tunnel has no working public address | Lifecycle | Confirm the device is connected and the tunnel is started |
| Public page loads but audio stalls | Storage, resources, or network | Compare the same track locally and remotely, then inspect logs and resource use |
| Remote session logs in automatically | Authentication configuration | Stop exposure, disable auto-login, and retest in a fresh external session |
| Access fails after reboot | Startup sequence | Check Docker, Aurral, Localtonet client connectivity, and tunnel state |
Paths fail after a storage move
A container sees only its mounted paths. Moving a host directory without updating the mount can leave a familiar container path pointing at an empty or incorrect location. Correct the host mapping, preserve the paths expected by Aurral and connected services, recreate the container if the Compose configuration changed, and rerun checks.
The tunnel device reaches the wrong machine
localhost always refers to the device or network namespace making the connection. On a second LAN machine it does not mean the Aurral host. In a separate container it does not mean the host either. Test the exact configured target from the Localtonet client's environment before investigating the public URL.
Only remote playback is unreliable
First compare the same track and playback operation locally. If local playback also fails, inspect storage and application logs. If only remote playback fails, compare networks, check host upload capacity and resource contention, and confirm tunnel availability. Do not assume a bandwidth guarantee or fix the issue by disabling authentication.
Frequently asked questions
Does Aurral require Lidarr, Navidrome, Plex, or Jellyfin?
No. Lidarr is optional, and Aurral includes browser playback and a Subsonic-compatible service. Add other media servers only when their integrations are useful to your deployment.
Do I need to forward port 3001 on my router?
No. Our client establishes an outbound connection to a Localtonet relay. It must be able to reach Aurral locally, but this workflow does not require an inbound router forwarding rule or public IP address.
Should Docker publish Aurral on localhost or the LAN?
For a Localtonet client running directly on the same host, 127.0.0.1:3001:3001 is an optional hardening choice. A client on another device needs a LAN-reachable binding. The original 3001:3001 mapping normally publishes on all host addresses.
Does latest mean I have Aurral v2.13.0?
No. The tag moves, and your local image may have been pulled earlier. Check the running application's version and record its image identity. Features described specifically in v2.13.0 release notes should not be assumed for an unknown image.
Can I leave local-network auto-login enabled?
Leave it disabled for this public-tunnel deployment. The supplied documentation does not confirm reverse-tunnel request classification. Verify from an external network and a fresh browser session that protected content requires authentication.
What should I back up?
Protect the Compose configuration, the host directories mounted at /config and /data, and all separately mounted media. The v2.13.0 application ZIP is an additional recovery layer, not a documented backup of the audio collection.
Is a created tunnel always online?
No. The selected device must be connected, the tunnel must be started, and Aurral must be reachable at its local target. Creating a saved configuration alone does not provide access.
Can I use a custom domain?
Our HTTP tunnels support Random Sub Domain, Custom Sub Domain, and Custom Domain process types. Choose an option available to your account and use current documentation for custom-domain DNS requirements.
Bring your working music server online with Localtonet
Verify local storage and playback first, then connect an HTTP tunnel to Aurral's published port. Keep authentication enabled, protect the device token, and stop the tunnel whenever remote access is no longer needed.
Get Started Free →
