Self Hosted Music Streaming with Airsonic on Ubuntu

Your music library will probably stay with you for life. Streaming providers likely won't. When you have had enough with streaming providers and you are ready to take control of your music library, it's time to self host your music streaming with Airsonic.

screenshot of DSub Android app streaming music from AirsonicAirsonic is a media server that implements the Subsonic API. Subsonic compatible apps such as DSub for Android (picture on right) can stream music, manager playlists etc. on Airsonic without being built specifically for this media server.

The server is written in Java and is therefore platform independent, you can run it on Windows, Mac and Linux. It's also open source under GPL3 license.

This post guides you through the installation of Airsonic on Ubuntu 20.04 LTS.

You'll need a server instance with a public ip number.

Prepare Apache Tomcat

Airsonic comes packaged as a Web ARchieve (WAR) for servlet containers.

We can run it on Ubuntu with OpenJDK and the Apache Tomcat servlet container, that are both available as APT packages.

Install OpenJDK and Apache Tomcat 9.

$ sudo su -
$ apt-get install default-jdk
$ apt-get install tomcat9

At this point Tomcat should already be running as a service managed by Systemd. Let's check it.

$ systemctl status tomcat9
   ● tomcat9.service - Apache Tomcat 9 Web Application Server
     Loaded: loaded (/lib/systemd/system/tomcat9.service; enabled; vendor preset: enabled)
     Active: active (running)

The Systemd unit file for Tomcat is configured with ProtectSystem=strict that only allows the process to access a few Tomcat specific folders. We need to grant access to some Airsonic specific folders too.

Open tomcat9.service for editing

$ vi /lib/systemd/system/tomcat9.service

Press i for insert mode and add these lines to the [service] section of the file.


Then press ESC to exit insert mode and type ":wq" to write and quit.

Create the Airsonic folders on disk and grant access to the tomcat user.

$ cd /var
$ mkdir airsonic music playlists
$ chown -R tomcat:tomcat airsonic/ music/ playlists/

Let Systemd know we changed a unit file and restart Tomcat.

$ systemctl daemon-reload
$ systemctl restart tomcat9

Deploy Airsonic

Download the latest WAR file release of Airsonic from github.

Make the file readable by the tomcat user.

$ cd Download
$ chown tomcat:tomcat airsonic.war

Drop the WAR file in Tomcat's hotdeployment folder.

$ mv airsonic.war /var/lib/tomcat9/webapps/

Watch Tomcat's log file to see if it deploys Airsonic as expected.

$ tail -f /var/log/tomcat9/catalina*.log

If it doesn't go smoothly then you probably missed one or two steps to grant the tomcat user access to the Airsonic folders.

Change the administrator password

Apache Tomcat is running on port 8080. Make sure it's accessible through your firewall.

Then open http://<ip>:8080/airsonic/ in a browser and sign in with admin/admin. Yes we pause here for a brief moment to express shock and horror that it has an active admin account with a default password!

screenshot of Airsonic webpage to get started

First order of the day is to click Change administrator password.

When apps sign into the Subsonic API they send a MD5 hash of the password and a salt, which is not exactly strong, so make sure to pick a long password.

Obviously a better way to secure the password is to enable HTTPS but I won't cover that here.

Import music

Click Home and Set up media folders.

screenshot of Airsonic scanning media folders

To import your mp3 or whatever media files your have, copy them to the server's /var/music folder and then click Scan media folders now.

Airsonic is not picky when when comes to handling your media files, but there's a ton of free applications that can help you optimize your library's mp3 tagging, folder structure and cover art.

One option is to use MusicBrainz Picard.

I'd suggest to use Picard to organize files according to this pattern:


Picard can also help to download cover art and store it as a "cover.jpg" file in each album folder.

You can always click Clean-up database and then Scan media folders now if you make changes to the structure of your library.

Create a non-administrative user

Create a new user, to connect to Airsonic from mobile apps, by clicking the Users tab and select -- New User -- in the drop down menu.

Deselect Administrative user and give the new user permission to play files, download files, upload files etc.

screenshot of setting up a new user in Airsonic

Connect DSub

Airsonic has its own free Android app, but many prefer DSub.

To set up DSub go to Settings and add a new server. Set its address to http://<ip>:8080/airsonic/ and enter the credentials of the non-administrative user.

screenshot of connecting DSub to Airsonic

Then open the Library and drag down the list of songs to sync it with the Airsonic server.

Now you are ready to stream.