Deploying slskd

Introduction

slskd is a modern, web-based client for the Soulseek peer-to-peer file sharing network. It provides a sleek, responsive interface that allows you to search for and download files, manage your shared library, and interact with the Soulseek community from any device with a web browser.

Built with .NET and React, slskd offers a feature-rich experience while maintaining low resource usage. The application runs as a background service, making it perfect for always-on deployments where you want continuous access to the Soulseek network.

Key highlights of slskd:

Web-Based Interface: Access Soulseek from any device through a modern, responsive web UI
Search Functionality: Search the entire Soulseek network for files with advanced filtering options
Download Management: Queue, prioritize, and manage downloads with a comprehensive download manager
Share Management: Configure and manage your shared files and folders
User Management: Track users, browse their shares, and manage your user list
Chat Support: Send and receive messages through the Soulseek chat system
Room Support: Join and participate in Soulseek chat rooms
API Access: RESTful API for automation and integration with other tools
Multi-User Support: Support for multiple user accounts with different permissions
Open Source: Licensed under AGPL-3.0

This guide walks through deploying slskd on Klutch.sh using Docker, configuring persistent storage for your downloads and shares, and setting up the application for production use.

Why Deploy slskd on Klutch.sh

Deploying slskd on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds slskd without complex orchestration. Push to GitHub, and your Soulseek client deploys automatically.

Persistent Storage: Attach persistent volumes for your downloads, shared files, and configuration. Your data survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your slskd interface from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Always-On Access: Your Soulseek client remains connected 24/7 without managing your own hardware, enabling continuous downloads and shares.

Scalable Resources: Allocate CPU and memory based on your usage patterns and download needs.

Custom Domains: Assign a custom domain for easy access to your slskd instance.

Prerequisites

Before deploying slskd on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your slskd configuration
A Soulseek account (username and password)
Basic familiarity with Docker and containerization concepts
(Optional) A custom domain for your slskd instance

Preparing Your Repository

To deploy slskd on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

slskd-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM slskd/slskd:latest

# Set environment variables
ENV SLSKD_HTTP_PORT=5030
ENV SLSKD_SLSK_LISTEN_PORT=50300

# Soulseek credentials (set via Klutch.sh environment variables)
ENV SLSKD_SLSK_USERNAME=${SLSKD_SLSK_USERNAME}
ENV SLSKD_SLSK_PASSWORD=${SLSKD_SLSK_PASSWORD}

# Application configuration
ENV SLSKD_REMOTE_CONFIGURATION=true

# Expose ports
EXPOSE 5030

# The base image includes the default entrypoint

Creating the .dockerignore File

Create a .dockerignore file to exclude unnecessary files from the build:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
`SLSKD_SLSK_USERNAME`	Yes	-	Your Soulseek username
`SLSKD_SLSK_PASSWORD`	Yes	-	Your Soulseek password
`SLSKD_HTTP_PORT`	No	5030	Web interface port
`SLSKD_REMOTE_CONFIGURATION`	No	false	Enable remote configuration

Deploying slskd on Klutch.sh

Once your repository is prepared, follow these steps to deploy slskd:

Push Your Repository to GitHub

Initialize your repository and push to GitHub. Ensure your Dockerfile is in the root of your repository.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “slskd” or “soulseek-client”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your slskd Dockerfile.

Configure HTTP Traffic

slskd serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 5030

Set Environment Variables

In the environment variables section, add:

Variable	Value
`SLSKD_SLSK_USERNAME`	Your Soulseek username
`SLSKD_SLSK_PASSWORD`	Your Soulseek password
`SLSKD_REMOTE_CONFIGURATION`	`true`

Attach Persistent Volumes

Persistent storage is essential for slskd. Add the following volumes:

Mount Path	Recommended Size	Purpose
`/app`	1 GB	Application data and configuration
`/downloads`	50+ GB	Downloaded files
`/shares`	50+ GB	Files you want to share

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the slskd container
Provision an HTTPS certificate

Access slskd

Once deployment completes, access your slskd instance at https://your-app-name.klutch.sh. The default credentials are:

Username: slskd
Password: slskd

Change these immediately after first login.

Initial Configuration

Changing Default Credentials

After your first login:

Navigate to Options in the web interface
Go to the Web section
Change the default username and password
Save your changes

Configuring Shared Folders

To share files with the Soulseek network:

Go to Options > Shares
Add directories from your /shares volume
Configure exclusion patterns if needed
Trigger a rescan to index your files

Download Settings

Configure your download preferences:

Navigate to Options > Downloads
Set download directory to /downloads
Configure filename templates
Set concurrent download limits

Production Best Practices

Security Recommendations

Change Default Credentials: Immediately change the default slskd web credentials
Strong Passwords: Use strong, unique passwords for both slskd and your Soulseek account
Environment Variables: Store sensitive credentials in Klutch.sh environment variables, not in your repository

Performance Optimization

Volume Sizing: Allocate sufficient storage for your expected download volume
Concurrent Downloads: Adjust concurrent download limits based on available bandwidth
Share Indexing: Schedule share rescans during low-activity periods

Backup Strategy

Configuration Backup: Back up your /app volume containing settings
Download Management: Regularly move completed downloads to permanent storage

Troubleshooting Common Issues

Cannot Connect to Soulseek Network

Symptoms: Connection status shows disconnected or failed.

Solutions:

Verify your Soulseek credentials are correct
Check that environment variables are properly set
Review application logs for connection errors

Downloads Not Starting

Symptoms: Downloads queue but don’t progress.

Solutions:

Check available disk space on the downloads volume
Verify network connectivity
Check if the source user is online

Web Interface Not Accessible

Symptoms: Cannot reach the slskd web interface.

Solutions:

Verify the deployment is running
Confirm HTTP traffic is configured for port 5030
Check deployment logs for startup errors

Additional Resources

Conclusion

Deploying slskd on Klutch.sh gives you a modern, web-based Soulseek client with automatic builds, persistent storage, and secure HTTPS access. The combination of slskd’s feature-rich interface and Klutch.sh’s deployment simplicity means you can focus on discovering and sharing music rather than managing infrastructure.

With always-on connectivity, your slskd instance remains connected to the Soulseek network 24/7, enabling continuous downloads and making your shared files available to the community at all times.