Guide to Self-Hosting Koel on VPS for a Professional Personal Music Streaming Service
This guide walks through setting up a self-hosted personal music streaming service using Koel on a VPS, offering a professional alternative to Spotify. You'll install Koel with...
This guide walks through setting up a self-hosted personal music streaming service using Koel on a VPS, offering a professional alternative to Spotify. You'll install Koel with Docker, configure Nginx and SSL, optimize performance, and secure your setup. Koel is an open-source platform that lets you build your own music library, supports multiple formats, streams directly, and integrates with mobile apps. The process includes system requirements, Docker setup, configuration, security, and troubleshooting steps to ensure a smooth, professional-grade experience.
System Requirements and Preparation
To self-host Koel, you need a VPS with at least 2GB RAM and 20GB SSD storage. For optimal performance, choose an NVMe-based VPS to ensure high I/O throughput for continuous music playback. You can select a NVMe Cloud VPS for Docker, Nginx & Databases to meet these requirements. Additionally, you need a domain name (or subdomain) and SSH access to your server.
Prepare the necessary tools: Docker, Docker Compose, Nginx, and a database such as MySQL or PostgreSQL. Koel uses Docker for simplified deployment, so installing Docker is the first step. You can refer to Disk I/O and IOPS: Key Factors in VPS Performance to select a VPS with suitable I/O characteristics for music streaming.
Installing and Configuring Koel
First, install Docker and Docker Compose on your VPS. Use the following commands:
sudo apt update
sudo apt install docker.io docker-compose -y
sudo systemctl enable docker
sudo systemctl start docker
After installation, create a directory for Koel and generate a docker-compose.yml file:
mkdir koel
cd koel
nano docker-compose.yml
Paste the following content into the file:
version: '3.8'
services:
koel:
image: koel/koel:latest
container_name: koel
ports:
- "80:80"
environment:
- APP_KEY=base64:your_random_key_here
- DB_CONNECTION=mysql
- DB_HOST=koel-db
- DB_PORT=3306
- DB_DATABASE=koel
- DB_USERNAME=koel
- DB_PASSWORD=your_password
volumes:
- ./music:/var/www/koel/storage/music
- ./config:/var/www/koel/config
depends_on:
- koel-db
restart: unless-stopped
koel-db:
image: mysql:8.0
container_name: koel-db
environment:
MYSQL_ROOT_PASSWORD: root_password
MYSQL_DATABASE: koel
MYSQL_USER: koel
MYSQL_PASSWORD: your_password
volumes:
- ./db:/var/lib/mysql
restart: unless-stopped
Replace `your_random_key_here` with a random key generated using `openssl rand -base64 32`. Create the `music` folder for your music files and `config` for configuration files.
Integrating Nginx and SSL
To access Koel via a domain name and secure it with HTTPS, configure Nginx. Create an Nginx configuration file at `/etc/nginx/sites-available/koel`:
server {
listen 80;
server_name your-domain.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl;
server_name your-domain.com;
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
location / {
proxy_pass http://localhost:80;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Run the following command to generate a Let's Encrypt certificate:
sudo certbot certonly --nginx -d your-domain.com
Restart Nginx and Docker:
sudo systemctl restart nginx
docker-compose up -d
Performance Optimization and Security
Koel supports features like category-based playback, search, and streaming. To optimize performance, store your music library on SSD and use Redis for caching. You can add Redis to the `docker-compose.yml` file:
koel-redis:
image: redis:alpine
container_name: koel-redis
restart: unless-stopped
Modify the `config/app.php` file to use Redis as the cache driver.
For security, configure the firewall (UFW) to allow only ports 80, 443, and SSH. Regularly update Koel and the operating system. Refer to Zero-Downtime VPS Migration Between Providers: Strategy and Practical Guide to ensure stability during upgrades.
Verification and Troubleshooting
To verify Koel is running, access `https://your-domain.com` in your browser. If you see the login interface, the installation was successful. If not, check the Docker logs with `docker-compose logs koel`.
If access fails, verify that Nginx is configured correctly, the domain is pointed to the VPS, and the SSL certificate has been issued. If you encounter database errors, check the `docker-compose.yml` file to ensure all environment variables are correct.
References
Recommended NVMe Cloud VPS Plans to Deploy This Setup
Enterprise RAID 10 NVMe SSDs, CMC & FPT District 9 uplinks with Anycast Anti-DDoS and 99.99% SLA.
VPS-3E
10% VAT included
- CPU: 2 vCPU
- RAM: 4 GB
- SSD: 50 GB NVMe
