What 16 integrations taught me about self-hosted software
Aurral talks to Lidarr, Last.fm, ListenBrainz, Koito, yt-dlp, slskd, Prowlarr, SABnzbd, NZBGet, deemix, Navidrome, Plex, Jellyfin, Ticketmaster, Gotify, and webhooks. Every one of them runs on someone else's hardware, at some version I don't control, behind a network setup I'll never see. These are the lessons that cost me the most support threads.
Nobody's setup looks like yours
My first README told people to put their Lidarr URL and API key in an .env file. That
works if you run Docker the way I do. It doesn't if you're on Unraid, behind a reverse proxy, or running
services on three different machines. Aurral 2.0 moved all of that configuration into the web UI with an
onboarding flow, so people could fix a wrong URL without editing files and restarting containers.
The small cases keep coming. Some people run slskd with authentication turned off, so Aurral stopped requiring an slskd API key. That fix came from a support conversation, not from my own testing.
Upstream will change under you
slskd changed its download API while Aurral depended on it, so Aurral had to support both the current and the older version. In August, a user on r/Lidarr posted that Aurral 2.1.0 could no longer reach Lidarr. Every integration is a promise that depends on someone else's release schedule.
What helps is a health check that tells people which service failed and why, plus a troubleshooting page that matches the error they see. An error that names Lidarr and says the API key was rejected is something people can fix on their own. "Something went wrong" turns into a Discord thread.
Never depend on one free API
Aurral's metadata originally came from MusicBrainz, which is great and also rate limited. In the first month I added a circuit breaker so a slow MusicBrainz wouldn't take the whole app down. Later Aurral added BrainzMash, a community metadata service, as a provider with fallback routing. Discovery works the same way. If you don't have a Last.fm API key, Aurral falls back to ListenBrainz.
Stay out of the user's library
People spend years curating a music library. The fastest way to lose their trust is to have automation fill it with albums they didn't choose. Aurral's playlists and flows download into their own area, and changes to the main library go through Lidarr's API. I put that in my Reddit updates because it's the first thing a careful self-hoster wants to know.
Sometimes the community builds it first
In April a user built Jellygate, a small bridge that let people sign in to Aurral with their Jellyfin account, and posted it to r/jellyfin. Aurral could sit behind proxy authentication, but it didn't speak Jellyfin's login. Seeing someone build their own workaround told me more about demand than any feature request. Aurral now supports native OIDC along with Plex and Google sign-in.
Sometimes you wait
Aurral users asked for slskd support well before I could ship it. It depended on a change in slskd itself, so I linked the upstream issue, explained the blocker, and shipped once it was possible. Some integration work is just being patient in public. I wrote more about that in When my users became someone else's problem.
The short version
- Configuration belongs in the UI, with a guided first run.
- Errors should name the service and the fix.
- Every external API needs a fallback or a graceful failure.
- Automation should never touch data the user curated by hand.
- Workarounds people build are feature requests with proof attached.
Each integration has a setup guide on docs.aurral.org.