Установка Koel на Ubuntu 18.04

Обложка: веб-интерфейс и плеер Koel

К чему готовиться

Кратко о том, что делает этот материал полезным:

Пошаговые команды для Ubuntu 18.04; сохраните их и выполняйте от имени пользователя с sudo.
Совместимость: Koel v4.x на PHP 7.2 и Node.js 10.x (из-за устаревших зависимостей фронтенда).
Рекомендации по безопасности, резервному копированию и автоматизации синхронизации медиа.

Важные термины (одной строкой):

Koel — веб-приложение для личного стриминга музыки (Laravel + Vue.js).
PHP-FPM — менеджер процессов PHP для Nginx.
Certbot — утилита для получения сертификатов Let’s Encrypt.

Предварительные требования

Сервер с Ubuntu 18.04.
Ненулевой пользователь с правами sudo (не root).
Обновите систему:

$ sudo apt update && sudo apt upgrade

Установите базовые пакеты:

$ sudo apt install ca-certificates curl unzip build-essential libpng-dev gnupg2 lsb-release ufw -y

Некоторые пакеты могут уже быть установлены.

Настройка брандмауэра (UFW)

Перед включением UFW откройте SSH, иначе потеряете доступ:

$ sudo ufw allow OpenSSH
$ sudo ufw enable
$ sudo ufw allow http
$ sudo ufw allow https
$ sudo ufw status

Ожидаемый вывод показывает порты 22, 80 и 443 разрешёнными.

Важно: если вы используете нестандартный SSH-порт, замените OpenSSH на нужный порт (например, “sudo ufw allow 2222/tcp”).

Установка Git

$ sudo apt install git -y
$ git config --global user.name "Your Name"
$ git config --global user.email "[email protected]"

Установка Node.js (версия 10.x)

Koel v4 использует старые фронтенд-библиотеки, поэтому рекомендована Node 10.x:

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
sudo apt install -y nodejs

Проверка:

$ node --version

Ожидаемый пример вывода: v10.x

Установка Yarn

$ curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
$ echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
$ sudo apt update && sudo apt install -y yarn
$ yarn --version

Установка PHP 7.2 и расширений

$ sudo apt install -y php7.2-fpm php7.2-mbstring php7.2-bcmath php7.2-xml php7.2-mysql php7.2-curl php7.2-zip
$ php --version

Убедитесь, что PHP-FPM запущен и слушает unix-сокет, указанный далее в конфигурации Nginx.

Установка MariaDB и настройка базы данных

$ sudo apt install mariadb-server
$ mysql --version
$ sudo mysql_secure_installation

Если вы хотите использовать пароль для root и сторонние приложения (phpMyAdmin и т.д.), отключите плагин аутентификации на основе unix_socket и задайте пароль:

$ sudo mysql -u root
use mysql;
update user set plugin='' where User='root';
flush privileges;
exit
$ sudo systemctl restart mariadb.service

Создайте базу и пользователя для Koel (замените yourpassword на надёжный пароль):

$ sudo mysql -u root
mysql> CREATE DATABASE koelmusic;
mysql> CREATE USER 'koeluser'@'localhost' IDENTIFIED BY 'yourpassword';
mysql> GRANT ALL PRIVILEGES ON koelmusic.* TO 'koeluser'@'localhost';
mysql> FLUSH PRIVILEGES;
mysql> exit

Установка Nginx и конфигурация для Koel

$ sudo apt install nginx
$ nginx -v

Создайте файл конфигурации:

$ sudo nano /etc/nginx/sites-available/koel.conf

Вставьте (отредактируйте server_name и root при необходимости):

