Airsonic is an open-source, self-hosted media streaming server designed for music enthusiasts who want full control over their audio library. As a fork of Subsonic, it offers extensive customization, robust API support, and the ability to stream or share media across multiple devices. In this guide, we’ll cover everything you need to deploy, configure, and optimize Airsonic, including installation options, reverse proxy setup, logging, backups, updates, and advanced features.
Installing Airsonic
📦 Docker/Docker Compose Setup
The easiest and most common way to deploy Airsonic is via Docker. Below is a complete docker-compose.yml file to get started.
version: '3.8'
services:
airsonic:
image: airsonic/airsonic
container_name: airsonic
ports:
- "4040:4040"
volumes:
- ./airsonic/data:/airsonic/data
- ./airsonic/music:/airsonic/music
- ./airsonic/playlists:/airsonic/playlists
- ./airsonic/podcasts:/airsonic/podcasts
environment:
- AIRSONIC_CONTEXT_PATH=/airsonic
- JAVA_OPTS=-Xmx512m
restart: unless-stopped
To deploy Airsonic using Docker Compose, run the following commands:
mkdir -p ~/airsonic/{data,music,playlists,podcasts}
cd ~/airsonic
nano docker-compose.yml # Paste the above YAML configuration
docker-compose up -d
This sets up Airsonic on port 4040 with persistent storage for configuration, media, playlists, and podcasts.
🚀 Manual Installation
For those who prefer direct installation, follow these steps on a Linux server:
- Install required dependencies:
sudo apt update && sudo apt install -y openjdk-11-jre wget unzip
- Download and install the Airsonic WAR file:
wget https://github.com/airsonic/airsonic/releases/download/v10.6.2/airsonic.war
mv airsonic.war /opt/airsonic.war
- Create a systemd service file for Airsonic:
sudo nano /etc/systemd/system/airsonic.service
Add the following content:
[Unit]
Description=Airsonic Media Streaming Server
After=syslog.target network.target
[Service]
User=airsonic
ExecStart=/usr/bin/java -jar /opt/airsonic.war
Restart=always
Environment="JAVA_OPTS=-Xmx512m"
[Install]
WantedBy=multi-user.target
- Start the Airsonic service:
sudo systemctl daemon-reload
sudo systemctl enable --now airsonic
Airsonic will now be running on port 8080 by default.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
To access Airsonic through a custom domain, configure Nginx as a reverse proxy:
sudo nano /etc/nginx/sites-available/airsonic
Add this server block and adjust the domain name as needed:
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://localhost:4040;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
Enable the configuration and reload Nginx:
sudo ln -s /etc/nginx/sites-available/airsonic /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure your Airsonic instance using Let's Encrypt:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com
Automate renewal with a cron job:
crontab -e
0 3 * * * certbot renew --quiet
🛠️ Testing and Reloading Nginx
After configuration, test and reload Nginx to apply changes:
sudo nginx -t && sudo systemctl reload nginx
Logging and Debugging Airsonic
🗃️ Enabling Debug Logs
To enable debug-level logging, edit Airsonic’s logback.xml file (located in the data directory):
nano ~/airsonic/data/logback.xml
Set the log level to DEBUG:
<root level="DEBUG">
<appender-ref ref="CONSOLE"/>
</root>
📄 Viewing Logs
For Docker users, view logs with:
docker logs airsonic
For manual setups, use:
tail -f /var/log/airsonic.log
🛠️ Troubleshooting Common Issues
-
Port In Use: Ensure no other service is using the configured port.
-
Nginx Errors: Check
/var/log/nginx/error.logfor reverse proxy issues. -
Media Not Loading: Verify permissions on the media folder.
📤 Exporting Logs
To send logs to an ELK Stack, configure a filebeat.yml file and point it to Airsonic’s log directory.
Backup and Restore
🗂️ File-Based Backups
Backup Airsonic’s configuration and media files:
tar -czvf airsonic_backup_$(date +%F).tar.gz ~/airsonic/data ~/airsonic/music
🔄 Database Backups
If using a database (e.g., PostgreSQL), export it:
pg_dump -U airsonic_user airsonic_db > airsonic_db_backup.sql
📅 Automated Backup Scripts
Automate backups with a cron job:
crontab -e
## Add:
0 2 * * * tar -czvf /backups/airsonic_$(date +\%F).tar.gz ~/airsonic/data ~/airsonic/music
Updating and Upgrading Airsonic
⬆️ Updating Docker Images
For Docker setups, update Airsonic with:
docker-compose pull
docker-compose up -d
🛠️ Manual Updates
For manual installs, download the latest WAR file and restart the systemd service:
wget https://github.com/airsonic/airsonic/releases/latest/download/airsonic.war -O /opt/airsonic.war
sudo systemctl restart airsonic
🔍 Checking for Updates
To check for updates, visit Airsonic’s GitHub Releases.
Leveraging Airsonic’s Unique Features
🔧 Enabling APIs
Airsonic includes robust API support. Enable API access in the settings, and test endpoints using curl:
curl -u username:password http://yourdomain.com/rest/getAlbum.view?u=username&p=password&v=1.16.1&c=MyClient
🌟 Advanced Configurations
-
Customize Transcoding: Configure transcoding in
Settings > Transcoding. -
Third-Party Tools: Integrate apps like Subsonic clients or scripts for syncing playlists.
Wrapping Up
Airsonic provides a versatile, self-hosted solution for managing and streaming music libraries. By following this guide, you’ve learned how to install, configure, and optimize Airsonic, ensuring secure and efficient access to your media. With its advanced APIs and customization options, you’re now well-equipped to make the most of this powerful media streaming platform!
