• 1 novnc opening
    NoVnc landing page, clic "connect"

How to Install Spotycast with Docker

This page covers the Docker deployment, then shows how to manually run the installer binaries shipped inside the container to publish Spotify as a stable Icecast / HTTP stream for your players. If you want the high-level overview first, start with the Spotify to Icecast bridge guide.

Start install
See how it works
1) Deploy Docker stack 2) Enable Free 3) Enable Premium Diagnostics
Running into discovery issues? Check the FAQ.

1) Deploy the Docker Compose stack

This page is the practical installation path for Spotycast. For the conceptual overview of why this architecture exists and what a Spotify to Icecast bridge actually does, see Spotify to Icecast.

Important: deploying the Docker Compose stack does not install Free or Premium. It only deploys the container, GUI and required runtime environment. You enable Free or Premium manually in step 2 or step 3.

Prerequisites

  • An I386/AMD64 Linux host such as a NAS, server or Proxmox instance with 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 (example)

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
28000:28000

Docker Compose file (template)

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 free version only
    network_mode: host

    privileged: true
    shm_size: "1gb"

    ports:
      - "2222:22"
      - "5901:5901"
      - "6080:6080"
      - "28000:28000"

    environment:
      # Session interactive / desktop
      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

Portainer deployment

Stacks → Add stack → name it spotycast → paste YAML → deploy.

CLI deployment (optional)

Use this if you prefer a terminal-only workflow.

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

Open the container GUI

Open noVNC at http://<HOST>:6080/vnc.html, then launch LXTerminal.

2) Install / Enable the Free version

Current behavior: the Free installer binary is already present in /root/binaries inside the container and is executable. You run it manually from LXTerminal.

Run the Free binary

cd /root/binaries
./spotifyd-free

What the Free installer does

  • Configures the audio pipeline, typically Spotify playback → PulseAudio → Liquidsoap → Icecast.
  • Starts the required services inside the container.
  • Exposes Icecast mountpoints once playback becomes active.

Quick validation

  • Open Icecast at http://<HOST>:28000.
  • Verify the expected mountpoints are visible.
  • Start Spotify playback and check that the stream remains stable from your player side.
Want the implementation details behind this chain? See How the Spotify to Icecast bridge works.

3) Install / Enable the Premium version

Upgrade note: if you previously enabled the Free version, disable or uninstall it first to avoid conflicts such as duplicate services, overlapping configs or port collisions.

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.
  • For the Premium workflow, launch Spotify Desktop with:
export DISPLAY=:1
spotycast-start-spotify
  • Log into Spotify Desktop, then select the desired quality level, including Lossless where available in your environment.
For the product-level comparison between the standard path and the premium path, see Spotycast Premium.

Diagnostics

If installation succeeds but playback 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, copy and paste them in LXTerminal:
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
Still troubleshooting? See the FAQ and the architecture page.

Related: