Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

Music Streaming Server Airsonic-Advanced

Introduction

Welcome to this comprehensive guide on self-hosting your own music streaming server using Airsonic-Advanced. In an era where streaming services dominate, taking control of your personal music library offers significant advantages: ownership, privacy, customization, and freedom from subscription fees. Airsonic-Advanced is a free, open-source, web-based media streamer, forked from the original Airsonic project (which itself was a fork of Subsonic). It allows you to access your music collection from anywhere, using a web browser or dedicated mobile apps.

This guide is designed for university students and enthusiasts eager to dive deep into the world of self-hosting. We will progress from fundamental concepts and basic setup to more complex configurations, security enhancements, and maintenance practices. The material is divided into Basic, Intermediate, and Advanced sections, ensuring a gradual learning curve.

Basic: Covers the essentials – understanding Airsonic-Advanced, preparing your system, performing a straightforward installation using Docker, initial configuration, and adding your music library.
Intermediate: Focuses on multi-user setups, refining your library with proper metadata, and connecting various client applications to your server.
Advanced: Delves into securing your server with HTTPS using a reverse proxy, fine-tuning performance and features through advanced configuration, and implementing robust backup and update strategies.

Each theoretical section is followed by a practical "Workshop" designed to reinforce your learning through hands-on, step-by-step projects. We assume a basic familiarity with Linux command-line operations. By the end of this guide, you will have a fully functional, secure, and personalized music streaming server tailored to your needs. Let's begin the journey of liberating your music collection!

1. Getting Started with Airsonic-Advanced

This initial section lays the groundwork for deploying Airsonic-Advanced. We'll explore what Airsonic-Advanced is, its core features, the underlying technology, and the necessary prerequisites for running it successfully on your own server.

Understanding Airsonic-Advanced

Airsonic-Advanced is a modern fork of the Airsonic project, which aimed to continue the legacy of the popular Subsonic media server after its development became less open. The "Advanced" fork specifically focuses on continuous development, incorporating new features, bug fixes, and improvements contributed by the open-source community.

Key Features:

Web-Based Access: Provides a clean and intuitive web interface for browsing, managing, and playing your music.
Multi-User Support: Allows creating separate accounts for different users, each with potentially different permissions (streaming, downloading, administration, etc.).
Wide Format Support: Handles a vast array of audio formats (MP3, AAC, FLAC, Ogg Vorbis, WMA, ALAC, OPUS, etc.).
Transcoding: Can automatically convert music files on-the-fly to a lower bitrate or different format, saving bandwidth or ensuring compatibility with specific client devices. This is particularly useful for mobile streaming.
Subsonic API Compatibility: Implements the widely adopted Subsonic API, enabling compatibility with a large ecosystem of third-party mobile and desktop client applications.
Playlist Management: Create, save, and manage personal or shared playlists.
Podcast Receiver: Can subscribe to and download podcast episodes.
Metadata Handling: Reads embedded tags (ID3, Vorbis comments) and fetches cover art automatically.
Open Source: Free to use, modify, and distribute under an open-source license (GPLv3).

Architecture:

Airsonic-Advanced is primarily a Java application. It runs as a server process, typically packaged within a servlet container like Jetty or Tomcat (often embedded within the application itself). It exposes a web interface (usually on port 4040 by default) and the Subsonic API endpoint. It scans designated media folders, parses metadata from music files, and stores this information in an internal database (HSQLDB by default, but configurable to use external databases like PostgreSQL).

Prerequisites:

Before installing Airsonic-Advanced, ensure your system meets the following minimum requirements:

Operating System: Linux (recommended, e.g., Ubuntu, Debian, CentOS, Fedora), Windows, or macOS. This guide will primarily focus on Linux (Ubuntu/Debian).
Java Runtime Environment (JRE): Airsonic-Advanced requires Java 11 or later. OpenJDK is the recommended distribution.
RAM: At least 512MB of RAM dedicated to Airsonic is recommended for smaller libraries. Larger libraries (tens of thousands of tracks) will benefit significantly from 1GB or more.
Disk Space: Enough space for the Airsonic application itself (relatively small), its database and cache (can grow depending on library size and cover art), and, most importantly, your music collection.
CPU: A reasonably modern CPU is needed, especially if you plan to use transcoding frequently, as this process is CPU-intensive.

Workshop: Preparing Your System

In this workshop, we will prepare a typical Linux server (Ubuntu 22.04 LTS assumed, commands may vary slightly for other distributions) by installing the necessary Java runtime and creating the directories that Airsonic-Advanced will use.

Objective: Install Java 11+ and create dedicated directories for Airsonic-Advanced configuration and media storage.

Steps:

Update Package Lists: Open a terminal on your server. It's always good practice to start by updating your package manager's list of available packages.
```
sudo apt update
```
Explanation: sudo executes the command with administrative privileges. apt update downloads the latest package information from the repositories defined in your system's sources lists.
Install Java (OpenJDK 17): We will install OpenJDK 17, which is a widely supported Long-Term Support (LTS) version suitable for Airsonic-Advanced.
```
sudo apt install openjdk-17-jre -y
```
Explanation: apt install is the command to install packages. openjdk-17-jre is the package name for the Java Runtime Environment (JRE) version 17. The -y flag automatically confirms the installation prompt, useful in scripts or tutorials.
Verify Java Installation: Check that Java was installed correctly and is the active version.
```
java -version
```
You should see output similar to this (details might vary slightly):
```
openjdk version "17.0.x" 202x-xx-xx
OpenJDK Runtime Environment (build 17.0.x+x-Ubuntu-x)
OpenJDK 64-Bit Server VM (build 17.0.x+x-Ubuntu-x, mixed mode, sharing)
```
Explanation: The java -version command invokes the Java executable and asks it to print its version information. Seeing output confirming version 17 or higher means the installation was successful.
Create Airsonic Data Directory: We'll create a central directory to hold Airsonic's configuration, database, logs, and cache. Using /srv (service data) is a common convention for persistent application data.
```
sudo mkdir -p /srv/airsonic-advanced/config
```
Explanation: mkdir creates directories. The -p flag ensures that parent directories are created if they don't exist (i.e., it creates /srv if needed, then /srv/airsonic-advanced, then /srv/airsonic-advanced/config). We'll map this directory later using Docker volumes.
Create Media Directories: Create directories where your actual music files will reside. You might want separate folders for music, podcasts, and playlists if you plan to use those features distinctly within Airsonic.
```
sudo mkdir -p /srv/airsonic-advanced/music
sudo mkdir -p /srv/airsonic-advanced/podcasts
sudo mkdir -p /srv/airsonic-advanced/playlists
```
Explanation: Similar to the previous step, this creates the necessary directories under /srv/airsonic-advanced. Separating media types on the host filesystem can help with organization and potential backup strategies.
Set Permissions (Placeholder - Docker Handles This Better): When running directly on the host, you'd need to set appropriate permissions for the user running Airsonic. However, when using Docker (as we will in the next section), it's often easier to manage permissions using PUID/PGID environment variables, which we will cover there. For now, just creating the directories with sudo (owned by root) is sufficient, as Docker volumes can often handle the necessary mappings. If you were not using Docker, you might run commands like sudo chown <user>:<group> /srv/airsonic-advanced -R. We will revisit permissions in the Docker context.

You have now successfully installed the required Java runtime and prepared the basic directory structure for your Airsonic-Advanced installation. The system is ready for the next step: installing Airsonic-Advanced itself using Docker.

2. Basic Installation using Docker

While Airsonic-Advanced can be installed directly on the host system (e.g., using the .war file), using Docker offers significant advantages for self-hosting. This section explains why Docker is beneficial and guides you through installing Airsonic-Advanced using Docker Compose.

Why Docker?

Docker is a platform for developing, shipping, and running applications in containers. Containers package up an application with all its dependencies (libraries, system tools, code, runtime) into a single unit.

Benefits for Self-Hosting Airsonic-Advanced:

Isolation: Airsonic runs in its own isolated environment, separate from your host operating system and other applications. This prevents conflicts between dependencies (e.g., different Java versions required by other apps).
Dependency Management: The Docker image includes the correct Java version and any other dependencies needed by Airsonic. You don't need to manage these manually on your host system (beyond installing Docker itself).
Reproducibility: A Docker setup defined in a docker-compose.yml file ensures you can easily recreate the exact same environment on different machines or after a system reinstall.
Ease of Updates: Updating Airsonic is often as simple as pulling the latest Docker image and restarting the container.
Simplified Installation: Complex setup steps are often encapsulated within the Docker image's build process, making the initial deployment much easier.

Core Docker Concepts:

Image: A read-only template containing the application and its dependencies. You can build your own images or use pre-built ones from registries like Docker Hub (e.g., the official airsonic-advanced/airsonic-advanced image).
Container: A runnable instance of an image. It's a lightweight, isolated process running on the host system's kernel.
Volume: A mechanism for persisting data generated by and used by Docker containers. Volumes map a directory inside the container to a directory on the host filesystem, ensuring data (like Airsonic's configuration or your music library) survives container restarts or updates.
Port Mapping: Allows you to expose a port from inside the container (e.g., Airsonic's default port 4040) to a port on your host machine, making the application accessible from your network.
Docker Compose: A tool for defining and running multi-container Docker applications. It uses a YAML file (docker-compose.yml) to configure the application's services, networks, and volumes, simplifying the management of containerized applications.

Installing Docker and Docker Compose

Before running Airsonic-Advanced in Docker, you need to install Docker Engine and Docker Compose on your host system.

Installation on Ubuntu/Debian:

Uninstall Old Versions (Optional):

sudo apt-get remove docker docker-engine docker.io containerd runc

Set up Docker's apt Repository:

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg lsb-release -y
sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Explanation: These commands install prerequisites, download Docker's official GPG key for verifying packages, and add the Docker software repository to your system's package sources.

Install Docker Engine:
```
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
```
Explanation: This installs the Docker Community Edition (CE) engine, command-line interface (CLI), containerd runtime, and the Docker Compose plugin (which integrates docker compose directly into the Docker CLI).
Verify Docker Installation:
```
sudo docker run hello-world
```
Explanation: This command downloads a small test image and runs it in a container. If successful, it prints a confirmation message, indicating Docker is installed and working.
Add User to Docker Group (Optional but Recommended): To run docker commands without sudo every time, add your user to the docker group.
```
sudo usermod -aG docker $USER
```
Explanation: usermod modifies user accounts. -aG appends the user to the specified supplementary group (docker). $USER is an environment variable representing your current username. Important: You need to log out and log back in (or run newgrp docker in your current shell) for this group change to take effect.

Running Airsonic-Advanced with Docker Compose

Using Docker Compose makes managing the Airsonic-Advanced container significantly easier. We'll create a docker-compose.yml file to define the service.

Create a Project Directory: Let's organize our Docker Compose file.
```
mkdir ~/airsonic-docker
cd ~/airsonic-docker
```

Create docker-compose.yml: Create a file named docker-compose.yml in the ~/airsonic-docker directory using a text editor (like nano or vim):

nano docker-compose.yml

Paste the following content into the file:

version: '3.8' # Specifies the Docker Compose file format version

services:
  airsonic:
    image: airsonicadvanced/airsonic-advanced:latest # Use the official image
    container_name: airsonic-advanced # Assign a specific name to the container
    environment:
      # --- Basic Settings ---
      - PUID=1000 # User ID Airsonic runs as inside the container. Change to your user's ID!
      - PGID=1000 # Group ID Airsonic runs as inside the container. Change to your user's GID!
      - TZ=Europe/London # Set your timezone, e.g., America/New_York, Asia/Tokyo
      # --- Optional Settings (Defaults are usually fine) ---
      # - CONTEXT_PATH=/airsonic # Access Airsonic via http://<host>:4040/airsonic (useful behind reverse proxy)
      # - JAVA_OPTS=-Xmx1024m # Increase memory allocation (e.g., 1GB) if needed for large libraries
    volumes:
      # Map host directories to container directories for persistent data
      - /srv/airsonic-advanced/config:/config # Configuration, database, logs, cache
      - /srv/airsonic-advanced/music:/music # Your music library
      - /srv/airsonic-advanced/podcasts:/podcasts # Downloaded podcasts
      - /srv/airsonic-advanced/playlists:/playlists # Saved playlists
    ports:
      # Map host port 4040 to container port 4040 (Airsonic's default web UI)
      - "4040:4040"
    restart: unless-stopped # Automatically restart the container unless manually stopped

Explanation of docker-compose.yml:

version: '3.8': Defines the version of the Compose file syntax being used.
services:: This section defines the different application components (containers). We only have one service here, named airsonic.
image: airsonicadvanced/airsonic-advanced:latest: Specifies the Docker image to use. We're using the official airsonic-advanced image from Docker Hub, tagged latest. It's generally recommended to pin to a specific version tag in production for stability, but latest is fine for getting started.
container_name: airsonic-advanced: Gives the running container a fixed, recognizable name.
environment:: Defines environment variables passed into the container. These are crucial for configuring Airsonic:
- PUID and PGID: Critically important for permissions. These variables tell the container to run the Airsonic process using this specific User ID (UID) and Group ID (GID). You must change 1000 to match the UID and GID of the user who owns the host directories (/srv/airsonic-advanced/...). If the host directories are owned by root (UID 0, GID 0), you could use PUID=0 and PGID=0, but it's generally better practice to run containers as a non-root user. To find your user's UID and GID, run the command id $USER in your terminal. It will output something like uid=1000(youruser) gid=1000(youruser) groups=1000(youruser),.... Use the uid and gid numbers.
- TZ: Sets the timezone inside the container. This ensures logs and scheduled tasks use the correct time. Find your timezone identifier (e.g., from timedatectl list-timezones).
- CONTEXT_PATH (Optional, Commented Out): If you want to access Airsonic at a subpath (e.g., http://yourserver/airsonic instead of http://yourserver/), uncomment this and set the desired path. This is often used when running behind a reverse proxy.
- JAVA_OPTS (Optional, Commented Out): Allows passing options directly to the Java Virtual Machine (JVM). -Xmx1024m sets the maximum Java heap size (memory) to 1024 megabytes (1GB). The default is usually 512MB. Increase this if you have a very large library or experience performance issues.
volumes:: Defines the data persistence mappings. Each line follows the format - /path/on/host:/path/in/container.
- /srv/airsonic-advanced/config:/config: Maps the host directory we created earlier to /config inside the container, where Airsonic stores its vital data.
- /srv/airsonic-advanced/music:/music: Maps the host music directory to /music inside the container. Airsonic will look for music here.
- /srv/airsonic-advanced/podcasts:/podcasts: Maps the host podcast directory.
- /srv/airsonic-advanced/playlists:/playlists: Maps the host playlist directory.
ports:: Exposes container ports to the host machine. - "4040:4040" maps port 4040 on the host to port 4040 inside the container, making the web UI accessible via http://<your-server-ip>:4040.
restart: unless-stopped: Defines the container's restart policy. unless-stopped means Docker will automatically restart the container if it crashes or if the Docker daemon restarts (e.g., after a server reboot), unless you explicitly stop the container manually.

Workshop: Your First Airsonic-Advanced Instance

Let's bring Airsonic-Advanced to life using the Docker Compose file we just created.

Objective: Launch the Airsonic-Advanced container, verify it's running, and access the web interface for the first time.

Prerequisites: Docker and Docker Compose installed, docker-compose.yml file created, host directories (/srv/airsonic-advanced/...) created.

Steps:

Determine Your User ID (PUID) and Group ID (PGID): Open your terminal and run:
```
id $USER
```
Note down the uid and gid numbers. For example: uid=1001(myuser) gid=1001(myuser).
Update docker-compose.yml: Edit your docker-compose.yml file (nano ~/airsonic-docker/docker-compose.yml) and replace the default PUID=1000 and PGID=1000 values with the actual UID and GID you found in the previous step. Also, set the correct TZ for your location. Save and close the file.
Set Ownership of Host Directories (If Necessary): Ensure the host directories (/srv/airsonic-advanced/*) are owned by the user ID and group ID you specified in the docker-compose.yml file. If you created them with sudo, they might be owned by root. Change ownership:
```
# Example: If your PUID is 1001 and PGID is 1001
sudo chown -R 1001:1001 /srv/airsonic-advanced
```
Replace 1001:1001 with your actual PUID:PGID. The -R flag applies the ownership recursively to all files and subdirectories. Explanation: This step is crucial. By setting the host directory ownership to match the PUID/PGID, you ensure that the Airsonic process running inside the container (as that user/group) has the necessary permissions to read and write files in the mapped volumes (especially the /config volume).
Navigate to the Project Directory: Make sure your terminal is in the directory containing the docker-compose.yml file.
```
cd ~/airsonic-docker
```
Launch the Container: Run the following command to download the Airsonic-Advanced image (if not already present) and start the container in detached mode (running in the background).
```
docker compose up -d
```
Explanation: docker compose invokes the Docker Compose plugin. up tells Compose to start the services defined in the docker-compose.yml file. -d stands for "detached," meaning the command will exit after starting the containers, leaving them running in the background. If you omit -d, logs will be streamed to your terminal, and pressing Ctrl+C will stop the container.

Check Container Status: Verify that the container is running.

docker compose ps

You should see output indicating the airsonic-advanced container is "Up" or "Running".

NAME                 COMMAND                  SERVICE             STATUS              PORTS
airsonic-advanced    "/init"                  airsonic            running             0.0.0.0:4040->4040/tcp

View Container Logs (Optional but Useful): If you encounter issues or want to see what Airsonic is doing during startup, check its logs.
```
docker compose logs -f
```
Explanation: logs retrieves the logs from the service(s). -f follows the log output in real-time. Press Ctrl+C to stop following the logs. Look for lines indicating the server has started successfully, often mentioning the port it's listening on.
Access the Web UI: Open a web browser on a computer connected to the same network as your server. Navigate to: http://<your-server-ip>:4040 Replace <your-server-ip> with the actual IP address of the machine running Docker. Explanation: You are connecting to the port (4040) that you mapped on your host machine in the docker-compose.yml file, which Docker forwards to the Airsonic application running inside the container.

You should be greeted by the Airsonic-Advanced setup screen.

Congratulations! You have successfully installed and launched Airsonic-Advanced using Docker Compose. The server is running and accessible on your local network.

3. Initial Configuration and Adding Music

With Airsonic-Advanced running, the next steps involve the initial setup through the web interface, configuring it to find your music library, and understanding how it scans and processes your media files.

When you first access the Airsonic-Advanced web UI (http://<your-server-ip>:4040), you'll be guided through a brief setup process.

Welcome Screen: Acknowledges the first-time setup.
Admin User Creation: You'll be prompted to create the primary administrator account.
- Username: Choose a username (e.g., admin).
- Password: Set a strong, unique password for this account.
- Confirm Password: Re-enter the password.
Setup Complete: Once the admin user is created, you'll be logged in and taken to the main Airsonic-Advanced interface.

It is crucial to remember this admin username and password, as it grants full control over the Airsonic-Advanced instance.

Configuring Media Folders

Airsonic-Advanced needs to know where to find your music files. You need to configure this within the web UI, pointing it to the paths inside the container that we mapped using Docker volumes.

Navigate to Settings: Log in with your admin account. In the top navigation bar, click on "Settings".
Go to Media Folders: In the left-hand sidebar under the "Server Settings" section, click on "Media folders".
Add Music Folder:
- You'll see sections for "Music folders", "Podcast folders", and "Playlist folders".
- Under "Music folders", click the "Add media folder" button (or similar wording).
- Name: Give the folder a descriptive name (e.g., "My Music Library"). This name is only for display within Airsonic.
- Folder: Enter the path inside the container where your music volume is mapped. Based on our docker-compose.yml, this is /music. Do not enter the host path (/srv/airsonic-advanced/music) here.
- Enabled: Ensure the checkbox is ticked.
- Click "Save".
Configure Podcast/Playlist Folders (Optional):
- If you plan to use Airsonic for podcasts or want it to manage playlist files in a specific location, repeat the process under the "Podcast folders" and "Playlist folders" sections, using the corresponding container paths (/podcasts, /playlists).
Save Settings: After adding/modifying folders, scroll down and click the main "Save" button at the bottom of the Media Folders page.

Understanding the Scanning Process

Once media folders are configured, Airsonic needs to scan them to build its internal library.

How it Works: Airsonic recursively traverses the directories you specified (e.g., /music). For each compatible audio file it finds, it attempts to read embedded metadata (tags) like artist, album, title, track number, genre, year, and embedded cover art.
Library Building: This extracted information is stored in Airsonic's internal database. This database allows for fast searching, browsing by artist/album, and displaying track information without needing to re-read the file tags every time.
Cover Art: Airsonic prioritizes embedded cover art within music files. If cover art is missing, it may look for image files (like folder.jpg, cover.jpg) in the album's directory. It can also be configured (under Settings -> Metadata) to fetch cover art from online sources like Last.fm, but this is often disabled by default. It caches downloaded or resized cover art in its configuration directory (/config/cache/transcode or similar).
Scan Triggering:
- Manual Scan: You can trigger a scan manually at any time by going to "Settings" -> "Media folders" and clicking the "Scan media folders now" button.
- Scheduled Scan: By default, Airsonic performs an automatic scan periodically (e.g., once per day). You can configure the interval in "Settings" -> "Media folders" -> "Scan interval (minutes)". Setting it to 0 disables automatic scanning.
Potential Issues:
- Inconsistent Tags: Files with missing or inconsistent tags (e.g., slightly different album titles or artist names for tracks within the same album) can lead to split albums or miscategorized tracks in the library.
- Unsupported Formats: While support is broad, very obscure or DRM-protected files might not be recognized.
- Permissions: If the Airsonic process (running as PUID/PGID inside the container) doesn't have read permissions for the files in the mapped volume, it won't be able to scan them. This is why setting PUID/PGID and host directory ownership correctly is vital.
- Large Libraries: The initial scan of a very large library can take a significant amount of time and consume CPU resources. Subsequent scans are usually faster as they primarily look for changes.

Workshop: Adding Your First Album

Let's add some music to our Airsonic server and see it appear in the library.

Objective: Copy music files into the designated host directory, configure Airsonic to scan that directory, trigger a scan, and verify the music is playable.

Prerequisites: Airsonic-Advanced running, accessible web UI, admin login credentials.

Steps:

Prepare Music Files: Find an album or a few music tracks on your computer. For testing, you can often find royalty-free music online (e.g., searching for "Creative Commons music downloads"). Ensure the files are in a common format like MP3 or FLAC. Let's assume you have an album in a folder named Example Artist - Example Album.

Copy Music to Host Directory: Copy the entire album folder (Example Artist - Example Album) into the host directory you mapped as the /music volume in your docker-compose.yml. In our setup, this is /srv/airsonic-advanced/music/. You might need sudo or appropriate permissions to copy files there.

# Example using scp from your local machine to the server:
# scp -r "/path/to/Example Artist - Example Album" your_server_user@<your-server-ip>:/tmp/
# ssh your_server_user@<your-server-ip>
# sudo mv /tmp/"Example Artist - Example Album" /srv/airsonic-advanced/music/

# Example if copying locally on the server:
# sudo cp -r "/path/on/server/to/Example Artist - Example Album" /srv/airsonic-advanced/music/

Ensure the files within /srv/airsonic-advanced/music/Example Artist - Example Album/ inherit the correct ownership (the PUID/PGID you set) so Airsonic can read them. If you used sudo to copy/move, you might need to reset the ownership:

# Example: If your PUID is 1001 and PGID is 1001
sudo chown -R 1001:1001 /srv/airsonic-advanced/music/"Example Artist - Example Album"

Configure Media Folder in Airsonic (If Not Done): If you haven't already, log in to the Airsonic web UI as admin. Go to "Settings" -> "Media folders". Add a "Music folder" with the name "My Music" and the path /music. Save the folder configuration, then save the overall settings page.
Trigger a Media Scan: While still in "Settings" -> "Media folders", click the button labeled "Scan media folders now". You should see a confirmation that the scan has started. Depending on the number of files, it might take a few seconds to a few minutes.
Check Scan Status (Optional): You can monitor the scan progress by looking at the Airsonic logs (docker compose logs -f airsonic). You'll likely see lines related to scanning directories and identifying files.
Verify Music in Library: Once the scan is complete (give it a minute or two), navigate back to the Airsonic "Home" page or browse the library using the "Library" link in the top navigation bar. You should now see "Example Artist" listed under Artists and "Example Album" under Albums. Click through to see the tracks.
Play a Track: Click on one of the tracks from the newly added album. It should start playing in the web player at the bottom of the screen.

You have now successfully added music to your Airsonic-Advanced server and confirmed that it can scan and play your files. You can continue adding the rest of your music library using the same process. Remember that good metadata (tags) on your files will significantly improve the browsing experience – a topic we'll explore further in the Intermediate section.

4. User Management and Access Control

As you share your Airsonic-Advanced instance or use it across different devices and contexts, managing users and their permissions becomes essential. This section covers creating individual user accounts and configuring their access levels.

Creating and Managing Users

Running everything as the initial administrator account is convenient for setup but insecure and inflexible for multiple users (family members, friends) or different client types. Creating separate user accounts allows for personalization (playlists, listening history) and granular control over permissions.

Steps to Create a New User:

Log in as Admin: Access the Airsonic web UI using your administrator account.
Navigate to User Settings: Click on "Settings" in the top navigation bar.
Go to Users: In the left-hand sidebar, under the "Users & Sharing" section, click on "Users".
Create New User: You'll see the list of existing users (initially, just your admin account). Click the "Create new user" button (or similar).
Enter User Details:
- Username: Choose a unique username for the new user (e.g., john_doe). Usernames are case-insensitive.
- Password: Set an initial password for the user. They can usually change this later if allowed.
- Confirm Password: Re-enter the password.
- Email Address (Optional): Can be used for notifications or password resets if configured.
- Administrator Role: Leave this unchecked unless you want this user to have full administrative privileges like your main admin account.
Assign Permissions: This is the crucial part for access control. Check the boxes corresponding to the privileges you want to grant this user:
- Stream music: Allows the user to listen to music. This is the most fundamental permission for a music server.
- Download music: Allows the user to download individual tracks or entire albums. Disable this if you only want to allow streaming.
- Upload music: Allows the user to upload music files to the server via the web UI or compatible clients. Be cautious with this permission.
- Add/remove podcasts: Allows the user to manage podcast subscriptions.
- Change password and settings: Allows the user to change their own password, avatar, and some personal preferences. Highly recommended for non-admin users.
- Create/edit playlists: Allows the user to manage their own playlists.
- Administer playlists: Allows the user to manage all users' playlists (usually reserved for admin).
- Administer users: Allows the user to create, edit, and delete other users (usually reserved for admin).
- Administer server settings: Allows access to the main server configuration sections (media folders, transcoding, etc. - usually reserved for admin).
- Cover art management: Allows updating or changing cover art.
- Comment management: Allows adding/editing comments on albums/tracks.
- Manage Shares: Allows creating shareable links to tracks/albums (if enabled server-wide).
- Podcast episode management: Allows deleting downloaded podcast episodes.
Folder Access (Optional but Powerful):
- By default, users usually have access to all configured media folders. However, you can restrict access to specific folders per user. Scroll down to the "Folder Access Permissions" section.
- Uncheck "Allow access to all media folders".
- Select the specific media folders (using the names you defined, e.g., "My Music Library") that this user should be able to access. This is useful if you have different libraries (e.g., Kids' Music, Classical Music) and want to restrict certain users.
Save User: Click the "Save" button at the bottom of the page. The new user account is now created and ready to be used.

Managing Existing Users:

From the "Settings" -> "Users" page, you can:

Edit: Click the pencil icon next to a username to modify their password, permissions, or folder access.
Delete: Click the trashcan icon to permanently remove a user account. Be careful, as this action cannot be undone.

Fine-tuning Permissions

Choosing the right combination of permissions depends on your specific use case:

Personal Use (Single User): Your admin account might be sufficient, although creating a separate non-admin user for daily listening is still good practice from a security perspective (principle of least privilege).
Family Members: Create individual accounts. Grant Stream music, Change password and settings, and Create/edit playlists. Decide whether to grant Download music based on your preferences. Restrict administrative permissions. You might use Folder Access if you have age-appropriate libraries.
Friends (Remote Access): Be more restrictive. Grant Stream music, Change password and settings. Strongly consider disabling Download music and Upload music. Ensure your server has sufficient bandwidth and CPU for concurrent streams, especially if transcoding is involved.
Specific Clients/Devices: You might create a dedicated user account for a device (e.g., a network music player) with only Stream music permissions and potentially restricted folder access.

Always apply the principle of least privilege: grant only the permissions necessary for the user to perform their intended tasks. Avoid granting administrative rights unless absolutely necessary.

Workshop: Setting Up a Family Account

Let's create a restricted user account suitable for a family member who should only be able to stream music and manage their own playlists.

Objective: Create a new non-admin user, assign specific limited permissions, and verify these restrictions by logging in as the new user.

Prerequisites: Airsonic-Advanced running, admin access.

Steps:

Log in as Admin: Access your Airsonic-Advanced instance (http://<your-server-ip>:4040) with your admin credentials.
Navigate to User Creation: Go to "Settings" -> "Users" -> "Create new user".
Enter Basic Details:
- Username: family_member
- Password: Choose a password (e.g., MusicLover123!)
- Confirm Password: Re-enter the password.
- Administrator Role: Ensure this is unchecked.
Assign Permissions: Check only the following boxes:
- Stream music
- Change password and settings
- Create/edit playlists
- Leave all other boxes (especially Download music, Upload music, and all administrative permissions) unchecked.
Configure Folder Access (Optional):
- For this workshop, let's assume the family member should have access to all music. Leave the "Allow access to all media folders" checkbox checked (or ensure your primary music folder is selected if you uncheck it).
Save the User: Click the "Save" button.
Log Out as Admin: Click your admin username in the top-right corner and select "Log out".
Log In as New User: On the login screen, enter the username family_member and the password you set (MusicLover123!).
Verify Restrictions:
- Streaming: Browse the library and try playing music. This should work.
- Playlists: Go to "Playlists" in the top navigation. You should be able to create a new playlist, add songs to it, and save it.
- Downloads: Browse to an album or track. Look for a download button (often a downward arrow). It should either be missing or greyed out/non-functional.
- Settings: Click on "Settings". You should only see limited options related to the user account (like "Personal", "Password", "Players"). You should not see server administration sections like "Users", "Media folders", "Network", "Transcoding", etc.
- Upload: Check if there is any option to upload files. There shouldn't be.
Change Password (Optional but Recommended): As the family_member user, go to "Settings" -> "Password". Change the initial password to something else. This confirms the Change password and settings permission works.

You have successfully created a restricted user account, demonstrating how Airsonic-Advanced allows fine-grained control over user capabilities. This is fundamental for securely sharing your music library.

5. Enhancing Your Library with Metadata and Cover Art

The quality of your listening experience in Airsonic-Advanced heavily depends on the quality of your music library's metadata (tags) and associated cover art. Well-organized metadata ensures accurate sorting, filtering, searching, and display. This section explores the importance of metadata and how to manage it effectively.

The Importance of Good Metadata (Tags)

Metadata, in the context of digital music, refers to the information embedded within the audio files themselves that describes the music. Common tag formats include ID3 (for MP3 files, with versions ID3v1, ID3v2.3, ID3v2.4 being common) and Vorbis comments (for Ogg Vorbis and FLAC files).

Why is good metadata crucial?

Organization: Airsonic uses tags to categorize music. Accurate Artist, Album, Track Number, and Title tags are essential for the library view to make sense.
Browsing & Discovery: Consistent Genre, Year, and Album Artist tags allow users to browse and filter the library effectively. The Album Artist tag is particularly important for compilations or albums with guest artists, ensuring the album appears as a single entry under the main artist (e.g., "Various Artists") rather than being split across multiple artists.
Searching: Accurate tags make searching for specific tracks, albums, or artists reliable.
Display: Client applications (web UI, mobile apps) use metadata to display information while playing music. Missing or incorrect tags lead to a poor user experience (e.g., showing "Unknown Artist").
Smart Playlists: Features like generating random playlists based on genre or year rely entirely on the accuracy of these tags.

Recommended Essential Tags:

Ensure most of your files have at least these tags consistently filled:

Title: The name of the track.
Artist: The primary artist performing the track.
Album: The name of the album the track belongs to.
Track Number: The position of the track within the album (e.g., 1, 2, or 1/12, 2/12). Consistent formatting helps.
Album Artist: The primary artist for the entire album. For single-artist albums, this is often the same as the Artist. For compilations, it should be set to "Various Artists" (or similar consistent name). This tag is key to preventing albums from being split.
Year or Date: The release year of the album.
Genre: The musical genre (e.g., Rock, Jazz, Electronic). Consistency helps browsing.
Disc Number: Important for multi-disc albums (e.g., 1/2, 2/2). Ensures tracks are ordered correctly across discs.

Using External Tools for Tagging

Manually editing tags for hundreds or thousands of files is impractical. Dedicated music tagging applications are indispensable for managing a digital music library efficiently.

Popular Tagging Tools:

MusicBrainz Picard (Cross-Platform, Free): Highly recommended. Picard uses the extensive MusicBrainz open music encyclopedia to identify and tag your music files accurately.
- Acoustic Fingerprinting: Can identify tracks even with minimal existing metadata by analyzing the audio itself (using AcoustID).
- Album-Oriented: Groups files into album clusters before tagging, making it excellent for ensuring album consistency.
- Extensible: Supports plugins for additional features and tag sources.
- Cover Art: Can automatically download and embed high-quality cover art from sources like the Cover Art Archive.
Mp3tag (Windows, Free): A powerful and popular tag editor with batch editing capabilities, support for various tag formats, and integration with online databases like MusicBrainz, Discogs, and freedb.
EasyTAG (Linux, Free): A GTK+-based tag editor for Linux, supporting multiple formats and featuring basic database lookup capabilities.
foobar2000 (Windows, Free): Primarily a music player, but known for its powerful metadata editing capabilities via its properties dialog and plugins like foo_musicbrainz.

Benefits of Using Taggers:

Consistency: Enforce consistent naming conventions for artists, albums, genres.
Accuracy: Fetch correct information from reliable online databases.
Completeness: Fill in missing tags like Year, Genre, Album Artist.
Batch Processing: Edit tags for entire albums or groups of files simultaneously.
Cover Art: Easily find and embed high-quality cover art.
Renaming Files: Many taggers can automatically rename files and folders based on tag information (e.g., Artist/Year - Album/TrackNumber - Title.mp3), further organizing your library structure.

Airsonic's Metadata Handling

Airsonic reads the tags from your files during its media scan process.

Tag Priority: It generally reads standard tags from common formats (ID3 for MP3, Vorbis comments for FLAC/Ogg). If multiple tag versions exist (e.g., ID3v1 and ID3v2), ID3v2 usually takes precedence as it's more capable.
Embedded Cover Art: Airsonic strongly prefers cover art embedded directly within the music files. This is the most reliable way to ensure the correct art is displayed. Most tagging tools can embed downloaded art.
External Cover Art Files: If embedded art is missing, Airsonic might look for image files (e.g., cover.jpg, folder.jpg, front.jpg) in the same directory as the music files. The exact filenames it searches for might be configurable or depend on the version.
Online Lookups (Optional): In "Settings" -> "Metadata", you can configure Airsonic to automatically download metadata and cover art from online sources (like Last.fm). However, this can sometimes lead to incorrect matches, especially for less common music. Relying on well-tagged files using external tools before scanning is generally more reliable.
Caching: Airsonic caches cover art (often resized versions) in its configuration directory (/config/cache/...) to speed up loading in the UI and clients.
Resolving Discrepancies: If you update tags or cover art using an external tool after Airsonic has already scanned the files, you must trigger a rescan in Airsonic for the changes to be reflected. Go to "Settings" -> "Media folders" -> "Scan media folders now". Sometimes, for deeply cached information (especially cover art), you might need to select "Scan folders for new and changed files, clear cache information and rebuild library". Use this option sparingly as it takes longer. For persistent cover art issues, clearing the cache directory manually (/config/cache) might be necessary (stop Airsonic first).

Workshop: Cleaning Up Album Metadata

Let's take an album from your library (or download a sample one that likely has poor tags) and use MusicBrainz Picard to clean up its metadata and embed cover art.

Objective: Use an external tagging tool (MusicBrainz Picard) to correct tags and add cover art, then rescan in Airsonic to see the improvements.

Prerequisites: Airsonic-Advanced running, some music added, MusicBrainz Picard installed on your local computer (download from picard.musicbrainz.org).

Steps:

Identify an Album for Cleanup: Browse your Airsonic library and find an album that has issues: missing cover art, inconsistent artist/album names, missing track numbers, or incorrect genre/year. Alternatively, find a poorly tagged album online for testing.
Copy Album Files Locally: Copy the problematic album's folder from your server's music directory (/srv/airsonic-advanced/music/) to your local computer where Picard is installed. This avoids working directly on the server files initially.
Install MusicBrainz Picard: If you haven't already, download and install Picard for your operating system.
Launch Picard: Open the MusicBrainz Picard application.
Add Album Files to Picard: Drag the album folder from your local computer into the left-hand pane ("Unmatched Files") of Picard. The individual tracks will appear.
Cluster Files: Select the added tracks in the left pane and click the "Cluster" button on the toolbar. Picard will attempt to group the files based on their existing metadata, ideally grouping them into a single album cluster.
Lookup/Scan the Album:
- Lookup (Metadata-Based): Select the album cluster in the left pane and click the "Lookup" button. Picard will search the MusicBrainz database based on the existing tags. If it finds a likely match, the album will move to the right-hand pane, associated with a MusicBrainz release entry.
- Scan (Fingerprint-Based): If Lookup fails or tags are minimal, select the cluster/files and click the "Scan" button. Picard will generate AcoustID fingerprints for the tracks and search MusicBrainz based on the audio itself. This is often more accurate but can take longer.
Review the Match: Once matched (in the right-hand pane), Picard displays the tracks fetched from MusicBrainz alongside your files.
- Compare the track listings. Ensure the number of tracks and titles match.
- Check the metadata (Artist, Album Artist, Year, Genre) fetched from MusicBrainz in the bottom pane. It should look correct and complete.
- Picard usually highlights changes it intends to make (e.g., green for additions, orange for modifications).
- A cover art image should appear at the bottom right if available from the Cover Art Archive. Ensure it's the correct cover.
Save Changes (Embed Metadata and Cover Art):
- If the match looks correct, select the album entry in the right-hand pane.
- Click the "Save" button on the toolbar. Picard will now:
  - Write the corrected tags (fetched from MusicBrainz) into your music files.
  - Download and embed the cover art into the files.
- Wait for the process to complete for all tracks (the icons next to the tracks should turn green).
Copy Updated Files Back to Server: Delete the old version of the album folder from your Airsonic server's music directory (sudo rm -rf "/srv/airsonic-advanced/music/Problem Album Folder"). Then, copy the newly tagged and updated album folder from your local computer back to /srv/airsonic-advanced/music/. Ensure the ownership is correct again (sudo chown -R PUID:PGID ...).
Rescan in Airsonic:
- Log in to Airsonic as admin.
- Go to "Settings" -> "Media folders".
- Click "Scan media folders now".
Verify Changes: Once the scan finishes, navigate to the album in your Airsonic library. You should now see:
- The correct, high-quality cover art.
- Consistent and accurate Artist, Album, Album Artist, Year, Genre information.
- Tracks correctly numbered and ordered.

By consistently applying this process to your library, you significantly enhance the usability and enjoyment of your self-hosted Airsonic-Advanced instance. Investing time in good metadata pays off immensely in the long run.

6. Connecting Clients and Mobile Apps

While the Airsonic-Advanced web interface is functional, the real power of a personal music server comes from accessing it through dedicated client applications on your desktop, mobile phone, or other devices. Thanks to the Subsonic API, a wide range of clients are compatible with Airsonic-Advanced.

Understanding the Subsonic API

The Subsonic API (Application Programming Interface) is a set of rules and specifications that allows different software applications (clients) to communicate with a Subsonic-compatible media server (like Airsonic-Advanced). It defines how a client can request information (like the list of artists, albums, or tracks), initiate playback, manage playlists, download files, search the library, and perform other actions.

Protocol: The API typically works over HTTP or HTTPS. Clients send requests to specific URL endpoints on the server (e.g., /rest/ping.view, /rest/getArtists.view, /rest/stream.view).
Authentication: Requests usually include the username and a password (or an API token/key derived from the password) for authentication.
Data Format: The server responds with data, often formatted in XML or JSON.
Compatibility: Because Airsonic-Advanced implements this well-established API, any client designed to work with Subsonic (or its forks like Airsonic, Navidrome, etc.) should generally work with Airsonic-Advanced. Minor incompatibilities can sometimes exist due to specific API extensions or variations, but core functionality is usually supported.

Recommended Desktop and Mobile Clients

Numerous clients leverage the Subsonic API. Here are some popular options across different platforms:

Mobile Clients:

Android:
- DSub: One of the oldest and most feature-rich Subsonic clients. Highly configurable, supports offline caching, transcoding selection, Android Auto. (May require a small one-time purchase for full features, but often has free/trial versions).
- Subsonic Music Streamer (Official): The original client from the Subsonic project. Functionality might vary depending on whether the server is licensed Subsonic or an open-source fork.
- Ultrasonic: A free and open-source client, actively developed. Good feature set, including caching and transcoding support.
- Symfonium: A modern, highly-rated paid client known for its polished interface, advanced features (including unified library from multiple sources), caching, and customization. Often considered one of the best Android options.
iOS:
- substreamer: A popular free client with a clean interface, caching, and good performance.
- play:Sub: Another well-regarded client, often praised for its stability and features (may have an associated cost).
- iSub: One of the original iOS Subsonic clients (may have an associated cost).

Desktop Clients:

Web UI: Don't forget the built-in Airsonic-Advanced web interface! It works on any desktop browser.
Clementine Music Player (Linux, Windows, macOS): A full-featured desktop music player that has native support for Subsonic (you might need to enable the 'Subsonic' service in its preferences). Allows browsing your remote library and streaming tracks directly within Clementine.
Supersonic (Linux, Windows, macOS - Electron-based): A dedicated desktop client specifically for Subsonic/Airsonic servers.
Sublime Music (Linux - GTK-based): Another dedicated Linux desktop client with a focus on fitting in with the GNOME desktop environment.
Various Command-Line Tools: Some CLI tools also exist for interacting with the Subsonic API.

The best client often comes down to personal preference regarding interface design, specific features (like offline caching robustness, gapless playback support, casting support), and cost. It's worth trying a few free options first.

Configuring Client Connections

Connecting a client application to your Airsonic-Advanced server generally requires three pieces of information:

Server URL: This is the address the client needs to reach your Airsonic instance.
- Format: It typically includes the protocol (HTTP or HTTPS), the server's hostname or IP address, the port number, and potentially the context path if you configured one.
- Examples:
  - Local Network (HTTP, default port, no context path): http://192.168.1.100:4040
  - Local Network (HTTP, default port, with context path): http://192.168.1.100:4040/airsonic
  - Remote Access (HTTPS, standard port 443 via reverse proxy, no context path): https://music.yourdomain.com
  - Remote Access (HTTPS, standard port 443 via reverse proxy, with context path): https://yourdomain.com/airsonic
- Important: Ensure you use http or https correctly based on whether you have set up secure access (covered in the Advanced section). When using a reverse proxy for HTTPS (like Nginx Proxy Manager), you typically connect to the standard HTTPS port (443), which doesn't need to be specified in the URL, and use the domain name.
Username: The Airsonic-Advanced username for the account you want to use (e.g., family_member).
Password: The password associated with that Airsonic-Advanced username.

Most clients have a server settings section where you enter this information. Some clients might also ask for an optional server name (just a label for the connection) or have settings for transcoding (allowing the client to request a specific bitrate or format from the server).

Workshop: Connecting DSub (Android)

Let's connect a popular Android client, DSub, to the Airsonic-Advanced instance we set up on the local network. (The steps are conceptually similar for other clients like Ultrasonic or iOS clients like substreamer).

Objective: Install and configure DSub on an Android device to stream music from your local Airsonic-Advanced server over Wi-Fi.

Prerequisites:

Airsonic-Advanced running on your server (http://<your-server-ip>:4040).
An Airsonic user account created (e.g., the family_member account from the previous workshop or your admin account).
An Android device connected to the same Wi-Fi network as the Airsonic server.
Access to the Google Play Store (or an alternative source like F-Droid if using Ultrasonic).

Steps:

Install DSub: On your Android device, open the Google Play Store, search for "DSub", and install the app (developer listed usually as Scott Jackson). There might be a free/trial version available. (Alternatively, search for and install "Ultrasonic" from the Play Store or F-Droid for a fully free option - the setup process is very similar).
Launch DSub: Open the DSub application.
Add Server: You'll likely be prompted to add a server, or you may need to find an "Add Server" or "Settings" menu.
- Server Name / Nickname: Enter a descriptive name, e.g., "My Airsonic" or "Home Music". This is just a label.
- Server Address: This is the crucial part. Enter the URL for your server exactly as needed to access the web UI from your phone's browser on the same Wi-Fi network. Based on our basic setup, this will be: http://<your-server-ip>:4040 (Replace <your-server-ip> with the actual IP address of your server). Do not add a trailing slash / unless you specifically configured a context path.
- Username: Enter the Airsonic username (e.g., family_member).
- Password: Enter the password for that user.
Test Connection: Look for a "Test Connection" or "Login" button. Tap it. DSub will attempt to communicate with your Airsonic server using the details provided.
- Success: You should see a confirmation message like "Connection successful" or "Login successful".
- Failure: If it fails, double-check:
  - Is your phone definitely on the same Wi-Fi network as the server?
  - Did you type the server IP address and port correctly? (e.g., http://192.168.1.100:4040)
  - Is the Airsonic container running (docker compose ps)?
  - Did you type the username and password correctly (case-sensitive)?
  - Is there a firewall on your server blocking incoming connections on port 4040? (Less likely with basic setups, but possible).
Save Server Settings: Once the test is successful, save the server configuration.
Browse Library: DSub should now connect and display your Airsonic library, showing categories like Artists, Albums, Genres, Playlists, etc. Navigate through your library.
Play Music: Select an album or track and tap it to start playback. Music should stream from your server to your phone. Control playback using the DSub interface.
Explore Caching (Optional): Many clients, including DSub, support caching or offline downloads. Explore the settings or long-press menus on albums/tracks to find options like "Cache" or "Download". This allows you to store music locally on your device for listening without a network connection. Test caching an album and then putting your phone in airplane mode to see if you can still play it.

You have now successfully connected a mobile client to your Airsonic-Advanced server, unlocking the convenience of mobile music streaming from your personal library. Connecting other clients follows the same fundamental process of providing the correct Server URL, Username, and Password. The next step in enhancing usability is often securing remote access with HTTPS.

7. Securing Your Airsonic-Advanced Instance with HTTPS

While accessing Airsonic-Advanced over your local network via HTTP might be acceptable, exposing it directly to the internet without encryption is highly insecure. Anyone monitoring the network traffic could potentially intercept your login credentials or see what you're listening to. Using HTTPS (HTTP Secure) encrypts the communication between your clients and the server, protecting your data. The standard and recommended way to enable HTTPS for web applications like Airsonic is by using a reverse proxy.

Why HTTPS is Essential

Encryption: HTTPS uses TLS/SSL protocols to encrypt all data exchanged between the client (your browser or mobile app) and the server (Airsonic). This prevents eavesdroppers on the network (e.g., on public Wi-Fi, or even your ISP) from reading the content of the communication, including usernames, passwords, and browsing activity.
Authentication: An SSL certificate, obtained from a trusted Certificate Authority (CA), verifies the identity of the server. When your browser connects via HTTPS, it checks the certificate to ensure it's connecting to the legitimate server associated with the domain name, helping prevent Man-in-the-Middle (MitM) attacks where an attacker impersonates the server.
Data Integrity: HTTPS ensures that the data exchanged has not been tampered with during transmission.
Browser Requirements: Modern web browsers increasingly flag HTTP sites as "Not Secure" and may restrict certain features (like geolocation or service workers) on non-HTTPS sites.
Client Compatibility: Some mobile clients or web features might function better or exclusively over HTTPS.

Directly configuring SSL/TLS within Airsonic itself is possible but generally not recommended. It complicates the Java configuration and certificate management. A reverse proxy handles this externally, simplifying the setup and providing additional benefits.

Using a Reverse Proxy (Nginx Proxy Manager)

A reverse proxy is a server that sits in front of one or more web servers (like Airsonic), intercepting requests from clients. It forwards those requests to the appropriate backend server and returns the server's response to the client.

Benefits of using a Reverse Proxy for Airsonic:

SSL/TLS Termination: The reverse proxy handles the complexities of HTTPS encryption and decryption. It receives HTTPS requests from clients, decrypts them, forwards them as plain HTTP requests to Airsonic on the local network (which is safe within your trusted environment), receives the HTTP response from Airsonic, encrypts it, and sends it back to the client via HTTPS.
Certificate Management: Tools like Nginx Proxy Manager automate the process of obtaining and renewing free SSL certificates from Let's Encrypt.
Centralized Access Point: You can run multiple web applications (Airsonic, Nextcloud, a blog, etc.) on the same server, each on different internal ports, but make them all accessible via standard ports (80 for HTTP, 443 for HTTPS) using different domain or subdomain names handled by the reverse proxy.
Load Balancing (Advanced): Can distribute incoming requests across multiple instances of an application.
Security: Can provide an additional layer of security, potentially filtering malicious requests.
Compression & Caching: Can compress responses or cache static content to improve performance.

Nginx Proxy Manager (NPM):

Nginx Proxy Manager is a popular, open-source tool that provides a user-friendly web interface for managing Nginx (a powerful web server/reverse proxy) configurations, specifically focused on reverse proxying and SSL certificate management with Let's Encrypt. It runs easily as a Docker container itself.

Setting up Nginx Proxy Manager

We'll install NPM using Docker Compose, similar to how we installed Airsonic.

Create NPM Data Directory:
```
sudo mkdir -p /srv/npm/data
sudo mkdir -p /srv/npm/letsencrypt
```
Explanation: We create persistent storage directories for NPM's configuration/database (data) and the SSL certificates it obtains (letsencrypt).

Create NPM docker-compose.yml: Create a new directory (e.g., ~/npm-docker) and a docker-compose.yml file inside it:

mkdir ~/npm-docker
cd ~/npm-docker
nano docker-compose.yml

Paste the following content:

version: '3.8'
services:
  npm:
    image: 'jc21/nginx-proxy-manager:latest'
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      # Public HTTP Port: Map host port 80 to container port 80
      - '80:80'
      # Public HTTPS Port: Map host port 443 to container port 443
      - '443:443'
      # Admin Web UI: Map host port 81 to container port 81
      - '81:81'
    environment:
      # Use internal SQLite database (simplest setup)
      # For MariaDB/MySQL, see NPM documentation
      DB_SQLITE_FILE: "/data/database.sqlite"
      # Set to '1' to disable built-in healthchecks (optional)
      # DISABLE_IPV6: 'true'
    volumes:
      - /srv/npm/data:/data
      - /srv/npm/letsencrypt:/etc/letsencrypt

Explanation:

image: 'jc21/nginx-proxy-manager:latest': Uses the official NPM image.
ports:
- 80:80 & 443:443: Maps the standard web ports on the host to the container. NPM will listen here for incoming traffic to your proxied applications. Ensure these ports are not already in use by another application on your host.
- 81:81: Maps the port for accessing the NPM administration web UI.
environment: Configures NPM to use an SQLite database file stored in the /data volume.
volumes: Maps the host directories we created to store NPM's persistent data and certificates.

Set Ownership (If Necessary): Depending on your Docker setup and the NPM image's internal user, you might need to adjust ownership of /srv/npm. Often, running the container creation command (docker compose up -d) will correctly initialize permissions within the volumes if they are empty. Check the NPM documentation if you encounter permission errors. Generally, Docker manages volume permissions reasonably well here.
Launch NPM Container:
```
cd ~/npm-docker
docker compose up -d
```
Access NPM Web UI: Open your web browser and navigate to http://<your-server-ip>:81.
- Default Login:
  - Email: admin@example.com
  - Password: changeme
- You will be forced to change these credentials immediately upon first login. Use a strong, unique password.

Configuring NPM for Airsonic

Now, we'll configure NPM to act as a reverse proxy for Airsonic, enabling HTTPS access via a domain name.

Prerequisites:

A Domain Name: You need a registered domain name (e.g., yourdomain.com) or a subdomain (e.g., music.yourdomain.com).
DNS Configuration: You need to configure the DNS records for your chosen domain/subdomain to point to the public IP address of your server where NPM is running.
- Create an A record (or AAAA for IPv6) for your chosen name (e.g., music.yourdomain.com) pointing to your server's public IP.
- If your home IP address is dynamic, you'll need a Dynamic DNS (DDNS) service (like DuckDNS, No-IP) to keep the DNS record updated. Many routers and some software can automate DDNS updates.
Port Forwarding: You must configure your router/firewall to forward incoming traffic on port 80 and port 443 from the internet to the internal IP address of the server running Docker and NPM. This allows Let's Encrypt to verify your domain ownership (via HTTP-01 challenge on port 80) and allows clients to connect via HTTPS (on port 443).

Steps within NPM Web UI (after logging in):

Go to Proxy Hosts: Navigate to "Hosts" -> "Proxy Hosts".
Add Proxy Host: Click the "Add Proxy Host" button.
Details Tab:
- Domain Names: Enter the domain name you configured DNS for (e.g., music.yourdomain.com). You can add multiple aliases if needed.
- Scheme: Select http (because NPM will talk to Airsonic internally over plain HTTP).
- Forward Hostname / IP: Enter the container name or Docker internal IP address of your Airsonic container. Using the container name (airsonic-advanced as defined in our Airsonic docker-compose.yml) is generally recommended as Docker's internal networking handles the IP resolution. Alternatively, find the container's IP using docker inspect airsonic-advanced.
- Forward Port: Enter the port Airsonic is listening on inside the Docker network, which is 4040.
- Cache Assets: You can leave this off initially.
- Block Common Exploits: Recommended to enable this.
- Websockets Support: Recommended to enable this, as some clients might use websockets.
SSL Tab:
- SSL Certificate: Select "Request a new SSL Certificate".
- Force SSL: Enable this. This automatically redirects any HTTP requests to HTTPS.
- HTTP/2 Support: Recommended to enable this for potential performance improvements.
- Email Address for Let's Encrypt: Enter your valid email address. Let's Encrypt uses this for expiry notifications.
- I Agree: Check the box to agree to the Let's Encrypt Terms of Service.
Save: Click the "Save" button.

NPM will now attempt to contact Let's Encrypt to obtain an SSL certificate for your domain. This involves Let's Encrypt trying to access a specific file served by NPM over HTTP (port 80) on your domain to verify you control it. This is why port forwarding for port 80 is essential.

Success: If successful, the status indicator next to your proxy host entry will turn green ("Online").
Failure: If it fails, common reasons include:
- Incorrect DNS configuration (DNS hasn't propagated yet, or points to the wrong IP).
- Port 80 not forwarded correctly to the NPM host.
- Firewall blocking port 80.
- Let's Encrypt rate limits (if you've requested certificates too many times recently). Check the NPM log file (docker compose logs nginx-proxy-manager) for detailed error messages.

Updating Airsonic Configuration (Optional but Recommended)

With the reverse proxy handling external access, you might consider:

Removing Port Mapping (Optional): In your Airsonic docker-compose.yml, you could potentially remove the ports: - "4040:4040" section. This prevents direct access to Airsonic via port 4040 from your local network, forcing all access (even local) through the reverse proxy (e.g., https://music.yourdomain.com). This can simplify firewall rules and ensures consistent use of HTTPS. However, it means NPM must be running for Airsonic to be accessible at all. For simplicity in this guide, we'll leave the port mapping, allowing both direct local access (http://<server-ip>:4040) and proxied access (https://music.yourdomain.com).
Context Path: If you configured a CONTEXT_PATH in Airsonic (e.g., /airsonic), ensure your clients use the correct URL (e.g., https://music.yourdomain.com/airsonic). The reverse proxy setup in NPM doesn't usually require changes for this, as it forwards the path requested by the client.

Workshop: Securing Airsonic with NPM and Let's Encrypt

Let's put theory into practice and secure our Airsonic instance.

Objective: Install Nginx Proxy Manager, configure it to reverse proxy Airsonic, obtain a Let's Encrypt SSL certificate, and access Airsonic securely via HTTPS using a domain name.

Prerequisites:

Airsonic-Advanced running via Docker Compose.
Docker and Docker Compose installed.
A registered domain name or subdomain.
Ability to configure DNS records for your domain.
Ability to configure port forwarding (Ports 80 & 443) on your router/firewall.

Steps:

Domain & DNS:
- Choose a subdomain (e.g., airsonic.yourdomain.com).
- Log in to your DNS provider's control panel.
- Create an A record for airsonic.yourdomain.com pointing to your public IP address. (Use a DDNS service if your IP is dynamic). Wait for DNS propagation (can take minutes to hours). You can check propagation using tools like dnschecker.org.
Port Forwarding:
- Log in to your router's administration interface.
- Find the "Port Forwarding" or "Virtual Server" section.
- Forward external port 80 (TCP) to internal port 80 on the internal IP address of the server running Docker.
- Forward external port 443 (TCP) to internal port 443 on the internal IP address of the server running Docker.
Install Nginx Proxy Manager:
- Follow the steps outlined in "Setting up Nginx Proxy Manager" above: create directories (/srv/npm/...), create the docker-compose.yml in ~/npm-docker, and run docker compose up -d.
Initial NPM Login:
- Access http://<your-server-ip>:81.
- Log in with admin@example.com / changeme.
- Change the default credentials as prompted.
Configure Proxy Host in NPM:
- Go to "Hosts" -> "Proxy Hosts" -> "Add Proxy Host".
- Details Tab:
  - Domain Names: airsonic.yourdomain.com (your chosen domain)
  - Scheme: http
  - Forward Hostname / IP: airsonic-advanced (the container name from Airsonic's docker-compose.yml)
  - Forward Port: 4040
  - Enable: Block Common Exploits, Websockets Support.
- SSL Tab:
  - SSL Certificate: "Request a new SSL Certificate"
  - Enable: Force SSL
  - Enable: HTTP/2 Support
  - Email Address: Your real email address.
  - Agree to Terms: Check the box.
- Click "Save".
Verify Certificate Acquisition: Wait a minute or two. The status icon for your host entry should turn green ("Online"). If not, troubleshoot using DNS/port forwarding checks and NPM logs (docker compose logs nginx-proxy-manager).
Test Secure Access:
- Open your browser and navigate to https://airsonic.yourdomain.com (using https and your domain).
- You should see the Airsonic-Advanced login page.
- Check the browser's address bar for a padlock icon, indicating a secure HTTPS connection. Click it to view the certificate details – it should be issued by Let's Encrypt for your domain.
Reconfigure a Client (e.g., DSub):
- Open DSub (or another client) on your mobile device.
- Go to the server settings for your Airsonic connection.
- Change the Server Address to your new secure URL: https://airsonic.yourdomain.com (no port needed, as HTTPS uses port 443 by default).
- Save the settings and test the connection.
- You should now be able to connect securely from anywhere using your domain name.

Congratulations! Your Airsonic-Advanced instance is now accessible securely over the internet using HTTPS, thanks to Nginx Proxy Manager and Let's Encrypt. This is a crucial step for protecting your credentials and privacy when accessing your music remotely.

8. Advanced Configuration and Customization

Beyond the basic setup and UI settings, Airsonic-Advanced offers deeper configuration options primarily through environment variables (when using Docker) or a properties file. This allows fine-tuning performance, enabling specific features like transcoding, integrating with external services, and customizing behavior.

Exploring `airsonic.properties` (or Environment Variables)

Airsonic-Advanced uses a set of configuration properties to control its behavior. When running natively (not in Docker), these are typically managed in a file named airsonic.properties located in the Airsonic data directory. However, when running with the official Docker image, the preferred method is to set these properties using environment variables in your docker-compose.yml file.

The Docker image often translates environment variables into the appropriate Java system properties or configuration file entries when the container starts. The naming convention usually involves taking the property name (e.g., airsonic.contextPath), converting it to uppercase, replacing dots (.) with underscores (_), and prefixing it with AS_ or similar (though common ones like CONTEXT_PATH, JAVA_OPTS, PUID, PGID, TZ are often handled directly without a prefix). Always consult the documentation for the specific Docker image you are using (airsonicadvanced/airsonic-advanced on Docker Hub) for the exact environment variables it supports.

Common Configuration Areas & Examples (using environment variable format):

Memory Allocation (JAVA_OPTS): Controls the memory available to the Java Virtual Machine (JVM). The most common option is -Xmx for maximum heap size.
```
environment:
  - JAVA_OPTS=-Xmx2048m # Allocate 2GB max heap size
```
Explanation: Insufficient memory can cause instability or slow performance, especially with large libraries or heavy transcoding. Increase this if needed, but don't allocate more RAM than your server reasonably has available.
Context Path (CONTEXT_PATH): Sets the base URL path for Airsonic.
```
environment:
  - CONTEXT_PATH=/musicstream # Access via http://host:4040/musicstream
```
Explanation: Useful when running multiple applications behind a single reverse proxy domain, differentiating them by path. Ensure your reverse proxy configuration forwards requests to this path correctly if set.
Database Configuration: By default, Airsonic uses an embedded HSQLDB database stored in /config/db. For better performance and scalability, especially with very large libraries, you can configure it to use an external database like PostgreSQL. This involves setting multiple environment variables:
```
environment:
  # Example for PostgreSQL (requires a separate running PostgreSQL server/container)
  - AS_DATABASE_URL=jdbc:postgresql://<postgres_host>:<postgres_port>/<database_name>
  - AS_DATABASE_USERNAME=<db_user>
  - AS_DATABASE_PASSWORD=<db_password>
  # - AS_JDBC_DRIVER_CLASS=org.postgresql.Driver # Often detected automatically
```
Explanation: Configuring an external database is an advanced topic requiring separate database setup and management. HSQLDB is sufficient for most personal use cases.
LDAP Integration: For environments with existing LDAP or Active Directory infrastructure, Airsonic can be configured to authenticate users against it. This involves setting AS_LDAP_... variables (e.g., AS_LDAP_URL, AS_LDAP_SEARCH_FILTER, AS_LDAP_MANAGER_DN, AS_LDAP_MANAGER_PASSWORD). Refer to Airsonic documentation for details.
Transcoding Settings (Covered Next): Specific environment variables can control default transcoding behavior or paths to external transcoder binaries if needed.
Other Settings: Many other fine-grained settings exist (e.g., controlling character encoding, default locales, specific feature flags). Explore the Airsonic-Advanced documentation or the airsonic.properties.template file often found within the source code or container for a more complete list.

When changing environment variables in docker-compose.yml, you need to recreate the container for them to take effect:

cd ~/airsonic-docker # Or wherever your compose file is
docker compose down # Stop and remove the container (keeps volumes)
docker compose up -d # Recreate and start with new environment variables

Transcoding Settings

Transcoding is the process of converting audio (or video) from one format or bitrate to another, usually done on-the-fly as the media is streamed.

Why Use Transcoding?

Bandwidth Saving: Converting a high-bitrate lossless file (like FLAC) to a lower-bitrate lossy format (like MP3 or Opus) significantly reduces the amount of data transferred, crucial for streaming over mobile networks or slow connections.
Client Compatibility: Some clients or devices might not support certain audio formats (e.g., a basic Bluetooth speaker might only handle MP3 or AAC). Transcoding can convert unsupported formats to compatible ones.
Reducing CPU Load on Client: While the server does the heavy lifting, playing a simpler format might consume less battery/CPU on the client device.

How Airsonic Handles Transcoding:

Transcoders: Airsonic needs external command-line tools (transcoders) to perform the conversions. The most common and versatile tool is ffmpeg, which supports a vast range of formats and codecs. The official Docker image typically includes ffmpeg. Airsonic can be configured with multiple transcoding steps, each defining a command to execute.
Players: In Airsonic's settings ("Settings" -> "Players"), you define different "Players". A player isn't necessarily a physical device but rather a profile that clients can identify as. Each player profile specifies which formats it can play natively and which transcoding step (if any) should be used for specific original formats or when down-sampling is requested.
Client Request: When a client requests a stream, it can specify a maximum bitrate or a specific player profile.
Server Decision: Airsonic checks the requested track's format and the client's request (max bitrate, player profile).
- If the format is natively supported by the player profile and no down-sampling is needed, the original file is streamed (passthrough).
- If the format is not supported or a lower bitrate is requested, Airsonic selects the appropriate transcoding step associated with the player profile. It executes the defined command (e.g., using ffmpeg), feeding it the original audio data and piping the transcoded output stream back to the client.

Configuring Transcoding:

Location: "Settings" -> "Transcoding" in the web UI.
Transcoding Steps: You'll see a list of pre-defined transcoding steps (e.g., "MP3 - 320 kbps", "Opus - 96 kbps"). Each step has:
- Name: A descriptive name.
- Source Format(s): The original audio formats this step applies to (e.g., flac, wav, alac).
- Target Format: The format to convert to (e.g., mp3, opus).
- Default: Whether this is a default fallback transcoding.
- Step: The actual command-line instruction. This often uses placeholders like %s (source file path) and requires knowledge of ffmpeg (or other transcoder) command-line syntax. Example for converting to 128kbps MP3 using ffmpeg:
```
ffmpeg -i %s -map 0:a:0 -b:a 128k -ar 44100 -ac 2 -f mp3 -
```
  Explanation: -i %s: input file. -map 0:a:0: select the first audio stream. -b:a 128k: set audio bitrate to 128 kbps. -ar 44100: set audio sample rate to 44.1 kHz. -ac 2: set audio channels to stereo. -f mp3: output format is MP3. -: output to standard output (stdout), which Airsonic reads.
Assigning to Players: Go to "Settings" -> "Players". Select a player profile (e.g., the default "Web interface" or profiles used by mobile apps like DSub). For various original formats, you can choose "Passthrough" (no transcoding) or select one of the configured transcoding steps from the dropdown. You can also set a default transcoding for when the client requests a bitrate lower than the original.

CPU Considerations: Transcoding, especially from lossless formats, is CPU-intensive. A low-power server (like a Raspberry Pi) might struggle with multiple simultaneous transcodes. Monitor your server's CPU usage while transcoding is active. If performance suffers, consider pre-transcoding versions of your library or using less CPU-intensive codecs/settings (Opus is often more efficient than MP3 at lower bitrates).

Customizing the Look and Feel

Airsonic-Advanced offers some basic customization options for its web interface:

Themes: Go to "Settings" -> "Personal". Users can select from available themes (e.g., light, dark, and potentially others). The administrator might be able to install custom themes, though this usually involves modifying files within the container or host volume, which can be complex and may not survive updates easily. Sticking to built-in themes is generally recommended.

Workshop: Setting Up a Low-Bandwidth Transcoding Step

Let's configure Airsonic to transcode high-quality FLAC files to a lower-bitrate Opus format, suitable for mobile streaming, and assign this transcoding to a specific player profile used by a mobile client.

Objective: Create a new transcoding step for Opus audio, assign it to the player profile used by DSub (or another mobile client), and verify that FLAC files are transcoded when streamed via that client.

Prerequisites:

Airsonic-Advanced running, admin access.
ffmpeg available within the Airsonic container (the official image includes it).
A mobile client (like DSub) connected.
Some FLAC files in your Airsonic library.
Ability to monitor server CPU usage (e.g., using htop or docker stats).

Steps:

Log in as Admin: Access the Airsonic web UI.
Navigate to Transcoding Settings: Go to "Settings" -> "Transcoding".
Create New Transcoding Step: Scroll down to the "Add new transcoding" section.
- Name: Opus - 96 kbps (Mobile)
- Source format(s): flac wav alac ape (List formats you want this to apply to, space-separated)
- Target format: opus
- Step: Paste the following ffmpeg command:
```
ffmpeg -i %s -map 0:a:0 -b:a 96k -ac 2 -f opus -content_type application/ogg -
```
  Explanation: Similar to the MP3 example, but -b:a 96k sets a 96kbps Opus bitrate, -f opus specifies Opus output, and -content_type application/ogg helps clients recognize the stream correctly (Opus is often encapsulated in Ogg containers).
- Click "Save". Your new transcoding step should appear in the list.
Identify Mobile Client Player: Go to "Settings" -> "Players". Look at the list of active players. When you connect with a mobile client like DSub or Ultrasonic, Airsonic usually creates a player entry for it automatically, often named after the app (e.g., "DSub", "ultrasonic"). Note the exact name. If it's not there, connect with your mobile app, play a track briefly, and refresh the Players page.
Configure the Mobile Player:
- Click the pencil icon (Edit) next to the player entry corresponding to your mobile app (e.g., "DSub").
- Scroll down to the "Transcodings" section.
- Find the rows for the source formats you specified earlier (FLAC, WAV, ALAC, APE).
- In the dropdown menu for each of these formats, select the transcoding step you just created: "Opus - 96 kbps (Mobile)".
- Crucially: Scroll down to the "Default Max Bitrate" setting for this player. Many clients won't automatically trigger transcoding unless a max bitrate is set or requested. Set a value here, for instance, 128 (kbps). This tells Airsonic that if the original bitrate is higher than 128, it should look for a suitable transcoding. Alternatively, configure the max bitrate within the client app's settings if it allows (DSub has settings for Wi-Fi/Mobile max bitrates). Setting it in Airsonic's player profile is often more reliable.
- Click "Save" at the bottom of the player configuration page.
Monitor CPU Usage: Open a terminal to your server and run htop or docker stats airsonic-advanced to watch CPU usage.
Test Streaming:
- On your mobile device using the configured client (DSub), find a FLAC file in your library.
- Start playing the FLAC file.
- Observe the CPU usage on your server. You should see a noticeable increase in CPU usage for the ffmpeg process (which runs under the Airsonic container) while the track is playing and potentially buffering. This indicates transcoding is active. CPU usage should drop when playback stops or if you play an MP3 file (which likely won't be transcoded based on our rules).
Verify (Optional - Client Dependent): Some clients might display information about the currently playing stream, potentially showing the codec (Opus) or bitrate (around 96kbps), confirming the transcode. DSub sometimes shows this in the notification or player screen details.

You have successfully configured a custom transcoding setting to optimize streaming for low-bandwidth situations. This demonstrates the power of Airsonic's transcoding engine in adapting your library to different playback scenarios, albeit at the cost of server CPU resources.

9. Backup, Restore, and Updates

A crucial aspect of self-hosting any service, especially one holding personal data like your configured music library interface, is implementing reliable backup, restore, and update procedures. This ensures data safety and keeps your service running smoothly and securely.

Importance of Backups

Data loss can happen due to various reasons: hardware failure (disk crash), software bugs, accidental deletion, filesystem corruption, or security incidents. Without backups, recovering your Airsonic setup – including user accounts, playlists, listening history, ratings, and settings – can be impossible or incredibly time-consuming.

Configuration Data: This includes the database (user accounts, playlists, metadata cache, ratings, etc.), settings, cover art cache, and any custom configurations. Losing this means setting up Airsonic from scratch and losing all user-specific data.
Media Files: While Airsonic uses your media files, it doesn't typically store them within its primary configuration volume (unless you specifically configured it that way, which is not standard). Your music files (/srv/airsonic-advanced/music, etc.) need their own backup strategy, as they represent your actual library. Losing these is often catastrophic.
Docker Configuration: The docker-compose.yml file contains the definition of your service, including volume mappings, environment variables, and port settings. Backing this up makes it easy to redeploy Airsonic after a system failure or migration.

Backup Strategy

A good backup strategy identifies what needs to be backed up, how often, and where the backups are stored.

Key Components to Back Up:

Airsonic Configuration Volume: This is the most critical part for restoring the service itself. In our setup, this is the host directory mapped to /config inside the container: /srv/airsonic-advanced/config. This directory contains:
- db/ subdirectory: Holds the HSQLDB database files (if using the default).
- airsonic.properties (or equivalent settings managed internally).
- cache/ subdirectory: Contains cover art and potentially transcoded file caches (less critical to back up, can be regenerated, but backing it up speeds restore).
- playlists/ (if stored internally, though our example maps a separate volume).
- Log files (airsonic.log, etc. - optional to back up).
- Other configuration files and internal data.
Docker Compose File: Your ~/airsonic-docker/docker-compose.yml file.
Media Files: Your music, podcast, and playlist directories (/srv/airsonic-advanced/music, /srv/airsonic-advanced/podcasts, /srv/airsonic-advanced/playlists). These are often very large and require a separate consideration.

Backup Frequency:

Airsonic Configuration & Docker Compose: Backup frequently, especially after making changes (adding users, creating playlists, changing settings). Daily or weekly backups are common.
Media Files: Depends on how often you add new music. If you add music infrequently, backing up after each addition might suffice. If you add music constantly, a weekly or monthly schedule might be more practical, potentially combined with incremental backups.

Backup Storage:

Follow the 3-2-1 Rule:
- 3 Copies: Keep at least three copies of your important data.
- 2 Media: Store the copies on at least two different storage media types (e.g., internal drive + external USB drive, or internal drive + network storage).
- 1 Offsite: Keep at least one copy offsite (e.g., cloud storage, a drive stored at a different physical location). This protects against local disasters like fire or theft.

Backup Methods

rsync (Recommended for Config/Compose): A powerful and versatile command-line utility for synchronizing files and directories. It's efficient because it only transfers changed files. Ideal for backing up the configuration volume and compose file to another location (external drive, network share, another server).

Example rsync command to back up Airsonic config:
```
# Ensure Airsonic container is stopped for database consistency (especially HSQLDB)
cd ~/airsonic-docker
docker compose stop airsonic # Or docker compose down

# Backup command (replace /path/to/backups with your actual backup destination)
sudo rsync -avh --delete /srv/airsonic-advanced/config/ /path/to/backups/airsonic-config-backup/

# Backup the docker-compose file
rsync -avh ~/airsonic-docker/docker-compose.yml /path/to/backups/airsonic-docker-compose.backup.yml

# Restart Airsonic container
docker compose start airsonic # Or docker compose up -d
```
Explanation:
- rsync: The command itself.
- -a: Archive mode (preserves permissions, ownership, timestamps, symbolic links, recurses into directories).
- -v: Verbose (shows files being transferred).
- -h: Human-readable output for file sizes.
- --delete: Deletes files in the destination directory that no longer exist in the source directory. Use with caution to ensure the destination is only used for this backup. This keeps the backup a mirror of the source.
- /srv/airsonic-advanced/config/: The source directory. The trailing slash / is important! It means "copy the contents of this directory". Without it, rsync would copy the config directory itself into the destination.
- /path/to/backups/airsonic-config-backup/: The destination directory. Must exist.
- Stopping the container (docker compose stop airsonic) before backing up the /config volume, especially the db subdirectory, is highly recommended to ensure database consistency, particularly for file-based databases like HSQLDB. Restart it afterwards.
Dedicated Backup Software: Tools like BorgBackup (deduplication, encryption), Restic, Duplicati (web UI), or even simple scheduled scripts using rsync and cron.
Snapshots: If using filesystems like ZFS or Btrfs, filesystem snapshots can provide point-in-time, near-instantaneous backups of the configuration volume. However, these are usually local and should be combined with backups to other media/locations.
Media File Backup (rclone, Syncthing, etc.):
- rclone: Excellent tool for syncing large amounts of data to various cloud storage providers (Google Drive, Dropbox, Backblaze B2, etc.) or other local/network locations. Supports encryption.
- Syncthing: Continuous file synchronization tool for keeping folders in sync between multiple devices (e.g., sync your music folder to a NAS or another computer). Not strictly a backup tool (deletions sync too), but useful for redundancy.
- Manual Copy / External Drives: Simple, effective for periodic backups.

Restoring from Backup

The restore process generally involves reversing the backup steps:

Stop Airsonic Container:

cd ~/airsonic-docker
docker compose down # Use down to ensure container is removed before potentially restoring different version configs

Restore Airsonic Configuration: Use rsync (or your chosen method) to copy the backed-up configuration data back to the original host volume location.
```
# Example using rsync (ensure source/destination are correct!)
sudo rsync -avh --delete /path/to/backups/airsonic-config-backup/ /srv/airsonic-advanced/config/
```
Explanation: Copying the contents of the backup back into the active config directory.
Restore docker-compose.yml (If Needed): Copy the backed-up docker-compose.yml back to ~/airsonic-docker/docker-compose.yml.
Restore Media Files (If Needed): Restore your music files to /srv/airsonic-advanced/music/ (and other media directories) using the method you chose for backing them up. This might take a long time depending on library size.
Verify Ownership/Permissions: After restoring files (especially config), double-check that the ownership and permissions on /srv/airsonic-advanced/config and /srv/airsonic-advanced/music (etc.) match the PUID/PGID specified in your docker-compose.yml. You might need to run sudo chown -R PUID:PGID /srv/airsonic-advanced/* again.
Restart Airsonic Container:
```
cd ~/airsonic-docker
docker compose up -d
```
Check logs (docker compose logs -f airsonic) for any errors during startup. Access the web UI and verify that users, settings, playlists, and library counts look correct.

Updating Airsonic-Advanced (Docker)

Updating Airsonic-Advanced when using the Docker Compose method is generally straightforward:

Check for Breaking Changes: Before updating, it's wise to check the Airsonic-Advanced release notes or GitHub page for the new version you are pulling. Look for any specific instructions or potential breaking changes that might require manual intervention or configuration adjustments.
Pull Latest Image: Navigate to your Docker Compose directory and pull the latest image specified in your docker-compose.yml (or a specific newer version tag if you pinned it).
```
cd ~/airsonic-docker
docker compose pull airsonic
```
Explanation: pull downloads the latest version of the image(s) for the specified service (airsonic) from the Docker registry.
Recreate Container: Stop the current container and restart it using the newly pulled image. Docker Compose automatically detects the new image and uses it.
```
docker compose up -d --remove-orphans
```
Explanation: up -d starts the service in detached mode. If the image has changed, Compose will stop the old container and start a new one based on the new image, automatically connecting it to the existing volumes. --remove-orphans removes any containers for services that might have been removed from the compose file, keeping things tidy. Alternatively, docker compose down && docker compose up -d achieves a similar result.
Verify: Access the Airsonic web UI. Check the version information (often in the "About" section or settings) to confirm the update was successful. Test basic functionality.

Workshop: Performing a Backup and Simulated Restore

Let's practice backing up the essential Airsonic configuration and simulating a minor data loss scenario to test the restore process.

Objective: Back up the Airsonic configuration volume, simulate data loss by deleting a file, restore from the backup, and verify Airsonic's state. Also, practice the update process.

Prerequisites:

Airsonic-Advanced running via Docker Compose (~/airsonic-docker/docker-compose.yml, /srv/airsonic-advanced/config).
A location to store the backup (e.g., ~/airsonic_backup).

Steps:

Create Backup Directory:
```
mkdir ~/airsonic_backup
```

Stop Airsonic Container:

cd ~/airsonic-docker
docker compose stop airsonic

Perform Backup: Use rsync to back up the configuration volume and the compose file.

sudo rsync -avh --delete /srv/airsonic-advanced/config/ ~/airsonic_backup/config-backup/
rsync -avh ~/airsonic-docker/docker-compose.yml ~/airsonic_backup/docker-compose.backup.yml

Check the contents of ~/airsonic_backup/config-backup/ to ensure files were copied.

Simulate Data Loss: Let's delete a non-critical file from the live configuration directory. The log file is a safe choice.

sudo rm /srv/airsonic-advanced/config/airsonic.log
# Verify it's gone (ls command should show no such file)
sudo ls /srv/airsonic-advanced/config/airsonic.log

Perform Restore: Use rsync to copy the contents of the backup back to the live configuration directory.
```
sudo rsync -avh --delete ~/airsonic_backup/config-backup/ /srv/airsonic-advanced/config/
```
Verify Restore: Check if the deleted file has been restored.
```
sudo ls -l /srv/airsonic-advanced/config/airsonic.log
```
The file should now exist again.
Restart Airsonic:
```
cd ~/airsonic-docker
docker compose start airsonic
```
Access the web UI and ensure everything loads correctly.

Perform Update Simulation: Let's simulate updating Airsonic (even if we pull the same version, the process is the same).

cd ~/airsonic-docker
docker compose pull airsonic # Pull the latest (or specified) image
docker compose up -d --remove-orphans # Recreate the container with the pulled image

Check Update: Access Airsonic again. Check the "About" page or settings for the version number (though it might not have changed if latest was already up-to-date). The key is practicing the pull and up workflow.

You have now successfully practiced backing up your Airsonic configuration, restoring it after simulated data loss, and performing the standard update procedure using Docker Compose. Regularly performing backups and knowing how to restore them is essential for peace of mind when self-hosting.

Conclusion

Throughout this guide, we have journeyed from the fundamental concepts of Airsonic-Advanced to deploying, configuring, securing, and maintaining your own personal music streaming server. By following the structured progression through Basic, Intermediate, and Advanced topics, complemented by hands-on Workshops, you should now possess a solid understanding and a functional instance of Airsonic-Advanced.

We began by understanding the purpose and features of Airsonic-Advanced and preparing a Linux system with the necessary prerequisites. Leveraging the power and convenience of Docker and Docker Compose, we achieved a clean, isolated, and reproducible installation. Initial configuration involved setting up the administrator account, crucially pointing Airsonic to your music library via volume mappings, and understanding the importance of the media scanning process.

Moving to the intermediate level, we emphasized the significance of user management for secure multi-user access, configuring granular permissions tailored to different needs. We delved into the critical role of accurate metadata (tags) and cover art for a rich browsing experience, utilizing external tools like MusicBrainz Picard for effective library management. Connecting various desktop and mobile clients using the Subsonic API unlocked the true potential of accessing your music from anywhere within your network.

In the advanced sections, we addressed the vital task of securing your server for remote access using HTTPS. By implementing Nginx Proxy Manager as a reverse proxy, we automated SSL certificate acquisition and renewal via Let's Encrypt, ensuring encrypted communication. We explored advanced configuration possibilities through environment variables, focusing on performance tuning (memory allocation) and feature enablement, particularly the CPU-intensive but valuable transcoding capability for optimizing streams across different bandwidths and devices. Finally, we established robust procedures for backup, restore, and updates – essential practices for the long-term health and safety of any self-hosted service.

Self-hosting Airsonic-Advanced empowers you to take full control of your music library, freeing you from the limitations and privacy concerns of commercial streaming platforms. You now have a personalized, secure, and feature-rich music server accessible from your preferred devices.

This guide provides a strong foundation, but the journey of self-hosting is one of continuous learning. Don't hesitate to explore further: delve deeper into ffmpeg transcoding options, experiment with different client applications, investigate integrating with other services, or even contribute to the Airsonic-Advanced open-source project. The community forums and documentation are valuable resources for troubleshooting and discovering new possibilities. Enjoy the freedom and satisfaction of streaming your music, your way.

Music Streaming Server Airsonic-Advanced

Introduction

1. Getting Started with Airsonic-Advanced

Understanding Airsonic-Advanced

Workshop: Preparing Your System

2. Basic Installation using Docker

Why Docker?

Installing Docker and Docker Compose

Running Airsonic-Advanced with Docker Compose

Workshop: Your First Airsonic-Advanced Instance

3. Initial Configuration and Adding Music

First Login and Setup Wizard

Configuring Media Folders

Understanding the Scanning Process

Workshop: Adding Your First Album

4. User Management and Access Control

Creating and Managing Users

Fine-tuning Permissions

Workshop: Setting Up a Family Account

5. Enhancing Your Library with Metadata and Cover Art

The Importance of Good Metadata (Tags)

Using External Tools for Tagging

Airsonic's Metadata Handling

Workshop: Cleaning Up Album Metadata

6. Connecting Clients and Mobile Apps

Understanding the Subsonic API

Recommended Desktop and Mobile Clients

Configuring Client Connections

Workshop: Connecting DSub (Android)

7. Securing Your Airsonic-Advanced Instance with HTTPS

Why HTTPS is Essential

Using a Reverse Proxy (Nginx Proxy Manager)

Setting up Nginx Proxy Manager

Configuring NPM for Airsonic

Updating Airsonic Configuration (Optional but Recommended)

Workshop: Securing Airsonic with NPM and Let's Encrypt

8. Advanced Configuration and Customization

Exploring airsonic.properties (or Environment Variables)

Transcoding Settings

Customizing the Look and Feel

Workshop: Setting Up a Low-Bandwidth Transcoding Step

9. Backup, Restore, and Updates

Importance of Backups

Backup Strategy

Backup Methods

Restoring from Backup

Updating Airsonic-Advanced (Docker)

Workshop: Performing a Backup and Simulated Restore

Conclusion

Exploring `airsonic.properties` (or Environment Variables)