Skip to content

Local Development


Koel is built with Laravel and Vue.js, and as such, it requires a PHP environment to run. There are multiple ways to set up a PHP development environment, but if you're on macOS, the easiest way is probably to use Laravel Herd. You will also need Node.js and Yarn to build the client application. For more requirements, refer to the Requirements section.

Running the Local Webserver

First, clone the repository and install the dependencies:

git clone https://github/com/koel/koel.git
cd koel
composer install
yarn install

You can now start the development server with yarn dev:

$ yarn dev

  VITE v5.1.6  ready in 1549 ms

  Local:   http://localhost:5173/
  Network: use --host to expose
  press h + enter to show help

  LARAVEL v9.52.0  plugin v1.0.2

  APP_URL: http://localhost:8000

A development version of Koel should now be available at http://localhost:8000 with full HMR support. Every change you make to the client application will be reflected in the browser immediately.

Testing, Linting, Static Analysis, etc.

# PHP-related code quality tasks
# Basically, take a look at the "scripts" section in composer.json
composer test        # Run the PHP test suite
composer cs          # Run code style checker
composer cs:fix      # Run code style fixer
composer analyze     # Run PHP static analysis

yarn build # Build a production version of the client application

# Client code quality tasks
# These commands need to be run from within the submodule (resources/assets)
yarn test            # Unit testing
yarn lint            # Lint

Koel Docs

Of course, you are welcome to contribute to Koel Docs (this documentation) as well! Koel’s documentation is built with VitePress is stored under the docs directory in the same repository as Koel. To start the VitePress instance, use the following command:

yarn docs:dev
  vitepress v1.0.0

  Local:   http://localhost:5173/
  Network: use --host to expose
  press h to show help

The documentation should now be available at http://localhost:5173.