Docker Setup

Docker Setup

Run Music Hub as a headless server on Docker. The Docker server is available for NAS, Linux server, seedbox, and Docker Desktop setups.

Testing note: Docker support is available now, but still treated as a testing channel while NAS, Linux server, seedbox, Docker Desktop, pairing, remote access, and mobile playback paths get wider coverage. If anything behaves unexpectedly, join the community and report it so we can fix it quickly: Telegram (opens in a new tab) or WhatsApp (opens in a new tab).

What Docker Runs

Docker runs the Music Hub server and web UI. It does not run the Electron desktop app, and it cannot act as a desktop client of another hub.

Use Docker when you want one always-on hub that owns the library database, scans music folders, serves the browser UI, and pairs mobile apps.

1. Create docker-compose.yml

Download the current compose file:

mkdir -p music-hub
cd music-hub
curl -O https://music-hub.gordo.design/docker-compose.yml

Or create it manually:

services:
  music-hub:
    image: ghcr.io/gordo-labs/music-hub/server:latest
    container_name: music-hub
    ports:
      - "38472:38472"
    volumes:
      - ./data:/data
      # Change this to your real music folder.
      # Then use /music inside Music Hub.
      - /path/to/your/music:/music:ro
    environment:
      - MUSIC_HUB_DATA_DIR=/data
      - MUSIC_HUB_RUNTIME=docker
      - MUSIC_FOLDER=/music
      # Optional display name:
      # - HUB_NAME=My Music Hub
    restart: unless-stopped

2. Start the Hub

docker compose up -d
docker compose ps

Wait until the container is healthy, then open:

http://localhost:38472

From another device on the same network, use:

http://<server-ip>:38472

3. Add Your Music

If you set MUSIC_FOLDER=/music, the hub starts with that folder configured.

If you did not set MUSIC_FOLDER, open the web UI and add it manually:

  1. Go to Settings → Folders.
  2. Choose Add folder.
  3. Enter the container path, usually /music.
  4. Start the scan.

The host path is only used by Docker. Inside Music Hub, always use the container path from the volume mount.

4. Pair Mobile Apps

For first pairing:

  1. Open the Docker web UI at http://<server-ip>:38472.
  2. Go to Settings → Pairing.
  3. Arm pairing if needed.
  4. Scan the QR with the Music Hub mobile app.
  5. Keep the phone on the same Wi-Fi/LAN for the first connection.

The QR includes the LAN address the phone should use. If you open the UI from another machine with http://<server-ip>:38472, Docker can usually infer the correct address automatically.

Docker Desktop and NAT

When you run Docker Desktop on Mac or Windows, the browser often opens the UI as http://localhost:38472. A phone cannot use your laptop's localhost, so advertise the laptop's LAN IP explicitly.

Find your LAN IP, then add:

environment:
  - MUSIC_HUB_ADVERTISE_HOST=192.168.1.40
  - MUSIC_HUB_ADVERTISE_PORT=38472

If your host port differs from the container port, the advertised port must be the host port:

ports:
  - "38474:38472"
environment:
  - MUSIC_HUB_ADVERTISE_HOST=192.168.1.40
  - MUSIC_HUB_ADVERTISE_PORT=38474

Then restart:

docker compose up -d

Data and Backups

Keep /data on fast persistent storage:

./data/
  music.db
  music.db-wal
  config.json
  logs/

Back up ./data. Your music files are not copied into the Docker image or database; they stay in the mounted music folder.

Demo Music in Development

The local development compose override may mount:

- ./demomusic:/music:ro

That folder is only a runtime mount for local testing. It is excluded from the Docker image and is not shipped.

Remote access (Tailscale & Cloudflare)

Docker includes bundled helpers for Settings → Remote. See the full server guide in the repo (desktop/docs/SERVER-DOCKER.md) for Cloudflare tokens and compose caps.

Tailscale when the host already runs it

Many NAS and Linux users already have Tailscale on the host. In default bridge networking the container cannot see the host 100.x address automatically. Set:

environment:
  - MUSIC_HUB_TAILSCALE_HOST=100.64.1.5

Then open Settings → Remote → Tailscale. Music Hub detects native Tailscale, skips embedded login, and advertises 100.x.x.x:38472 in the pairing QR.

If you do not have host Tailscale, use embedded tsnet instead (requires NET_ADMIN and /dev/net/tun in compose — see docker-compose.yml comments).

Cloudflare

Use Settings → Remote → Cloudflare from the LAN web UI. The hub runs cloudflared inside the container and stores credentials under ./data/config.json.

Updating

docker compose pull
docker compose up -d

Database migrations run automatically on startup. Back up ./data before major updates.

Docker image architecture

The official image at ghcr.io/gordo-labs/music-hub/server:latest must be published as a multi-architecture image for both linux/amd64 and linux/arm64.

That matters because Docker Desktop on Apple Silicon and many ARM NAS/server boards need arm64, while common NAS, seedbox, and Linux server installs need amd64. If a fresh pull fails with an architecture error, report it in Telegram (opens in a new tab) or WhatsApp (opens in a new tab).

Troubleshooting

Web UI Does Not Open

docker compose ps
docker compose logs music-hub
curl http://localhost:38472/api/ping

The expected ping response is:

{"status":"ok"}

Phone Says It Is Not on the Same Wi-Fi

Check that the QR contains a LAN-reachable address, not localhost:

  1. Open the UI from http://<server-ip>:38472, not only http://localhost:38472.
  2. If you use Docker Desktop or a custom port, set MUSIC_HUB_ADVERTISE_HOST and MUSIC_HUB_ADVERTISE_PORT.
  3. Confirm the phone can open http://<server-ip>:38472 in its browser.
  4. Re-arm pairing and scan a fresh QR.

Music Folder Is Empty

Check the mount from inside the container:

docker compose exec music-hub ls /music

If /music is empty, fix the host path in docker-compose.yml. If files are visible but not scanned, add /music in Settings → Folders or set MUSIC_FOLDER=/music.

NAS Permissions

The container runs as a non-root user. Your media folder must be readable by the container.

For read-only music libraries, make sure the files are at least world-readable or readable by the mapped container user.

NAS Notes

Synology, Unraid, and TrueNAS all work with the same model:

  1. Create a persistent app/data folder for /data.
  2. Mount your music share as /music:ro.
  3. Expose port 38472.
  4. Open http://<nas-ip>:38472.
  5. Pair phones from the QR shown by that Docker hub.
Getting StartedFeatures