wiki/Catalogue-Self-Hosted/apps/app-koel.md

---
title: Koel
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, music, music-streaming, koel, php, vue, subsonic, laravel]
confidence: high
contested: false
sources:
  - https://selfh.st/apps/?tag=Music
  - https://github.com/koel/koel
  - https://koel.dev/
---

# 🎵 Koel

> Serveur personnel de streaming musical écrit en PHP (Laravel) et Vue.js, avec une UI moderne type Spotify, support Subsonic et applications mobiles natives.

## 📋 Informations Générales

| Métadonnée | Valeur |
| :--- | :--- |
| **Site web** | https://koel.dev/ |
| **GitHub** | https://github.com/koel/koel |
| **License** | MIT |
| **Langage** | PHP (Laravel) / Vue.js |
| **Étoiles** | ⭐ 2 107 |
| **Dernière MAJ** | 2026-06-06 |
| **Catégorie** | [[cat-music]] |

## 📝 Description

Koel (littéralement « âme » en espéranto) est un serveur de streaming musical personnel lancé en 2015 par Phan An, conçu pour reproduire l'expérience d'un service commercial comme Spotify ou Apple Music, mais en auto-hébergé. Construit sur **Laravel** côté backend et **Vue.js** côté frontend, l'interface est unanimement reconnue pour son design soigné, sa rapidité et ses thèmes multiples (Classic, Dawn, Jungle, Rose). Le slogan officiel est d'ailleurs « A music streaming solution that works ».

L'application scanne automatiquement votre bibliothèque (FLAC, MP3, OGG, etc.), extrait les métadonnées, récupère les pochettes, et expose le tout via une API REST et l'API **Subsonic/OpenSubsonic** (donc compatible avec Feishin, Symfonium, play:Sub, Substreamer, DSub, Sublime Music, etc.). Koel gère les favoris, les playlists intelligentes, l'égaliseur, les visualiseurs, le multi-utilisateurs, la synchro de lecture cross-device, ainsi que la prise en charge des radios et podcasts.

L'écosystème est complété par les **Koel Player** officiels sur iOS et Android (applications natives), qui se connectent sans configuration supplémentaire. Une offre **Koel Plus** (paiement unique) débloque des pilotes de stockage supplémentaires (S3, Nextcloud, Dropbox, ownCloud), les librairies par utilisateur, la collaboration sur playlists, le SSO, le white labeling, et le thème custom. L'édition Community reste 100 % libre et open-source.

## 🚀 Installation

### Option 1 : Docker Compose (recommandé)

```yaml
# docker-compose.yml
version: "3.8"

services:
  koel:
    image: ghcr.io/koel/koel:latest
    container_name: koel
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "8080:80"
    environment:
      APP_URL: http://koel.local:8080
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: 3306
      DB_DATABASE: koel
      DB_USERNAME: koel
      DB_PASSWORD: ChangeM3_KOEL
      ADMIN_EMAIL: admin@example.com
      ADMIN_PASSWORD: ChangeM3_ADMIN
      ADMIN_NAME: Admin
      LASTFM_API_KEY: ""
      YOUTUBE_API_KEY: ""
      SPOTIFY_CLIENT_ID: ""
      SPOTIFY_CLIENT_SECRET: ""
    volumes:
      - ./music:/music:ro
      - ./covers:/var/www/html/storage/app/public/covers
      - ./config:/var/www/html/storage/app/config

  db:
    image: mariadb:11
    container_name: koel-db
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: koel
      MARIADB_USER: koel
      MARIADB_PASSWORD: ChangeM3_KOEL
      MARIADB_RANDOM_ROOT_PASSWORD: "yes"
    volumes:
      - ./db:/var/lib/mysql
```

Premier lancement : `docker compose up -d && docker compose exec koel php artisan koel:init`.

### Option 2 : Installation manuelle

Prérequis : PHP 8.2+ (avec `ext-mbstring`, `pdo_mysql`, `gd`, `curl`, `intl`), Node 18+, Composer, MySQL/MariaDB. Cloner le repo, `composer install`, `npm ci && npm run prod`, configurer `.env`, lancer `php artisan koel:init` puis servir via Nginx/Apache (ex : `/var/www/koel/public`).

