Back to articles
DevOps & Systems

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...

DPTCloud Engineering4 min read
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 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

DPTCloud Tier III Infrastructure

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.

View 22 VPS Plans
ECO · vn-02

VPS-2E

94.600 ₫ / mo

10% VAT included

  • CPU: 2 vCPU
  • RAM: 2 GB
  • SSD: 30 GB NVMe
ECO · vn-02Recommended

VPS-3E

170.500 ₫ / mo

10% VAT included

  • CPU: 2 vCPU
  • RAM: 4 GB
  • SSD: 50 GB NVMe
BASIC · vn-01Recommended

VPS-05

457.600 ₫ / mo

10% VAT included

  • CPU: 4 vCPU
  • RAM: 8 GB
  • SSD: 50 GB NVMe

Related Articles

View all
ZaloZalo SupportDiscord0384 753 478