koel/koel v5.0.0

v5.0.0 - Alexi

on GitHub

Code-named "Alexi" in memory of the late Alexi Laiho, this fifth major version of Koel comes with lots of improvements, fixes, and some breaking changes. Please follow the upgrade guide carefully.

Breaking Change: Project Structure

Though written in Laravel, the older versions of Koel didn't follow a Laravel-conventional directory structure. This decision was made to support shared-hosting environments where users have little control over the filesystem. However, considering that:

• Self-managed or semi-managed hosting solutions like Digital Ocean, Heroku, AWS, etc., are now much more popular over time, giving users near-complete system control
• An unconventional structure requires modifications and hacks that are prone to problems and make it harder to follow official best practices

starting from version 5, Koel will revert to using the original Laravel structure.

The upgrade itself is straightforward: In most cases, you'll only need to point your server's root config to the public directory instead of koel's root. For example, with Apache:

<VirtualHost *:80>
-   DocumentRoot "/var/www/koel"
+   DocumentRoot "/var/www/koel/public"

and nginx:

server {
  listen          *:80;
  server_name     koel.dev;
-  root            /var/www/koel;
+  root            /var/www/koel/public;
  index           index.php;

Breaking Change: API

Koel's API now follows OpenAPI specs. The API reference is now contained within a single YAML file which can be opened with a compatible editor such as Spotlight Studio:

This greatly reduces the maintenance effort and renders a dedicated website for the API unnecessary.

Other Changes

As a major version, Koel 5 comes with a load of changes, new features, improvements, and bug fixes:

Server Requirements

Koel is now powered by Laravel 8, which means your server needs to meet its requirements.

Search

The simple "filter" box has been completely overhauled to be a full-featured Instant Search page that supports full-text, fuzzy searching for songs, artists, and albums.

To populate the search index, run this command (you only need to run this once, as subsequent changes to the music database will be synchronized automatically):

php artisan koel:search:import

By default, the search functionality is powered by TNTSearch, which comes packaged with Koel. You can also use the Algolia driver (their free plan allows 10K records and 10K search requests)—simply by updating .env with this info:

SCOUT_DRIVER=algolia
ALGOLIA_APP_ID=<your-app-id>
ALGOLIA_SECRET=<your-secret>

Don't forget to run the import command afterward!

Other Changes

• Admins can now be created from the Users screen
• The blurry album thumbnails are now generated and served by the server instead of using the CPU-expensive CSS blur filter
• Authentication is now handled by Laravel Sanctum instead of JWT. This eliminates some nasty session expiry bugs.
• You can now like/unlike song directly from the song-list ( koel/core@bda0142)

• Change the default user Gavatar to Mysterious Person (@BrookeDot koel/core@fb7f66b)
• Fixed: Smart playlist's content not loaded after creation (koel/core@bf90f5c)
• Fixed: Drag-n-drop songs into playlists that are not loaded (koel/core@756ace3)
• Chore: Remove unnecessary ping on window activated (koel/core@dbdcc59)
• Fix: Lyrics text zooming doesn't work (koel/core@74bab8f)
• Dev: Koel now has a decent E2E test suite powered by Cypress
• Dev: Koel's CI is now powered by GitHub Actions instead of Travis
• And TONS of improvements and fixes under the hood.

To Upgrade

1. Create a full backup!

2. Run the commands:

   git pull
   git checkout v5.0.0
   git submodule update --init --recursive
   composer install
   php artisan koel:init 

3. Update your webserver config following the instruction above

4. Enjoy!

If Things Go South

Restore your backup.