## ⚙️ Configuration

- **Bibliothèque musicale** : variable `MEDIA_PATH` (défaut `/music`), rescanner via `php artisan koel:scan`.
- **Intégrations** : clés API Last.fm, Spotify, YouTube, MusicBrainz (enrichissement des métadonnées).
- **Authentification** : locale par défaut, OAuth possible, header `X-Forwarded-User` en mode proxy (SSO via Authelia/Authentik).
- **Streaming** : `STREAMING_METHOD=transcode` pour transcoder en MP3 (économise la 4G), `proxy` ou `x-accel-redirect` recommandé derrière Nginx.
- **Stockage** : Community = `local`, Koel Plus ajoute S3/Nextcloud/Dropbox.
- **Logs** : `LOG_CHANNEL=stack` (stack daily + papertrail optionnel).

## 🔄 Alternatives

### Open Source
- [[app-navidrome]] — Go, ultra léger, multi-users natifs, Subsonic aussi.
- [[app-ampache]] — PHP historique, compatible Subsonic, plus complet mais UI datée.
- [[app-funkwhale]] — Fédéré (ActivityPub), orienté podcasts et communautés.
- [[app-airsonic]] — Java, Subsonic-compatible.
- [[app-gonic]] — Go, fork d'Airsonic-Advanced, minimaliste.
- [[app-jellyfin]] — Plus généraliste (vidéo + audio + Live TV).
- [[app-icecast]] — Pure serveur de streaming (radio).
- [[app-azuracast]] — Plateforme de webradio (broadcast).

### Propriétaires (ce que cette app remplace)
- Spotify — Streaming musical freemium.
- Apple Music — Streaming musical freemium.
- Tidal — Streaming HiFi/FLAC.
- Deezer — Streaming musical freemium.
- YouTube Music — Streaming avec vidéo.

## 🔒 Sécurité

- **HTTPS obligatoire** (Traefik ou Caddy avec Let's Encrypt) : la bibliothèque musicale est locale mais l'API Subsonic est exposée.
- **Header d'auth** : si reverse proxy SSO, valider `X-Forwarded-User` côté Koel (`TRUSTED_PROXIES`).
- **Chiffrement at-rest** : penser à chiffrer le volume `./music` (LUKS) sur serveur partagé/NAS.
- **Rate limiting** : l'API Subsonic n'est pas throttlée nativement, placer un WAF (CrowdSec) devant.
- **Mises à jour** : suivre les releases GitHub (correctifs XSS et d'auth sur le panel admin).
- **Credentials DB** : changer `ChangeM3_*` en secrets forts stockés dans un fichier `.env` non versionné.
- **Backups** : `./db` (MySQL) et `./covers` (cache pochettes) à sauvegarder régulièrement ; la musique elle-même ne se sauvegarde pas, on la duplique.

## 📚 Ressources

- Site officiel : https://koel.dev/
- Documentation : https://docs.koel.dev/
- Repository : https://github.com/koel/koel
- Apps mobiles : https://koel.dev/#download
- Koel Plus : https://koel.dev/plus
- Wiki communautaire : https://github.com/koel/koel/wiki
- Subsonic API : https://www.subsonic.org/pages/api.jsp
- Démo live : https://demo.koel.dev/

## 🔗 Pages Liées

- [[cat-music]] — Catégorie parente
- [[app-navidrome]] — Concurrent Go, plus léger
- [[app-ampache]] — Concurrent PHP historique
- [[app-funkwhale]] — Alternative fédérée
- [[app-gonic]] — Subsonic-compatible minimaliste
- [[app-azuracast]] — Pour le côté radio/stream broadcast
- [[app-traefik]] — Reverse proxy HTTPS
- [[app-authelia]] — SSO optionnel
- [[recettes-docker-compose]] — Templates Docker
- [[securisation-home-lab]] — Bonnes pratiques