How to install Spotycast with Docker

Before you start

This page is the operational install guide. It assumes you are comfortable running a Linux host, VM, NAS or self-hosted server and deploying a Docker Compose stack.

1) Deploy the Docker Compose stack

The Docker stack provides the container, GUI access, runtime dependencies, and exposed ports required by the Spotycast installers. For the architecture behind the bridge, see How Spotycast works.

Prerequisites

• An I386/AMD64 Linux host such as a NAS, server, Debian VM or Proxmox instance.
• Docker and the Docker Compose plugin.
• Portainer Stacks, recommended, or another Docker management UI able to deploy a Compose file.
• Network access to the host for noVNC / VNC, optional, and Icecast, which exposes the audio endpoint.

Recommended ports

Keep ports consistent with your current setup. Below is a common baseline you can adapt.

# SSH into container, optional
2222:22

# VNC / noVNC, optional
5901:5901
6080:6080

# Icecast HTTP stream endpoint
28000:28000

Docker Compose file

Paste this into Portainer → Stacks → Add stack → Web editor, or your Compose / Stack editor.

services:
  spotycast:
    image: chourmovs/debian13-vnc-novnc-ssh:latest
    container_name: spotycast
    restart: unless-stopped

    # Mandatory for the Free version in many Spotify Connect discovery setups
    network_mode: host

    privileged: true
    shm_size: "1gb"

    # With network_mode: host, Docker may ignore explicit port mappings.
    # They are listed here as a port reference if you adapt the stack.
    ports:
      - "2222:22"
      - "5901:5901"
      - "6080:6080"
      - "28000:28000"

    environment:
      # Interactive desktop session
      USERNAME: "radio"
      USER_UID: "1000"
      USER_GID: "1000"

      # Access
      SSH_PASSWORD: "hackme"
      VNC_PASSWORD: "hackme"
      ROOT_PASSWORD: "hackme"
      ALLOW_ROOT_SSH: "yes"

      VNC_GEOMETRY: "1600x900"
      VNC_DEPTH: "24"

      ICECAST_PORT: "28000"

    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./spotycast-data:/data

mkdir -p spotycast && cd spotycast
nano docker-compose.yml
docker compose up -d
docker compose ps

2) Install / enable the Free version

The Free installer binary is already present in /root/binaries inside the container and should be executable. Run it manually from LXTerminal.

Run the Free binary

cd /root/binaries
./spotifyd-free

What the Free installer does

• Configures the standard audio pipeline, typically Spotify playback → PulseAudio → Liquidsoap → Icecast.
• Starts the required services inside the container.
• Exposes Icecast mountpoints once playback becomes active.
• Provides the baseline Spotycast path for players that consume HTTP radio streams.

3) Install / enable the Premium version

Premium is the advanced path for richer profiles, more endpoint flexibility, and a more demanding playback workflow. See the product-level positioning here: Spotycast Premium.

Run the Premium binary

cd /root/binaries
./spotifyd-premium

Activation

• When prompted, paste your Premium installation key.
• The installer validates the key and enables Premium features.
• Do not paste your premium key into public GitHub issues, screenshots, forums or support threads.

Start Spotify Desktop for the Premium workflow

export DISPLAY=:1
spotycast-start-spotify

• Log into Spotify Desktop.
• Select the desired quality level, including Lossless where available in your environment.
• Then validate the resulting Icecast / HTTP stream from the player side.

4) Validate the Icecast stream

Once Free or Premium is enabled, validate the chain before integrating it into your main player. The simplest test is to check Icecast first, then test the stream URL from another client.

Open Icecast

http://<HOST>:28000

Test the stream URL

vlc http://<HOST>:28000/spotify.aac
ffplay http://<HOST>:28000/spotify.aac

Diagnostics

If installation succeeds but playback, discovery or mountpoint exposure does not behave as expected, inspect the service logs below. For broader architecture context, cross-check with How it works.

Useful logs inside the container

tail -n 200 /var/log/spotify-roon-bridge/liquidsoap.stderr.log || true
tail -n 200 /var/log/spotify-roon-bridge/icecast2.stderr.log || true
tail -n 200 /var/log/spotify-roon-bridge/pulseaudio.stderr.log || true

Quick service checks

ss -ltnp | grep 28000 || true
curl --max-time 5 http://127.0.0.1:28000/status-json.xsl || true
ps aux | grep -E "spotify|liquidsoap|icecast|pulse" | grep -v grep || true

Common installation mistakes

Most failed installs are not caused by Icecast itself. They usually come from edition conflicts, network discovery constraints, wrong host URL, stale mountpoint, or player-side assumptions.