Debian / Docker installation • Spotycast Classic and Premium

How to install Spotycast on Debian and Docker

Restore Spotify-controlled playback on legacy Linux streamers without rebuilding your audio system. Deploy Spotycast on a separate Debian/Linux host, select the receiving protocol your player supports, then verify the correct audio path: Icecast HTTP radio for Classic, or a dedicated renderer backend for Premium.

Start installation →Understand the architecture

Docker Compose / Portainer • Roon • LMS / Lyrion • Volumio / moOde • OpenHome

Before you start: three decisions

1. Choose a host

The reference installation uses an AMD64/x86-64 Debian or compatible Linux host/VM with Docker and Compose. Keep the Spotycast bridge separate from your legacy audio appliance.

2. Check your LAN

Spotify discovery and renderer discovery may need local-network visibility. Start on a simple trusted LAN; troubleshoot VLAN, multicast and firewall restrictions only if necessary.

3. Choose an output

Use Classic when your player accepts an HTTP radio URL. Use Premium for a supported Squeezelite/LMS, MPD, Roon or OpenHome renderer backend.

Spotycast does not repair an abandoned Spotify client inside your streamer. It relocates the Spotify-facing integration to another Linux host while preserving compatible receiving hardware. If the problem might be discovery or output configuration, start with Spotify Connect troubleshooting.

Classic / Free or Premium 3.x?

Classic / Free

Use a stable Icecast radio URL

Spotycast Classic uses spotifyd → Liquidsoap → Icecast and publishes an HTTP stream that compatible players can open as radio.

  • No Spotycast Premium installation key
  • Compressed Spotify source, up to approximately 320 kbps
  • Roon Live Radio, LMS and compatible HTTP receivers
  • Validate by playing the Icecast mountpoint
Explore Classic →
Premium 3.x

Use a direct renderer backend

Premium uses Soloist → PipeWire → dedicated renderer backend, not the Classic Icecast radio output as its primary playback route.

  • Spotycast Premium installation key required
  • Separate Soloist API key required
  • Squeezelite/LMS, MPD, Roon and OpenHome backends
  • Validate in Manager and on the receiving renderer
Explore Premium →

Step 1 — Deploy the Spotycast Docker container

Both installation paths start in the same reference container. You may deploy it with Docker Compose on the Debian host or as a Portainer Stack. The sample below uses the project’s existing reference image and host networking.

Security first: The container runs privileged and exposes administrative SSH/VNC/noVNC interfaces under host networking. Deploy only on a trusted, firewalled LAN or isolated VM. Do not expose these interfaces to the public internet. Use strong unique passwords and review the security implications before deployment.

Docker Compose — host-network reference

services:
  spotycast:
    image: chourmovs/debian13-vnc-novnc-ssh:latest
    container_name: spotycast
    restart: unless-stopped
    network_mode: host
    privileged: true
    shm_size: "1gb"
    environment:
      USERNAME: "radio"
      USER_UID: "1000"
      USER_GID: "1000"
      SSH_PASSWORD: "${SPOTYCAST_SSH_PASSWORD}"
      VNC_PASSWORD: "${SPOTYCAST_VNC_PASSWORD}"
      ROOT_PASSWORD: "${SPOTYCAST_ROOT_PASSWORD}"
      ALLOW_ROOT_SSH: "no"
      VNC_GEOMETRY: "1600x900"
      VNC_DEPTH: "24"
      ICECAST_PORT: "28000"
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./spotycast-data:/data

With network_mode: host, the container uses host ports directly. A ports: mapping is intentionally omitted: it is not used with host networking. Before deployment, set the three password variables through a protected environment file or Portainer environment settings; do not publish actual credentials in a shared YAML file.

Prepare the environment variables

On the Docker host, create the spotycast directory and an environment file with restrictive permissions. Generate distinct values for SSH, VNC and root. Do not copy passwords from a tutorial.

mkdir -p spotycast && cd spotycast
umask 077
printf 'SPOTYCAST_SSH_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
printf 'SPOTYCAST_VNC_PASSWORD=%s\n' "$(openssl rand -hex 24)" >> .env
printf 'SPOTYCAST_ROOT_PASSWORD=%s\n' "$(openssl rand -hex 24)" >> .env
chmod 600 .env
nano compose.yml
docker compose config --quiet
docker compose up -d
docker compose ps
Store the complete Compose YAML above in compose.yml before running docker compose config. Keep .env private and backed up securely. If your image’s entrypoint has additional password requirements, follow its documentation.

Portainer alternative

  1. Open Stacks → Add stackName the stack spotycast and paste the same Compose definition.
  2. Set strong environment valuesDefine SPOTYCAST_SSH_PASSWORD, SPOTYCAST_VNC_PASSWORD and SPOTYCAST_ROOT_PASSWORD as protected stack variables, not tutorial passwords.
  3. Deploy on the trusted LANStart the container, verify its status, then access noVNC only from an authorized machine.
http://<SPOTYCAST-HOST>:6080/vnc.html

The URL is a local network example, not a public web endpoint. Launch LXTerminal in the container desktop to run the installer for your selected edition.

Step 2A — Install Spotycast Classic / Free

Choose this branch if your existing player can open a conventional HTTP radio stream. The reference image includes the Classic installer under /root/binaries.

cd /root/binaries
./spotifyd-free

