mirror of
https://github.com/koel/koel
synced 2024-12-18 16:44:03 +00:00
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
|
# Getting Started
|
|||
|
|
|
|||
|
|
## Requirements
|
|||
|
|
|
|||
|
|
Koel consists of two parts: the server and the client. The server is a Laravel application acting as the API, and the client is a Vue.js application responsible for the user interface.
|
|||
|
|
The requirements for each part are as follows:
|
|||
|
|
|
|||
|
|
### Server
|
|||
|
|
|
|||
|
|
* [All requirements by Laravel](https://laravel.com/docs/10.x/deployment#server-requirements) – PHP >= 8.1 with required extensions
|
|||
|
|
* Any database supported by Laravel – MySQL, MariaDB, PostgreSQL, or SQLite
|
|||
|
|
* If you're [building Koel from source](#building-from-source), make sure to have [Composer](https://getcomposer.org/), Git, and Node.js >= 14 with [Yarn](https://yarnpkg.com).
|
|||
|
|
|
|||
|
|
### Client
|
|||
|
|
|
|||
|
|
* Koel has been tested on Chrome 47, Firefox 42, Safari 8, Opera 34, and Edge, but having the latest version is always recommended.
|
|||
|
|
|
|||
|
|
## Installation
|
|||
|
|
|
|||
|
|
There are three methods to install and start using Koel:
|
|||
|
|
|
|||
|
|
### Using a Pre-Compiled Archive
|
|||
|
|
|
|||
|
|
Koel supports installing from a pre-compiled archive, which eliminates the need of manually compiling the front-end assets.
|
|||
|
|
|
|||
|
|
First, go to the [Releases page](https://github.com/koel/koel/releases) on GitHub, download either the `.tar.gz` or `.zip` file found under "Assets," and unzip it into the destination web root directory. From there, run the two following commands:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
php artisan koel:init --no-assets
|
|||
|
|
|
|||
|
|
# Follow the wizard to populate necessary configurations
|
|||
|
|
|
|||
|
|
php artisan serve
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Building from Source
|
|||
|
|
|
|||
|
|
From your console, run the following commands:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd <KOEL_ROOT_DIR>
|
|||
|
|
git clone https://github.com/koel/koel.git .
|
|||
|
|
git checkout latest # Check out the latest version at https://github.com/koel/koel/releases
|
|||
|
|
composer install
|
|||
|
|
php artisan koel:init
|
|||
|
|
|
|||
|
|
# Follow the wizard to populate necessary configurations
|
|||
|
|
|
|||
|
|
php artisan serve
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
In both cases, you should now be able to visit http://localhost:8000 in your browser and start using Koel.
|
|||
|
|
|
|||
|
|
::: warning Use a proper webserver
|
|||
|
|
http://localhost:8000 is only the _development_ server for Koel (or rather, Laravel).
|
|||
|
|
For optimal performance, you'll want to set up a production server (Apache, nginx, Caddy etc.) and point it to the `public` directory of Koel.
|
|||
|
|
Koel provides a sample configuration for nginx in `nginx.conf.example`,
|
|||
|
|
but the process shouldn't be any different from that of a standard PHP application.
|
|||
|
|
:::
|
|||
|
|
|
|||
|
|
### Using Docker
|
|||
|
|
|
|||
|
|
Koel has an official Docker image: [koel/docker](https://github.com/koel/docker). Please refer to the repository for detailed instructions and issue reporting.
|
|||
|
|
|
|||
|
|
## Configuration
|
|||
|
|
|
|||
|
|
Koel’s configuration is stored in the `.env` file at the root of the project, which is created during the installation process
|
|||
|
|
by copying the `.env.example` file and filling it with sensible values.
|
|||
|
|
You can always modify the values to suit your environment.
|
|||
|
|
|
|||
|
|
### Configure a Mailer
|
|||
|
|
|
|||
|
|
Though Koel can work without a mailer, certain features like "forgot password" and user invitation require a mailer to be set up.
|
|||
|
|
To determine if that's the case, Koel relies on the `MAIL_MAILER` value in the `.env` file.
|
|||
|
|
Any non-empty value other than `log` or `array` is considered a proper mailer.
|
|||
|
|
As such, if you don't need email-required features, you can simply set `MAIL_MAILER` to `log` or `array` and leave the rest of the mailer-related values empty,
|
|||
|
|
and Koel will know to remove/disable these features.
|
|||
|
|
|
|||
|
|
## Upgrade
|
|||
|
|
|
|||
|
|
:::danger Backup your database
|
|||
|
|
Remember to always back up your database before upgrading.
|
|||
|
|
:::
|
|||
|
|
Check out [Releases](https://github.com/koel/koel/releases) for upgrade guides corresponding to your Koel version and installation method.
|
|||
|
|
|
|||
|
|
## Downgrade
|
|||
|
|
|
|||
|
|
Koel does not provide a built-in downgrade mechanism.
|
|||
|
|
In the unlikely event that you need to downgrade, simply restore your database from a backup and follow the installation guide for the version you want to downgrade to.
|