Руководство по установке Koel на VPS: Современная альтернатива Navidrome

Если вы искали стильную, современную и быструю альтернативу Navidrome для стриминга собственной музыки, Koel — это именно то, что вам нужно. В отличие от многих других решений, Koel выглядит как полноценный Spotify или Apple Music: интерфейс написан на Vue.js, серверная часть на Laravel, а поддержка темной темы и визуализаторов делает использование настоящим удовольствием.

В этом руководстве мы пошагово разберем установку Koel на чистый VPS под управлением Ubuntu 24.04 LTS. Мы будем использовать официальный Standalone Binary (FrankenPHP).

Почему именно этот метод?

  • Zero-Setup: Не нужно вручную устанавливать PHP, Composer, Node.js или настраивать базы данных.
  • Экономия ресурсов: Используется встроенная SQLite, что идеально для личных медиатек и экономит оперативную память (не нужно поднимать контейнер с MySQL).
  • Все-в-одном: FrankenPHP уже включает в себя веб-сервер Caddy и PHP-рантайм.

Шаг 1: Подготовка сервера

Для начала обновим систему и установим базовые утилиты, которые понадобятся для скачивания и распаковки. Подключитесь к вашему VPS по SSH под пользователем root.

# Обновление списков пакетов и самой системы
apt update && apt upgrade -y

# Установка необходимых утилит
apt install -y curl wget jq tar ufw

Настройка базовой безопасности (Фаервол):
Сразу откроем порт SSH, чтобы не потерять доступ к серверу, и порт 8000, на котором будет работать Koel.

ufw allow OpenSSH
ufw allow 8000/tcp
ufw enable
ufw status

Шаг 2: Создание изолированного пользователя

В целях безопасности никогда не запускайте веб-приложения от имени root. Создадим отдельного системного пользователя koel с домашней директорией в /opt/koel.

useradd -r -s /bin/false -m -d /opt/koel koel

Шаг 3: Загрузка и установка Koel (FrankenPHP)

Мы будем скачивать последнюю версию напрямую из GitHub-репозитория koel/franken.

💡 Pro-Tip: Мы будем скачивать архив во временную папку /tmp, чтобы избежать классической ошибки Linux, когда распакованный архив случайно вкладывается внутрь уже созданной домашней папки пользователя.

# Переходим во временную директорию
cd /tmp

