How to Install Airsonic-Advanced on AlmaLinux 9 or Rocky Linux 9
Airsonic is archived. Install the Airsonic-Advanced fork on AlmaLinux 9 or Rocky Linux 9 as a systemd service, and know its maintenance status first.
Airsonic is a self-hosted music streaming server descended from Subsonic. The original Airsonic project is finished: its GitHub repository was archived on 8 September 2021 with the notice that Airsonic is no longer maintained and users should migrate to Airsonic-Advanced. This guide therefore installs Airsonic-Advanced as a systemd service on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9, which replace CentOS 7 (end of life since June 2024). At the end you will have the web player running on port 8080 and scanning a music folder.
Know what you are installing
Be aware of the state of the fork before you commit a music library to it:
- Airsonic-Advanced is not archived, but development has slowed to a stop. The newest build on its releases page is the edge release
11.0.0-SNAPSHOT.20240424015024, published in April 2024, and the repository has had no commits since then. - The project publishes these snapshot builds rather than regular stable versions, and its README recommends the snapshots over the old stable releases.
- The 11.x series is not backwards compatible with Airsonic 10.6. On the first start with an existing Airsonic data directory it migrates the database and leaves a backup named
db.backup.<timestamp>next to it; going back means restoring that backup by hand.
For a private server behind a reverse proxy this is still a workable choice, but treat it as software that no longer receives fixes, and do not expose it to the internet without TLS and strong passwords.
Requirements
- A server running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 and a user with
sudorights - Java 11 or newer for the 11.x series. The README states that it also works with JDK 17, which is what this guide installs.
- Your music files on the server, for example in
/var/music
Install Java
sudo dnf install -y java-17-openjdk-headless wget
java -version
Install Airsonic-Advanced
Airsonic-Advanced is distributed as a single self-contained airsonic.war file and is run the same way as the original Airsonic. Create a dedicated user and the data directory, then download the build:
sudo useradd --system --home-dir /var/airsonic --shell /sbin/nologin airsonic
sudo mkdir -p /var/airsonic /var/music
sudo wget https://github.com/airsonic-advanced/airsonic-advanced/releases/download/11.0.0-SNAPSHOT.20240424015024/airsonic.war --output-document=/var/airsonic/airsonic.war
sudo chown -R airsonic:airsonic /var/airsonic
Each release also has an artifacts-checksums.sha file, and the public key used to sign releases is in the repository as releases_public_key.asc, if you want to verify the download. Check the releases page first in case a newer build has appeared, and adjust the URL.
Create the systemd service
The repository ships a hardened systemd unit and a matching settings file. Install both:
sudo wget https://raw.githubusercontent.com/airsonic-advanced/airsonic-advanced/master/contrib/airsonic.service -O /etc/systemd/system/airsonic.service
sudo wget https://raw.githubusercontent.com/airsonic-advanced/airsonic-advanced/master/contrib/airsonic-systemd-env -O /etc/sysconfig/airsonic
The unit runs /var/airsonic/airsonic.war as the airsonic user with these defaults, each of which you can override by uncommenting a line in /etc/sysconfig/airsonic:
| Variable | Default | Meaning |
|---|---|---|
PORT | 8080 | HTTP port |
CONTEXT_PATH | /airsonic | URL path the application is served under |
AIRSONIC_HOME | /var/airsonic | Database, settings and logs |
JAVA_OPTS | -Xmx700m | Java heap limit |
JAVA_ARGS | empty | Extra application arguments, for example --server.address=127.0.0.1 |
Start the service and enable it at boot:
sudo systemctl daemon-reload
sudo systemctl enable --now airsonic.service
sudo systemctl status airsonic.service
The first start takes a while because the database is created. Follow it with sudo journalctl -u airsonic -f.
Open the firewall and log in
If you will reach Airsonic directly rather than through a reverse proxy, open the port:
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload
Browse to http://203.0.113.10:8080/airsonic, replacing the address with your server's. The default username and password are both admin. Change the password immediately under Settings > Users.
Next, go to Settings > Media folders, add /var/music (or wherever your files are) and start a scan. The airsonic user needs read access to the files. Airsonic presents music the way it is organised in directories on disk; tags are used for display and search only.
Run it behind a reverse proxy
For access from outside your network, put nginx or Apache with a TLS certificate in front and keep port 8080 closed. Two points are specific to Airsonic-Advanced:
- The web interface talks to the server over WebSockets, so the proxy must pass
Upgraderequests through. - Airsonic must be told to trust forwarded headers. Add this line to
/var/airsonic/airsonic.propertiesand restart the service:
server.forward-headers-strategy=native
A minimal nginx location for this looks as follows:
location /airsonic {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
On SELinux-enforcing systems allow nginx to connect to the backend with sudo setsebool -P httpd_can_network_connect 1. To make Airsonic itself listen only on the loopback interface, set JAVA_ARGS=--server.address=127.0.0.1 in /etc/sysconfig/airsonic.
Update or move to Docker
To update, stop the service, replace /var/airsonic/airsonic.war with a newer build and start the service again. Copy the /var/airsonic directory somewhere safe first.
The project also publishes container images as airsonicadvanced/airsonic-advanced on Docker Hub and on GHCR. Inside the container the data directory is /var/airsonic and the media mount points are /var/music, /var/podcast and /var/playlists, which differ from the original Airsonic image. The container runs as root unless you pass --user or the PUID and PGID environment variables. See the project README for details.
Frequently asked questions
Can I still install the original Airsonic?
The last release files are still downloadable, but the repository has been read-only since September 2021 and its own notice tells users to migrate to Airsonic-Advanced. Installing it today means running unpatched software.
Can I move an existing Airsonic 10.6 installation to Airsonic-Advanced?
Yes. Point AIRSONIC_HOME at the existing data directory and start the new airsonic.war. The 11.x build migrates the database on first start and keeps a backup copy beside it. Make your own copy of the directory before you try it, because the migrated database cannot be opened by 10.6 again.
Why does the web interface load but never update the play queue?
That is usually a reverse proxy that does not forward WebSocket upgrades. Check that the Upgrade and Connection headers are passed and that server.forward-headers-strategy=native is set.
Which mobile apps work with it?
Airsonic-Advanced keeps the Subsonic API of its ancestors, so clients written for Subsonic or Airsonic can connect to it using the server address including the /airsonic path.