server {
  listen         *:80;
  server_name    koel.example.com;
  root           /var/www/koel;
  index          index.php;

  gzip           on;
  gzip_types     text/plain text/css application/x-javascript text/xml application/xml application/xml+rss text/javascript application/json;
  gzip_comp_level  9;

  if ($request_uri !~ ^/$|index\.php|robots\.txt|(public|api)/|remote|api-docs|sw\.js) {
    return 404;
  }

  location /media/ {
    internal;

    alias       $upstream_http_x_media_root;

    access_log /var/log/nginx/koel.access.log;
    error_log  /var/log/nginx/koel.error.log;
  }

  location / {
    try_files   $uri $uri/ /index.php?$args;
  }

  location ~ \.php$ {
    try_files $uri $uri/ /index.php?$args;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass  unix:/var/run/php/php7.2-fpm.sock;
    fastcgi_index index.php;
    fastcgi_split_path_info   ^(.+\.php)(/.+)$;
    fastcgi_intercept_errors  on;
    include  fastcgi_params;
  }
}

Активируйте конфигурацию, проверьте и перезагрузите Nginx:

$ sudo ln -s /etc/nginx/sites-available/koel.conf /etc/nginx/sites-enabled/
$ sudo nginx -t
$ sudo systemctl reload nginx

Совет: если у вас множественные сайты, используйте отдельные файлы и убедитесь, что server_name совпадает с фактическим доменом.

Установка Composer

$ php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
$ php composer-setup.php
$ php -r "unlink('composer-setup.php');"
$ sudo mv composer.phar /usr/local/bin/composer
$ composer --version

Развёртывание Koel

Создайте и подготовьте документ-рут:

$ sudo mkdir -p /var/www/koel
$ cd /var/www/koel
$ sudo chown -R user:user /var/www/koel

Клонируйте репозиторий и переключитесь на релиз (пример v4.1.1):

$ git clone --recurse-submodules https://github.com/phanan/koel.git .
$ git checkout v4.1.1

Установите зависимости через Composer:

$ composer install

Инициализируйте приложение и задайте параметры (в процессе вводите тип БД mysql, имя базы, пользователя и пароль; для медиа укажите путь к папке с музыкой, например /home/user/songs):

$ php artisan koel:init

Затем верните право собственности на веб-процессы:

$ sudo chown -R www-data:www-data /var/www/koel

Откройте в браузере http://koel.example.com и выполните вход под созданным админом.

Конфигурация Koel и полезные команды

Отредактируйте файл .env для SMTP, ключей YouTube/Last.fm и других параметров:

$ sudo nano /var/www/koel/.env

Перезагрузите Nginx при необходимости.

Смена пароля администратора:

$ php artisan koel:admin:change-password

Синхронизация медиатеки вручную:

$ php artisan koel:sync

Пример вывода:

Koel syncing started.
953/953 [????????????????????????????] 100%
Completed! 944 new or updated song(s), 0 unchanged song(s), and 9 invalid file(s).

Добавьте флаг -v для подробностей. Чтобы синхронизировать автоматически — используйте cron:

$ crontab -e
# Выберите nano
0 0 * * * cd /var/www/koel && /usr/bin/php artisan koel:sync >/dev/null 2>&1

Настройка HTTPS с помощью Let’s Encrypt (Certbot)

Добавьте PPA и установите Certbot для Nginx:

$ sudo add-apt-repository ppa:certbot/certbot
$ sudo apt update
$ sudo apt install python-certbot-nginx
$ sudo certbot --nginx -d koel.example.com

Выберите перенаправление на HTTPS (рекомендуется). Сертификаты автоматически обновляются каждые 90 дней; cron/ systemd-timer обычно настраивается Certbot’ом автоматически.

Резервные копии и восстановление (минимальная методика)

Мини-методика резервного копирования:

База данных: дамп через mysqldump:

$ mysqldump -u root -p koelmusic > /root/backups/koelmusic-$(date +%F).sql

Файлы приложения и медиа:

$ rsync -a --delete /var/www/koel /root/backups/koel-www
$ rsync -a --delete /home/user/songs /root/backups/koel-songs

Храните бэкапы вне сервера (облачное хранилище, удалённый сервер).

Критерии приёмки после восстановления:

Приложение запускается и возвращает страницу логина.
Админ может войти и увидеть библиотеку.
Поток медиаконтента воспроизводится на клиенте.

