Where Does Koel Store Config and Its Database?
Where Koel keeps its .env config, SQLite database, and media library paths on a server install.
Last updated
Koel centers on three things: a .env file with secrets and options at the install root, a database (SQLite file or MySQL) with users and library indexes, and your media folders scanned read only.
Migrations move the first two plus a note of media paths. The common failure is restoring the database without the matching .env app key, which invalidates sessions and encryption. Keep both together and rescans stay incremental instead of full. Smart playlists rebuild from rules on scan.
Where Koel stores this, by platform
<install>/.env + database/
.env plus database/database.sqlite here in default installs. Back both up together; the key inside .env decrypts what the database holds. Docker maps the same files under a volume, so check the compose mounts.
Frequently asked questions
how do i migrate koel to a new server
Copy the .env file, the database (database.sqlite or a MySQL dump), and note the media paths to the new box, keeping versions matched. Run koel:init on the fresh install before restoring. Cover art caches rebuild with a scan, so they can stay behind.
where is the koel env file
In .env at the install root (database credentials, app key, mail, streaming options). Never commit it with secrets intact. The installer writes the first copy; upgrades preserve it but may add new keys to merge.
does koel need a persistent volume
Yes through a persistent volume holding .env, the database, and Covers cache. The image carries code only. Media folders mount separately and read only is fine, since Koel scans without modifying your files.
Notice an outdated path? Let us know.