Let the installer finish and follow its prompts. The Classic playback path is spotifyd → local audio → Liquidsoap → Icecast → HTTP-compatible player.

The important downstream result is the playable Icecast stream. Merely seeing a Spotify Connect endpoint in the Spotify app does not verify that Liquidsoap, Icecast and the receiving player work.

Step 2B — Install Spotycast Premium 3.0.6

Choose this branch for a dedicated renderer path. Premium uses Soloist to handle Spotify playback, PipeWire to route audio, and the compatible backend you select in the Manager. It does not require starting Spotify Desktop and should not be tested as a Classic Icecast stream.

Before starting: Have both your Spotycast Premium installation key and your separate Soloist API key available. They are independent credentials. Do not publish them in logs, screenshots or configuration examples.
cd /root/binaries
./spotifyd-premium

What Premium sets up

Spotycast Core

Common orchestration layer for Premium.

Soloist

Spotify-facing engine authenticated using your Soloist API key.

PipeWire

Audio routing and creation of the sinks needed by supported renderers.

Manager GUI

Local management interface for installing, enabling and diagnosing renderer backends.

Select only the backend you need

Squeezelite / LMS

For compatible Lyrion Music Server, Squeezebox and Squeezelite setups.

MPD

For MPD-oriented playback including compatible Volumio and moOde workflows.

Roon

Dedicated Roon renderer path managed independently from the Icecast radio endpoint.

OpenHome / UPnP

For compatible renderers that can be discovered and reached over the LAN.

If Classic was previously installed in the same container, disable conflicting Classic services before enabling Premium, according to your installed release. Configure and validate one renderer backend at a time.

Step 3 — Verify the output you installed

Classic test

Check the Icecast HTTP stream

  1. Start playback to the Spotycast/spotifyd endpoint from Spotify.
  2. Open the Icecast status page at the configured host and port.
  3. Confirm a mountpoint is available.
  4. Open that mountpoint in VLC, ffplay or your target HTTP radio player.
http://<SPOTYCAST-HOST>:28000
vlc http://<SPOTYCAST-HOST>:28000/spotify.aac
ffplay http://<SPOTYCAST-HOST>:28000/spotify.aac

These are reference URLs for port 28000 and an AAC mountpoint. Confirm the real port, mountpoint and codec generated by your installed Classic configuration.

Premium test

Check the direct renderer path

  1. Open the Manager and confirm that the selected backend is enabled.
  2. Check Status and, when needed, Renderer logs.
  3. Verify that the target renderer is reachable on the LAN.
  4. Select the Premium Connect endpoint in Spotify and start playback.
  5. Confirm audible playback on the intended renderer.
Do not diagnose Premium by searching for an Icecast mountpoint. Its expected success path is direct renderer playback.

Troubleshooting installation problems

Check the component that actually failed; avoid changing networking, credentials and renderer settings simultaneously.

Spotify Connect device missing

Check client/service status, multicast discovery, firewall, Docker networking and LAN visibility. Discovery guide →

Classic stream has no audio

Check the Spotify playback session, Liquidsoap, Icecast status/mountpoint, codec compatibility and radio player output. No audio guide →

Premium backend silent

Confirm both keys, inspect Manager Status and Renderer logs, then check reachability of the specific renderer backend.

Dropouts or buffering

Separate Spotify upstream instability from HTTP buffering, network congestion and receiving backend problems. Dropouts guide →

Useful local checks

supervisorctl status
curl --max-time 5 http://127.0.0.1:28000/status-json.xsl
ss -ltnp | grep 28000

The Icecast checks above apply to Classic and assume its reference port. For Premium, use Manager’s backend-specific Status and Renderer logs first. A failed Classic-only check is not evidence of a Premium failure.

Common pitfalls: testing Premium through Icecast; forgetting the Soloist key; configuring every backend at once; installing directly on legacy firmware; exposing SSH/VNC on an untrusted network; or changing a working Docker network topology without a specific reason.

Frequently asked installation questions

Can I run Spotycast on a Debian VM instead of my streamer?
Yes. A separate compatible Debian/Linux host or VM is the reference deployment. The receiving player remains in your audio system and must support the selected Icecast or renderer protocol.
Should I use Classic or Premium for Roon?
Classic can provide an HTTP radio input for Roon Live Radio. Premium uses a dedicated Roon renderer backend. Choose according to your desired receiving path; see Spotify with Roon.
Does Premium require an Icecast URL?
No. Premium 3.x uses Soloist, PipeWire and dedicated renderer backends. Its validation method differs from Classic’s Icecast mountpoint test.
Does a green Spotify Connect device guarantee sound?
No. The Spotify-facing endpoint and the downstream renderer are separate. Verify end-to-end playback using the installed edition’s corresponding audio output.
Is the sample Docker Compose safe on the internet?
No. It uses host networking and a privileged desktop-enabled container. Restrict it to a trusted LAN or properly isolated host, secure SSH/VNC and never expose administrative ports publicly.

Three steps: deploy, choose, verify.

Install Spotycast on your Linux host, choose Classic for an Icecast HTTP radio endpoint or Premium for a compatible direct renderer backend, then verify the correct receiving path. Keep your existing streamer when its audio hardware still works.

Start with Docker →Need support?

Spotycast is an independent project and is not affiliated with or certified by Spotify or the audio manufacturers mentioned. Supported backends, authentication requirements and stream formats depend on the installed release.