Koel

Personal music streaming server that works

Alternative to: spotify, apple music, youtube music

Koel is a free, open-source music streaming solution that turns a personal music collection into a sleek, web-based listening experience. Built on Laravel and Vue, it scans a music library and serves it back through a fast, modern interface, with playlists, smart playlists, scrobbling, podcasts, radio, and Last.fm/Spotify/MusicBrainz integrations.

Koel Docker Compose example

Self-host Koel on your own server, homelab, or VPS starting from this Docker Compose example. It runs Koel in Docker containers using the official phanan/koel:latest, mariadb:lts images, with persistent volumes and automatic restarts preconfigured. Review the environment variables and adjust them to your setup, save the file as compose.yml (or docker-compose.yml), and start the stack with docker compose up -d.

services:
  koel:
    image: phanan/koel:latest
    depends_on:
      - database
    volumes:
      - music:/music
      - image_storage:/var/www/html/storage/app/public/images
      - search_index:/var/www/html/storage/search-indexes
    environment:
      # Database driver Koel connects with.
      DB_CONNECTION: "mysql"
      # Hostname of the database service on the compose network.
      DB_HOST: "database"
      # Database user Koel connects as (must match the database service).
      DB_USERNAME: "koel"
      # Password for the database user (must match the database service).
      DB_PASSWORD: "koel"
      # Database/schema name (must match the database service).
      DB_DATABASE: "koel"
      # Base64 application key used to encrypt sessions and stored credentials.
      # Must be a valid Laravel key ("base64:" + base64 of 32 bytes); set a fixed
      # value so it is preserved across container recreation.
      APP_KEY: "base64:pN79p+brmbwbFiz87xJQ4MDGiCs/+5nrU581l8C6et0="
    restart: unless-stopped

  database:
    image: mariadb:lts
    volumes:
      - db:/var/lib/mysql
    environment:
      # Root password for the MariaDB instance (internal to the compose network).
      MYSQL_ROOT_PASSWORD: "koel-root"
      # Database created on first start.
      MYSQL_DATABASE: "koel"
      # Application database user created on first start.
      MYSQL_USER: "koel"
      # Password for the application database user (must match Koel's DB_PASSWORD).
      MYSQL_PASSWORD: "koel"
    restart: unless-stopped

volumes:
  music:
  image_storage:
  search_index:
  db:

Prefer a managed setup? WinterFlow installs, configures, and updates Koel for you using this same Docker Compose configuration.