How to Deploy Music Assistant Server in a Docker Environment: Complete Guide

Music Assistant Server deploys via a multi-stage Docker build that separates FFmpeg compilation from the Python runtime, resulting in a production-ready image exposed on port 8095 with persistent /data storage.

Music Assistant Server is an open-source media library manager packaged for containerized deployment in the music-assistant/server repository. The architecture uses a sophisticated build pipeline to pre-compile heavy dependencies and optimize startup performance. This guide explains how to deploy Music Assistant server in a Docker environment using both pre-built registry images and custom source builds.

Understanding the Multi-Stage Docker Architecture

The deployment pipeline relies on three distinct stages defined across Dockerfile.base and Dockerfile to minimize runtime overhead and ensure deterministic, reproducible builds.

The Base Image (Dockerfile.base)

The foundation is built from Dockerfile.base, which compiles FFmpeg 7.1.2 with extensive audio codec support and bundles a matching PyAV wheel. This image is published to ghcr.io/music-assistant/base and serves as a dependency-rich foundation for subsequent stages. It isolates heavy compilation steps from the final runtime environment and is not intended to be run directly.

The Builder Stage

The builder stage starts from the base image and creates a Python virtual environment using UV for fast package resolution. According to the source in Dockerfile (lines 3-55), it installs all runtime dependencies from requirements_all.txt—including heavy packages like PyTorch—and pre-compiles Python bytecode to reduce container startup latency. The music-assistant wheel is installed into this prepared environment during this phase.

The Final Runtime Image

The final stage copies the prepared /app directory from the builder, configures the PATH to point to the virtual environment, and sets up a jemalloc-enabled entrypoint script for optimal memory management. As implemented in Dockerfile (lines 55-102), this image exposes port 8095 and declares a persistent volume at /data for the SQLite database and cache storage.

Deploying Music Assistant Server with Docker

You can deploy using the pre-built image from the GitHub Container Registry or build locally from the music-assistant/server source.

Running the Pre-Built Image

The fastest deployment method pulls ghcr.io/music-assistant/server:latest and maps the required ports and volumes:

docker run -d \
  --name music-assistant \
  -p 8095:8095 \
  -v /path/to/local/data:/data \
  --restart unless-stopped \
  ghcr.io/music-assistant/server:latest \
  --data-dir /data \
  --cache-dir /data/.cache

This command maps port 8095 for the HTTP API, mounts a local directory for persistent storage, and passes configuration arguments to specify database and cache locations.

Docker Compose Configuration

For long-term deployments, use a docker-compose.yml file:

version: "3.9"
services:
  music-assistant:
    image: ghcr.io/music-assistant/server:latest
    container_name: music-assistant
    ports:
      - "8095:8095"
    volumes:
      - ./data:/data
    restart: unless-stopped
    command: ["--data-dir", "/data", "--cache-dir", "/data/.cache"]

Deploy with docker compose up -d to manage the container lifecycle.

Building Locally from Source

To build the base image locally (optional, as CI publishes pre-built versions):

docker build -f Dockerfile.base -t ghcr.io/music-assistant/base:latest .

Then build the server image with specific version arguments:

docker build \
  --build-arg BASE_IMAGE_VERSION=latest \
  --build-arg MASS_VERSION=$(git describe --tags --abbrev=0) \
  -t music-assistant/server:<VERSION> .

Configuration and Volume Management

Proper volume configuration ensures data persistence across container restarts and updates.

Persistent Storage with /data Volume

The container requires a mounted volume at /data to store the Music Assistant database and cache. Without this volume, data resets when the container stops. The entrypoint script processes --data-dir and --cache-dir arguments to organize SQLite files and temporary cache within this persistent location.

Port Mapping and Network Access

Port 8095 must be exposed to access the web interface and HTTP API. When running on Raspberry Pi, NAS, or Intel NUC hosts, ensure this port is available and not blocked by firewall rules.

Summary

• Music Assistant Server uses a three-stage Docker build: base (FFmpeg), builder (Python deps), and final (runtime).
• The base image at ghcr.io/music-assistant/base contains custom-compiled FFmpeg 7.1.2 and PyAV wheels defined in Dockerfile.base.
• Production deployments use ghcr.io/music-assistant/server with port 8095 exposed and a /data volume mounted.
• The builder stage uses UV to install dependencies from requirements_all.txt and pre-compiles bytecode for faster startup.
• Runtime configuration uses --data-dir and --cache-dir arguments to manage persistent storage locations.

Frequently Asked Questions

What is the difference between the base image and the server image?

The base image (ghcr.io/music-assistant/base) is an intermediate build artifact containing FFmpeg and system libraries defined in Dockerfile.base, not intended for direct execution. The server image (ghcr.io/music-assistant/server) is the final runtime container that includes the Python application, virtual environment, and entrypoint script.

Why does the container use jemalloc?

The entrypoint script enables jemalloc for memory management optimization, which reduces memory fragmentation during long-running audio processing tasks typical in media server applications.

Can I run Music Assistant Server on a Raspberry Pi?

Yes, the multi-architecture Docker images support ARM64 and AMD64 platforms, making them compatible with Raspberry Pi, NAS devices, Intel NUCs, and standard Linux servers without architecture-specific modifications.

Where are the database and cache files stored?

By default, the container expects a volume mounted at /data, which stores the SQLite database and cache files. Use the --data-dir and --cache-dir command arguments to customize these paths within the container's filesystem, ensuring these locations point to your persistent volume mount.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}