A Docker image with only the bare essentials needed to run Koel. It includes Apache and a PHP runtime with required extensions.
Note
Instructions on master may not match the version you're running.
For version-specific documentation, switch to the corresponding tag (e.g., v8.3.1).
Important
This image does not include a database. A separate database container (MariaDB/MySQL or PostgreSQL) is required. Ready-to-use Docker Compose configurations are provided — see Quick Start.
Docker Compose is the easiest way to get started. Clone this repository, pick a compose file for your preferred database, update the passwords, and run:
# For MariaDB/MySQL docker compose -f docker-compose.mysql.yml up -d # For PostgreSQL docker compose -f docker-compose.postgres.yml up -d
This command handles migrations, generates the APP_KEY, creates the default admin account, and performs other first-run tasks. It runs automatically when the container starts (disable with SKIP_INIT=true), but you can also run it manually:
docker exec --user www-data -it <koel_container> php artisan koel:init --no-assets
The --no-assets flag skips building front-end assets, as they are already included in the image.
The first koel:init creates a default admin account:
- Email:
[email protected] - Password:
KoelIsCool
Change this password immediately:
docker exec -it <koel_container> php artisan koel:admin:change-password
You can also update the email and password via the web interface after logging in.
APP_KEY is generated during koel:init and is essential for encryption. If the container is recreated without persisting this key, you'll need to re-initialize. Two ways to preserve it:
Option 1: Bind-mount the .env file
touch .env
docker run -d --name koel \
-p 80:80 \
--mount type=bind,source="$(pwd)"/.env,target=/var/www/html/.env \
phanan/koelOption 2: Pass APP_KEY as an environment variable
# Generate a key docker run -it --rm phanan/koel php artisan key:generate --show # Pass it to your container docker run -d --name koel \ -p 80:80 \ -e APP_KEY=<your_app_key> \ phanan/koel
Important
This list is not exhaustive. See .env.example for a complete reference.
| Variable | Description |
|---|---|
SKIP_INIT |
If set, prevents the container from running koel:init on startup. |
DB_CONNECTION |
mysql, pgsql, sqlsrv, or sqlite-persistent. |
DB_HOST |
Hostname of the database container. Must be on the same Docker network. |
DB_USERNAME |
Database username (default: koel). |
DB_PASSWORD |
Database password. Must match the database container's configuration. |
DB_DATABASE |
Database name (default: koel). |
APP_KEY |
Base64-encoded key generated by koel:init or key:generate. |
FORCE_HTTPS |
Set to true if using an HTTPS reverse proxy in front of Koel. |
MEMORY_LIMIT |
Memory limit in MB for the scanning process. |
LASTFM_API_KEY, LASTFM_API_SECRET |
Enables Last.fm integration. |
SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET |
Enables Spotify integration. |
OPTIMIZE_CONFIG |
Preloads and optimizes configuration. Changes require a container restart. |
Koel's init script installs a scheduler that scans /music daily. To trigger a manual scan:
docker exec --user www-data <koel_container> php artisan koel:sync
| Path | Description |
|---|---|
/music |
Your music library. |
/var/www/html/storage/app/public/images |
Uploaded images (album art, user avatars, etc.). |
/var/www/html/storage/search-indexes |
Search indexes for songs, albums, and artists. |
Only port 80 (HTTP) is exposed. Set up a reverse proxy for HTTPS support.
The container's working directory is /var/www/html (Apache's document root). All Koel files reside here.
The Makefile contains several helper commands for local development. For example, to build and start the dev stack:
make start
If you run into any issues, check the Koel documentation first. If you encounter a bug in Koel itself, open an issue in the Koel repository. This repo's issues are reserved for Docker-related questions and problems.