Stream Your Own Music Library with Koel

// Before you start

What you need

A Linux server or VPS (Ubuntu 22.04 recommended) with SSH access
PHP 8.2 or higher installed on the server
MySQL or PostgreSQL database created and ready
Composer (PHP package manager) installed
Node.js 20+ and npm installed
A folder of music files (MP3, FLAC, AAC, etc.) already on the server

Step 1 of 6

Download Koel onto your server

3 min

This command pulls the latest stable Koel release directly from GitHub and places it in a folder called 'koel' in your current directory. You only need to be logged into your server via SSH.

Terminal · mac

$ git clone https://github.com/koel/koel.git && cd koel && git checkout $(git describe --tags $(git rev-list --tags --max-count=1))

What you should see

You should see git cloning output, then land on the latest version tag (e.g. v7.x.x).

This might happen

git not found

Run: sudo apt install git -y — then retry the command.

Step 2 of 6

Install PHP and JavaScript dependencies

5 min

Koel is built on Laravel (PHP) and Vue (JavaScript). This step downloads all the libraries both sides need. Composer handles PHP packages; npm handles the JavaScript ones. Run both commands from inside the koel folder.

Terminal · mac

$ composer install --no-dev && npm install && npm run build

What you should see

Composer prints a list of installed packages. npm prints build output ending with something like 'built in Xs'. No red error lines.

This might happen

npm run build fails with memory errors

Run: NODE_OPTIONS=--max-old-space-size=2048 npm run build — this gives Node more RAM.

Step 3 of 6

Create and configure your .env file

5 min

Koel reads all its settings from a file called .env. You copy the example file, then open it and fill in your database credentials and the path to your music folder. Use any text editor — nano is the easiest on a server.

Terminal · mac

$ cp .env.example .env && nano .env

What you should see

The .env file opens in nano. Find DB_CONNECTION, DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD and fill in your database details. Find MEDIA_PATH and set it to your music folder, e.g. /home/youruser/music. Save with Ctrl+O, exit with Ctrl+X.

This might happen

You are not sure what to put for DB_HOST

If the database is on the same server, use 127.0.0.1. If you are using a managed database service, use the hostname they gave you.

Step 4 of 6

Run the Koel installer

3 min

This single command generates a secret app key, runs all database migrations (creates the tables Koel needs), and sets up the admin account. It will prompt you to create an admin email and password — write them down.

Terminal · mac

$ php artisan koel:init

What you should see

You will see migration confirmations, then a prompt asking for an admin email and password. After entering them, you should see 'Koel is ready to rock!'

This might happen

SQLSTATE error about access denied

Your database credentials in .env are wrong. Double-check DB_USERNAME and DB_PASSWORD match what your database server expects.

Step 5 of 6

Scan your music library

2–20 min depending on library size

This command tells Koel to walk through the MEDIA_PATH folder you set earlier, read every audio file it finds, and add them to the database. It only needs to run once — after that, Koel watches for changes automatically.

Terminal · mac

$ php artisan koel:sync

What you should see

A progress bar appears showing files being scanned. At the end you see a summary like 'Scanned X songs, Y new, Z unchanged'.

This might happen

0 songs found

Check that MEDIA_PATH in .env points to the exact folder containing your audio files and that the PHP process has read permission on that folder (run: chmod -R 755 /your/music/path).

Step 6 of 6

Serve Koel and open it in your browser

2 min

For a quick test, PHP's built-in server is enough. For a permanent setup you would configure Nginx or Apache — see Koel's official docs for that. The command below starts a temporary server on port 8000 so you can log in right now.

Terminal · mac

$ php artisan serve --host=0.0.0.0 --port=8000

What you should see

Terminal shows: 'Starting Laravel development server: http://0.0.0.0:8000'. Open http://YOUR_SERVER_IP:8000 in a browser and log in with the admin credentials you created.

This might happen

Browser cannot connect

Your server firewall may be blocking port 8000. Run: sudo ufw allow 8000 — then try again. For production, set up Nginx instead of using artisan serve.

// Status

cooked. baked. worked.

A working private music streaming web app running on your own server. You can log in from any browser, browse your scanned library, create playlists, and stream your music — no subscription required.

// the honest bit

The honest part

The artisan serve method is for testing only — it stops when you close SSH. For a real always-on setup you must configure Nginx or Apache with PHP-FPM, which requires editing config files. Koel's official documentation at docs.koel.dev covers this in detail. The AI assistant feature requires an OpenAI API key set in .env. Koel Plus features (multi-user libraries, SSO, cloud storage) require a paid license.