Устранение неполадок — чек-лист

502 Bad Gateway: проверьте статус PHP-FPM и путь сокета (/var/run/php/php7.2-fpm.sock).

$ systemctl status php7.2-fpm

Ошибки соединения с БД: проверьте .env, пользователя и пароль; выполните пинг к MySQL:

$ mysql -u koeluser -p -e "SHOW DATABASES;"

Проблемы фронтенда (ошибки npm/yarn): убедитесь, что Node 10 установлен и выполните сборку при необходимости.
Права доступа к файлам: веб-сервер (www-data) должен иметь доступ к папке /var/www/koel и storage/ cache/.

$ sudo chown -R www-data:www-data /var/www/koel
$ sudo chmod -R 775 /var/www/koel/storage /var/www/koel/bootstrap/cache

Логи: смотрите /var/log/nginx/koel.error.log, /var/log/nginx/koel.access.log и storage/logs/laravel.log.

Когда эта инструкция может не сработать (ограничения)

Если вы используете Ubuntu более новой версии, пакеты и пути могут отличаться (PHP 7.4/8.x, Node 12+). В этом случае потребуется адаптация.
Если ваша медиатека очень большая (>50 000 треков), синхронизация и поиск могут потребовать оптимизации (SSD, индексация, рекомендовано больше памяти).
Для высоконагруженных публичных сайтов Koel лучше запускать за прокси/кэшом и с отдельным CDN.

Альтернативы и усовершенствования

Альтернативы Koel: Navidrome, Funkwhale (более активное развитие, разные функции). Выбор зависит от масштабов и функций (из коробки мобильные клиенты, федерация и т.д.).
Для автоматизированного развертывания используйте Ansible playbook или Docker-контейнеры (есть сторонние образцы для Koel).

Безопасность и рекомендации по харднингу

Ограничьте доступ к SSH по ключам, отключите логин по паролю.
Регулярно обновляйте систему и зависимости.
Используйте HTTPS всегда и HSTS, если сайт только ваш.
Настройте мониторинг диска и системы (пример: Prometheus/Node Exporter или простая настройка mail/alert при заполнении диска).

Пример минимальной настройки HSTS (в Nginx, после получения сертификата):

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

Матрица совместимости (основные компоненты)

Ubuntu 18.04 — ориентир инструкции.
PHP 7.2 — совместим с Koel v4.
Node.js 10.x — для сборки фронтенда Koel v4.
MariaDB 10.x — совместима как drop-in для MySQL.
Nginx 1.14 — стандарт для Ubuntu 18.04.

Чек-листы по ролям

Администратор сервера:

Обновить систему.
Настроить UFW, открыть порты.
Установить Docker/Ansible при необходимости.

Разработчик/DevOps:

Проверить зависимости Composer/Yarn.
Автоматизировать развёртывание.
Настроить CI/CD для релизов.

Оператор (поддержка):

Мониторить логи.
Выполнять периодические бэкапы.
Обрабатывать тикеты на доступ/аутентификацию.

Полезные команды в одной строке (шпаргалка)

Проверка статуса сервисов:

$ systemctl status nginx php7.2-fpm mariadb

Ручной дамп базы:

$ mysqldump -u koeluser -p koelmusic > /root/backups/koelmusic.sql

Синхронизация медиа:

$ php /var/www/koel/artisan koel:sync -v

Краткое резюме

Koel — удобный вариант для личного стриминга, который можно надёжно развернуть на Ubuntu 18.04, следуя шагам: подготовка сервера, установка зависимостей (Node 10, Yarn, PHP 7.2, MariaDB), настройка Nginx, развёртывание Koel, и включение HTTPS. Автоматизация синхронизации и резервного копирования обеспечит стабильную работу.

Полезные ссылки: официальная документация Koel и страницы релизов в репозитории GitHub.

Спасибо — если хотите, могу подготовить Ansible playbook или Dockerfile для автоматического развёртывания по этому сценарию.

Установка Koel на сервер Ubuntu 18.04