slskd (Soulseek) Setup Guide

Introduction

slskd is a headless, modern daemon for the Soulseek peer-to-peer network featuring a web-based user interface and REST API. It offers precise, single-track control over music downloads, making it an ideal alternative or companion to automated album managers like Lidarr.

---

Step 1: Initial Container Deployment

1. Ensure the required Soulseek environment variables are present in your root .env file:

SLSKD_USERNAME=your_soulseek_username
SLSKD_PASSWORD=your_soulseek_password
SLSKD_HTTP_PORT=5030
SLSKD_HTTPS_PORT=5031
SLSKD_P2P_PORT=50300

2. Copy the Compose service template into your active server directory:

cp compose/templates/soulseek.yaml compose/server1/soulseek.yaml

3. Create the app configuration directory and copy your sanitized baseline config (slskd_example.yml) into place:

sudo mkdir -p ${DOCKERDIR}/soulseek/app
cp scripts/slskd_example.yml ${DOCKERDIR}/soulseek/app/slskd.yml

4. Launch the container:

docker compose -p mediaserver -f docker-compose-server1.yaml up -d soulseek

⚠️ VPN Routing Notice: This container routes all network traffic through the VPN connection supplied by network_mode: "service:transmission-openvpn". Port mappings are inherited directly from the primary VPN service container rather than declared inside soulseek.yaml.

---

Step 2: Service Definition (soulseek.yaml)

# ------------------------------------------------------------------------------
# slskd - Soulseek daemon with web GUI
# ------------------------------------------------------------------------------
services:
  soulseek:
    container_name: soulseek.${HOST_NAME}
    image: slskd/slskd:latest
    environment:
      TZ: ${TZ}
      PUID: ${PUID}
      PGID: ${PGID}

      # --- Soulseek credentials ---
      SLSKD_USERNAME: ${SLSKD_USERNAME}
      SLSKD_PASSWORD: ${SLSKD_PASSWORD}

      # --- Optional integration key for Spotify-to-Plex ---
      SLSKD_API_KEY: ${LIDARR_API_KEY}
      SLSKD_REMOTE_CONFIGURATION: true

      UMASK: "002"

    # Use the transmission-openvpn network for privacy    
    network_mode: "service:transmission-openvpn"

    volumes:
      - ${DOCKERDIR}/soulseek/app:/app      
      - ${USERDOWNLOAD}/Torrents:/downloads

    restart: on-failure:4
    security_opt:
      - no-new-privileges:true

    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "homepage.group=Media"
      - "homepage.name=Soulseek"
      - "homepage.icon=https://raw.githubusercontent.com/slskd/slskd/master/docs/icon.png"
      - "homepage.href=http://soulseek.${HOST_NAME}:${SLSKD_HTTP_PORT}"
      - "homepage.description=Soulseek daemon with web GUI"

---

Step 3: Application Template (scripts/slskd_example.yml)

When you copy scripts/slskd_example.yml to ${DOCKERDIR}/soulseek/app/slskd.yml, it contains the default configuration below. You can edit this file to customize your paths or credentials before launching the container:

directories:
  incomplete: /downloads/Incomplete
  downloads: /downloads/Completed/Soulseek

web:
  https:
    disabled: false
    port: 5031
  authentication:
    disabled: false
    api_keys:
      lidarr_api:
        key: ${SLSKD_API_KEY} # Reuses your Lidarr API Key for SpotifyToPlex/scripting integration
        role: readwrite
        cidr: 0.0.0.0/0,::/0

soulseek:
  address: vps.slsknet.org
  port: 2271
  username: ${SLSKD_USERNAME}
  password: ${SLSKD_PASSWORD}

Key Configuration Notes

• directories: Maps incoming downloads into subfolders inside the container's /downloads mount (${USERDOWNLOAD}/Torrents/Completed/Soulseek).
• web.authentication.api_keys: Defines an API key (lidarr_api) allowing external automation tools like SpotifyToPlex to trigger searches and download single tracks.
• soulseek: Configures the primary Soulseek server endpoint and injects your account credentials.

💡 **Soulseek Account Creation: You do not need to register on a website beforehand. The Soulseek network registers new accounts automatically upon first connection using the username and password set in your configuration file. If the service fails to connect on startup, your chosen username is likely already taken. Simply change your username to something unique and restart the container.

---

Step 4: Accessing the UI & Initial Setup

1. Open your browser and navigate to http://<your-ip-address>:5030 (or the port routed through your VPN service).
2. Log in using your web authentication credentials or configured API access.
3. Verify connection status to the Soulseek network in the bottom status bar.

---

Step 5: Backup & Restore

Backing Up

Stop the service and compress the app configuration directory:

docker compose -p mediaserver -f docker-compose-server1.yaml stop soulseek
tar -czvf slskd_backup.tar.gz ${DOCKERDIR}/soulseek/app
docker compose -p mediaserver -f docker-compose-server1.yaml start soulseek

Restoring

1. Stop the soulseek container.
2. Unpack the backup archive back into ${DOCKERDIR}/soulseek/app.
3. Restart the container.

---

Step 6: Troubleshooting

• Unable to Connect to UI: Ensure that port 5030 is exposed in your transmission-openvpn container definition, as soulseek shares its network stack.
• Authentication Errors: Double-check SLSKD_USERNAME and SLSKD_PASSWORD in your .env file to ensure valid credentials for the Soulseek network.
• Container Logs: Check active logs for connection drops or VPN routing failures:

  docker logs -f soulseek.${HOST_NAME}