airsonic-pulse/docs/docker/README.md

Docker

Airsonic-Pulse is available as a multi-architecture Docker image from the GitHub Container Registry.

Image

ghcr.io/airsonic-pulse/airsonic-pulse

Supported architectures: linux/amd64, linux/arm64

Quick Start

docker run -d \
  --name airsonic-pulse \
  -p 4040:4040 \
  -v ./data/airsonic:/var/airsonic \
  -v ./data/music:/var/music \
  -v ./data/playlists:/var/playlists \
  -v ./data/podcasts:/var/podcasts \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  ghcr.io/airsonic-pulse/airsonic-pulse:latest

Then open http://localhost:4040 in your browser.

Environment Variables

Variable	Default	Description
PUID	0	User ID for the application process
PGID	0	Group ID for the application process
TZ	Etc/UTC	Container timezone
AIRSONIC_PORT	4040	HTTP listen port inside the container
CONTEXT_PATH	/	Servlet context path
UPNP_PORT	4041	DLNA/UPnP port
JAVA_OPTS	(empty)	Additional JVM options (appended to defaults)

The default heap is -Xmx1024m -Xms512m. Override via JAVA_OPTS if needed:

-e JAVA_OPTS="-Xmx2048m -Xms1024m"

Volumes

Container Path	Description
/var/airsonic	Application data, config, database, logs
/var/music	Default music library
/var/playlists	Default playlists folder
/var/podcasts	Default podcasts folder

These are the same paths used by the standalone WAR deployment, making it straightforward to switch between Docker and non-Docker installations.

User Permissions

By default the container runs as root (UID 0, GID 0). The entrypoint creates a user with the specified PUID/PGID, sets ownership of the data directories, and drops privileges before starting the application.

You can set the user in two ways:

• PUID / PGID environment variables (recommended): The entrypoint handles user creation and ownership.
• --user uid:gid flag: Bypasses the entrypoint's user management. You must ensure the volumes are pre-owned by the specified UID/GID.

Docker Compose

Compose files are provided in install/compose/ for three database configurations:

HSQLDB (embedded, default):

cd install/compose
docker compose -f docker-compose.hsqldb.yaml up -d

PostgreSQL:

cd install/compose
docker compose -f docker-compose.postgres.yaml up -d

MariaDB:

cd install/compose
docker compose -f docker-compose.mariadb.yaml up -d

External Database

To connect to an external database, set the Spring datasource properties via environment variables. Use lowercase with underscores — Spring Boot's relaxed binding maps them to the corresponding properties:

PostgreSQL:

-e spring_datasource_url="jdbc:postgresql://dbhost:5432/airsonic?stringtype=unspecified"
-e spring_datasource_username="airsonic"
-e spring_datasource_password="secret"

MariaDB:

-e spring_datasource_url="jdbc:mariadb://dbhost:3306/airsonic"
-e spring_datasource_username="airsonic"
-e spring_datasource_password="secret"

The JDBC driver is auto-detected from the URL — there is no need to set spring.datasource.driver-class-name.

Ports

Port	Protocol	Description
4040	TCP	HTTP web interface and API
4041	TCP	DLNA/UPnP (optional)
1900	UDP	DLNA/UPnP discovery (optional)

Health Check

The image includes a built-in health check that polls the /rest/ping endpoint every 15 seconds.

Building the Image Locally

# Build the WAR first
mvn clean package -pl airsonic-main -am -DskipTests -q

# Prepare build context
mkdir -p install/docker/target/dependency
cp airsonic-main/target/airsonic.war install/docker/target/dependency/airsonic-main.war

# Build
cd install/docker
docker build -t airsonic-pulse:local .

Transcoding

The Docker image includes ffmpeg and lame pre-installed. Symlinks are created automatically in /var/airsonic/transcode/ at container startup.