Setting up
Running Aurral Behind a Reverse Proxy with SSO
Putting Aurral behind a reverse proxy is where three separate things tend to go wrong: the address the app thinks it is on, header forwarding for authentication, and websockets or large uploads timing out.
Start with the address, not the proxy
Aurral uses the address from your browser to build the URL it gives phone apps and to build the Lidarr custom-list URL. If your proxy passes a scheme or host that Aurral does not expect, those links point somewhere unreachable even though the web UI works fine.
Set a public URL explicitly if your deployment supports one. That removes the guesswork, and it is the difference between phone apps that connect and phone apps that do not.
Minimum nginx configuration
The essentials are the websocket upgrade headers and a body size large enough for a first-run upload if you plan to import anything. Buffering websockets is what makes the UI feel broken in a specific way: the page loads but nothing responds.
Authentication and SSO
Aurral has its own account system with local sign-in, plus native OIDC support and reverse-proxy SSO. Each has different requirements about what the proxy must send.
Whichever you choose, the proxy has to forward enough identity information that Aurral knows who is asking. Getting this wrong usually shows up as either everyone becoming the same user, or nobody being recognised at all.
- Local sign-in: no proxy involvement, just put it behind HTTPS.
- Reverse-proxy SSO: the proxy must forward an authenticated username header.
- Native OIDC: configure the provider inside Aurral rather than in the proxy.
Things that break less often but still do
Large request bodies fail silently when the proxy default is too small. Timeouts on long scans appear as a hung page even though the scan continues. And a proxy that strips the scheme makes generated URLs point at http on an https site, which browsers block as mixed content.
| Symptom | Likely cause | Fix |
|---|---|---|
| UI loads but actions do nothing | Websockets buffered or blocked | Forward Upgrade and Connection headers |
| Phone apps cannot connect | Generated URLs use the internal address | Set the public URL explicitly |
| Uploads fail silently | Body size limit | Raise client_max_body_size |
| Long scans appear to hang | Proxy timeout | Raise the read timeout |
| Everything is the same user | Username header forwarded wrong | Correct the header mapping |
Do not expose it directly without HTTPS
If Aurral is reachable from outside your network, put it behind HTTPS. Aurral holds your library metadata, your listening history and an API key with administrative access, and plain HTTP over the open internet is not a reasonable trade.
Frequently asked questions
Do I need a reverse proxy for local use?
No. For LAN-only access, running on port 3001 directly is fine. Add a proxy when you want HTTPS, SSO, or access from outside your network.
Why do phone apps fail when the web UI works?
Usually because the generated connection URL uses an address your phone cannot reach. Setting the public URL explicitly fixes it.
Should I use reverse-proxy SSO or native OIDC?
Native OIDC if your provider supports it, since Aurral handles it directly. Reverse-proxy SSO is simpler if your proxy already authenticates everything.
Ready to set it up
One container and one media path is genuinely all it takes. Everything else in this page is something you add when the need appears.