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

> Deploy the Music Assistant server in Docker with this comprehensive guide. Learn to build a production-ready image for efficient music management and streaming.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: how-to-guide
- Published: 2026-06-15

---

**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`](https://github.com/music-assistant/server/blob/main/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:

```bash
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`](https://github.com/music-assistant/server/blob/main/docker-compose.yml) file:

```yaml
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):

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

```

Then build the server image with specific version arguments:

```bash
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`](https://github.com/music-assistant/server/blob/main/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.