Docker — Microgamma Docs

Microgamma ships as a public, multi-architecture Docker image on GitHub Container Registry, so you can run it headless in a container on any host. Inside the container, prefix any CLI command with mg; running with no command launches the app headless.

Keep your configuration in a named volume so it survives restarts, and mount your music library at /music.

1. Pull the image

Pull the plain :latest tag and Docker automatically selects the right build for your architecture (Intel or Apple Silicon / ARM):

docker pull ghcr.io/microgamma/microgamma-desktop:latest

Pin a specific version with a versioned tag instead:

docker pull ghcr.io/microgamma/microgamma-desktop:v2.94.3

Per-architecture tags (latest-x64, latest-arm64, v2.94.3-x64, …) also exist if you need to pin a specific build, but the plain tag is what most people want.

2. First-run setup

Run the interactive wizard once — device name, music location, login, and scan. It needs an interactive terminal, so pass -it:

docker run -it --rm \
  -v mg-config:/home/node/.microgamma \
  -v /path/to/music:/music \
  ghcr.io/microgamma/microgamma-desktop:latest \
  mg setup

3. Run headless

Start the app in the background, reusing the mg-config volume from setup:

docker run -d \
  --name microgamma \
  -v mg-config:/home/node/.microgamma \
  -v /path/to/music:/music \
  ghcr.io/microgamma/microgamma-desktop:latest

Running other commands

You can run any mg command the same way. For example, to rebuild the library index:

docker run --rm \
  -v mg-config:/home/node/.microgamma \
  -v /path/to/music:/music \
  ghcr.io/microgamma/microgamma-desktop:latest \
  mg scan --reset

Ports

The image doesn't publish any ports, and it usually doesn't need to — remote access through play.microgamma.io is brokered by Microgamma's signaling service. If you want to reach the song server directly on your LAN, publish port 3333 yourself (-p 3333:3333).