# Автоматически находим ссылку на последний релиз для Linux x86_64
DOWNLOAD_URL=$(curl -s https://api.github.com/repos/koel/franken/releases/latest | jq -r '.assets[] | select(.name | contains("linux-x86_64.tar.gz")) | .browser_download_url')

# Скачиваем архив
wget -O koel-franken.tar.gz $DOWNLOAD_URL

# Распаковываем
tar -xzf koel-franken.tar.gz

# Копируем ВСЕ файлы (включая скрытые) в домашнюю папку пользователя koel
cp -a /tmp/koel-franken-*linux-x86_64/. /opt/koel/

# Удаляем временные файлы
rm -rf /tmp/koel-franken-*linux-x86_64 /tmp/koel-franken.tar.gz

# Назначаем правильного владельца
chown -R koel:koel /opt/koel

Создадим папку для вашей будущей музыкальной коллекции:

mkdir -p /opt/koel/music
chown -R koel:koel /opt/koel/music

Шаг 4: Первый запуск и инициализация базы данных

При первом запуске Koel автоматически создаст скрытую папку .koel внутри домашней директории (/opt/koel/.koel/). Там будут храниться конфигурационный файл .env и база данных SQLite.

Запустим сервер в тестовом режиме:

cd /opt/koel
sudo -u koel ./koel php-server --listen :8000

Что произойдет в консоли:

  1. Пройдет инициализация (создание таблиц в БД).
  2. В логах появятся дефолтные учетные данные администратора:
    Email: admin@koel.dev
    Пароль: KoelIsCool
  3. Запустится веб-сервер Caddy.

Откройте браузер и перейдите по адресу: http://IP_ВАШЕГО_VPS:8000.
Войдите в систему, используя данные выше, и сразу же смените пароль в настройках профиля (Profile).

После успешного входа вернитесь в консоль и нажмите Ctrl+C, чтобы остановить тестовый сервер.

Шаг 5: Настройка автозапуска (Systemd)

Чтобы Koel запускался сам после перезагрузки VPS и работал в фоне, создадим системную службу.

nano /etc/systemd/system/koel.service

Вставьте следующий конфигурационный файл:

[Unit]
Description=Koel Music Streamer (FrankenPHP)
After=network.target

[Service]
Type=simple
User=koel
Group=koel
WorkingDirectory=/opt/koel
ExecStart=/opt/koel/koel php-server --listen :8000
Restart=on-failure
RestartSec=5s
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

Сохраните: Ctrl+O, Enter, Ctrl+X.

Активируйте и запустите службу:

systemctl daemon-reload
systemctl enable --now koel
systemctl status koel

(Статус должен быть active (running). Нажмите q, чтобы выйти из просмотра статуса).

Шаг 6: Добавление музыки (Основной способ: через веб-интерфейс)

Огромный плюс Koel в том, что вам не нужно лезть в консоль или использовать SFTP-клиенты для пополнения коллекции. Всё можно делать прямо в браузере!

6.1. Настройка Media Path (Обязательный первый шаг)

Прежде чем загружать файлы, нужно указать Koel, где на сервере хранится ваша музыка.

  1. В веб-интерфейсе Koel перейдите в Manage → Settings.
  2. Найдите поле Media Path.
  3. Впишите абсолютный путь к созданной нами папке: /opt/koel/music
  4. Нажмите кнопку Save & Scan.

Koel запомнит этот путь и сразу же просканирует папку (пока она пустая, это займет секунду).

6.2. Загрузка музыки через кнопку Upload

Теперь, когда путь задан, вы можете загружать треки напрямую:

  1. В боковом меню выберите Upload.
  2. Просто перетащите (Drag-and-Drop) ваши музыкальные файлы или целые папки с компьютера прямо в окно браузера.
  3. Koel автоматически загрузит их на сервер и сохранит в подпапку /opt/koel/music/__KOEL__UPLOADS__/.
  4. Музыка мгновенно появится в вашей библиотеке!

💡 Совет: Koel автоматически определяет дубликаты по хешу файлов. Если вы загрузите трек, который уже есть в библиотеке, система предупредит вас и предложит отменить загрузку.

6.3. Альтернативный способ: SFTP + Консоль (Для огромных коллекций)

Если у вас уже есть терабайты музыки на внешнем диске, загружать их через браузер неудобно. В этом случае:

  1. Скопируйте музыку в /opt/koel/music через SFTP (FileZilla, WinSCP).
  2. Зайдите в веб-интерфейс Koel → Manage → Settings и просто нажмите кнопку Scan.
  3. Либо запустите сканирование через консоль: sudo -u koel /opt/koel/koel php-cli artisan koel:scan

Шаг 7: Интеграции (Обложки, Биографии и Тексты)

По умолчанию Koel использует MusicBrainz и Wikipedia для получения информации об альбомах. Однако для получения качественных фотографий артистов и биографий рекомендуется подключить Last.fm или Spotify.

Конфигурация находится в файле: /opt/koel/.koel/.env

Подключение Last.fm (Рекомендуется)

  1. Зарегистрируйте API-аккаунт на Last.fm API.
  2. Откройте конфиг: nano /opt/koel/.koel/.env
  3. Добавьте ваши ключи: LASTFM_API_KEY=ваш_key LASTFM_API_SECRET=ваш_secret
  4. Перезапустите службу: systemctl restart koel
  5. Перейдите в Profile & Preferences в правом нижнем углу и затем в закладку Integrations и подключите Last.fm

Подключение Spotify (Для идеальных картинок)

⚠️ Внимание: С 2026 года для создания новых Developer App в Spotify требуется наличие Premium-подписки. Если её нет, используйте Last.fm.

Если подписка есть, получите Client ID и Client Secret в Spotify Developer Dashboard и добавьте их в .env:

SPOTIFY_CLIENT_ID=ваш_id
SPOTIFY_CLIENT_SECRET=ваш_secret

🌟 Опциональный шаг: Nginx Reverse Proxy и SSL (Let’s Encrypt)

Сейчас ваш сервер доступен по адресу http://IP:8000. Для повседневного использования (особенно с мобильных устройств) лучше скрыть порт и настроить HTTPS.

1. Установите Nginx и Certbot:

apt install -y nginx certbot python3-certbot-nginx

2. Создайте конфиг Nginx:

nano /etc/nginx/sites-available/koel

(Замените music.biggratz.ru на ваш поддомен, направив его A-запись на IP сервера в панели DNS).

server {
    listen 80;
    server_name music.biggratz.ru; # Ваш домен

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Важно для стриминга больших аудиофайлов
        proxy_buffering off;
        proxy_request_buffering off;
        client_max_body_size 100M;
    }
}

3. Активируйте сайт и получите SSL-сертификат:

ln -s /etc/nginx/sites-available/koel /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

# Получение сертификата Let's Encrypt
certbot --nginx -d music.biggratz.ru

Теперь ваш личный музыкальный сервер доступен по красивому адресу https://music.biggratz.ru с зеленым замочком безопасности, а автопродление сертификатов настроится автоматически!

Итог: Вы получили мощный, красивый и независимый музыкальный стриминговый сервис, который полностью принадлежит вам. Загружайте музыку прямо из браузера, настраивайте интеграции и наслаждайтесь прослушиванием! 🎧