Как установить и настроить Funkwhale на VPS

MAATRIX

SoundCloud режет плейлисты по авторским правам, Bandcamp не годится для личной фонотеки, а хранить музыку в облаке чужого сервиса — значит зависеть от чужих правил. Funkwhale закрывает эту нишу: открытый федеративный музыкальный сервер на ActivityPub, который можно поднять на своём VPS за час и получить полноценный стриминг — свой, без рекламы и без чужой модерации.

Что такое Funkwhale и зачем он на своём сервере

Funkwhale — это self-hosted аудиоплатформа, построенная на тех же принципах, что и Mastodon или PeerTube: она говорит на протоколе ActivityPub и потому «видит» другие подключённые к федивёрсу инстансы. Вы можете подписаться на канал коллеги с другого сервера Funkwhale, слушать его подкасты или альбомы прямо из своего интерфейса — без регистрации там.

Внутри это Django-приложение (бэкенд) плюс Vue-фронтенд, которые вместе умеют:

• хранить и стримить аудио (mp3, flac, ogg — форматы транскодируются на лету через ffmpeg при необходимости);
• строить библиотеку по альбомам, исполнителям, подкастам и плейлистам;
• радио на основе тегов и похожих треков;
• разграничение доступа — публичная библиотека, приватная только для вас, или федеративная только для подписчиков.

Для личного архива музыки, музыкального лейбла, подкаст-студии или небольшого сообщества это рабочая альтернатива тому, чтобы платить за облачный стриминг и мириться с его ограничениями.

Требования к серверу

Funkwhale не тяжёлый сервис, но транскодирование аудио и индексация библиотеки едят CPU и диск. Для комфортной работы:

Диск — самая гибкая переменная: для личной коллекции на пару тысяч треков хватит 20-30 ГБ, для лейбла с архивом альбомов в FLAC счёт может пойти на сотни гигабайт. Если библиотека будет расти, разумнее сразу закладывать сервер с расширяемым хранилищем или отдельным блочным диском под /srv/funkwhale/data/media.

Федерация требует настоящего домена с валидным SSL — без этого другие инстансы не смогут подписаться на вас, а вы на них. Если домен ещё не настроен, разберитесь с этим до установки — как именно, зависит от вашего DNS-провайдера, но в общем виде процесс описан в статье про Let's Encrypt SSL на VPS.

Установка через Docker Compose

Официально рекомендуемый способ — Docker Compose, он же самый предсказуемый в обслуживании. Дальше — установка на чистом Ubuntu 24.04 с уже настроенным Docker (если Docker ещё не стоит, сначала поставьте его штатным способом для вашего дистрибутива).

Создаём рабочую директорию и файл окружения:

mkdir -p /srv/funkwhale && cd /srv/funkwhale
mkdir -p data/media data/music data/staticfiles nginx/conf.d

Funkwhale поставляется с готовым docker-compose.yml, который тянут с их репозитория. Забираем актуальный шаблон и файл переменных окружения:

curl -L -o docker-compose.yml "https://dev.funkwhale.audio/funkwhale/funkwhale/-/raw/stable/deploy/docker-compose.yml"
curl -L -o .env "https://dev.funkwhale.audio/funkwhale/funkwhale/-/raw/stable/deploy/env.prod.sample"
curl -L -o nginx/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/-/raw/stable/deploy/docker.nginx.template"

Проверьте, что скачанные файлы не пустые и версия в docker-compose.yml актуальна на момент установки — проект развивается, и структура compose-файла между релизами может немного меняться.

Открываем .env и правим ключевые параметры:

# Домен, на котором будет жить инстанс
FUNKWHALE_HOSTNAME=music.example.com

# Протокол — всегда https в проде
FUNKWHALE_PROTOCOL=https

# Пароль базы данных — сгенерируйте случайный
DATABASE_PASSWORD=замените_на_случайную_строку

# Django secret key
DJANGO_SECRET_KEY=замените_на_случайную_строку_50+_символов

# Email администратора для уведомлений и Let's Encrypt
DJANGO_EMAIL_FROM=admin@example.com

# Куда складывать медиафайлы и статику
MEDIA_ROOT=/srv/funkwhale/data/media
STATIC_ROOT=/srv/funkwhale/data/staticfiles
MUSIC_DIRECTORY_PATH=/srv/funkwhale/data/music

# Ограничение загрузок (в МБ), подберите под ваши треки/альбомы
NGINX_MAX_BODY_SIZE=100

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

openssl rand -base64 45

Первый запуск и создание администратора

Запускаем стек:

docker compose up -d

Дайте контейнерам минуту-две подняться — особенно postgres и первичные миграции. Проверить состояние:

docker compose ps
docker compose logs -f api

Когда контейнер api перестал ругаться в логах и держит статус healthy (или просто стабильно работает — набор healthcheck-ов отличается между версиями), создаём суперпользователя:

docker compose run --rm api python manage.py createsuperuser --noinput \
  --username admin --email admin@example.com
docker compose run --rm api python manage.py set_password admin

Второй командой Funkwhale попросит ввести пароль интерактивно — задайте надёжный, это учётка с полным доступом к админке.

Nginx, домен и HTTPS

Compose-стек Funkwhale поднимает свой nginx-контейнер, который слушает 80/443 и работает по шаблону docker.nginx.template. Если на сервере уже есть внешний nginx или Caddy как единая точка входа для нескольких сайтов — логичнее вынести встроенный nginx Funkwhale из игры и подключить внешний реверс-прокси к внутреннему порту API/фронтенда, либо оставить всё как есть и просто прокинуть домен на публичные порты контейнера. Выбор зависит от того, сколько сервисов уже крутится на сервере.

Для одиночного инстанса проще всего довериться штатному nginx-контейнеру и получить сертификат отдельным шагом через certbot в режиме webroot или standalone:

docker run -it --rm -p 80:80 \
  -v /srv/funkwhale/nginx/letsencrypt:/etc/letsencrypt \
  certbot/certbot certonly --standalone -d music.example.com

Дальше пропишите пути к сертификату в конфиге nginx-контейнера Funkwhale (переменные NGINX_TLS_CERT и NGINX_TLS_KEY в .env или напрямую в шаблоне) и перезапустите:

docker compose up -d --force-recreate nginx

Если предпочитаете вообще не разбираться с certbot вручную, а поставить перед Funkwhale отдельный Caddy с автоматическим SSL — общий подход к такой связке разобран в статье про Let's Encrypt SSL на VPS, логика с Funkwhale аналогичная: прокси слушает 443, отдаёт запросы на внутренний порт контейнера.

Проверьте домен на публичный доступ, откройте https://music.example.com в браузере — должна открыться страница входа Funkwhale.

Загрузка музыки и настройка библиотеки

Загружать треки можно двумя путями.

Через веб-интерфейс. Зайдите под своим аккаунтом, откройте раздел «Библиотека» → «Загрузить», выберите файлы. Подходит для небольших партий и для тех, кто хочет сразу расставить теги и обложки вручную.

Через папку music/. Если у вас уже есть организованная фонотека с корректными ID3-тегами, положите файлы в data/music (или подпапки по исполнителям/альбомам) и запустите импорт из смонтированной директории:

docker compose run --rm api python manage.py import_files "Мой лейбл" \
  /music/**/*.flac --noinput

Funkwhale прочитает теги, разложит по исполнителям и альбомам, подтянет обложки, если они лежат рядом с файлами (cover.jpg) или встроены в метаданные. Транскодирование в более лёгкие форматы для стриминга происходит на лету средствами ffmpeg — убедитесь, что он доступен внутри контейнера api (в официальном образе уже включён).

Для подкастов Funkwhale умеет читать RSS-ленты напрямую — добавляете URL фида в разделе подписок, и новые эпизоды подтягиваются автоматически по расписанию.

Резервное копирование и обслуживание

Данные Funkwhale живут в трёх местах: база PostgreSQL, медиафайлы на диске (data/media, data/music) и Redis для очередей/кеша (Redis можно не бэкапить — он восстанавливаемый кеш, не источник истины).

Бэкап базы:

docker compose exec postgres pg_dump -U funkwhale funkwhale | gzip > /srv/backups/funkwhale-db-$(date +%F).sql.gz

Бэкап медиатеки — обычным rsync или tar, лучше на отдельный диск или в S3-совместимое хранилище:

rsync -a /srv/funkwhale/data/media/ /srv/backups/funkwhale-media/

Если библиотека большая, а держать полную копию локально дорого, разумно смотреть в сторону объектного хранилища как второго плеча бэкапа — принцип разобран в статье про MinIO на VPS: поднимаете S3-совместимое хранилище на отдельном сервере или диске и льёте туда архивы по расписанию.

Обновление до новой версии — штатно через смену тега образа в docker-compose.yml и:

docker compose pull
docker compose up -d
docker compose run --rm api python manage.py migrate

Перед обновлением мажорной версии обязательно смотрите changelog проекта — между релизами иногда меняются переменные окружения или структура compose-файла, и слепой pull без проверки может уронить стек.

Отдельно стоит защитить публичную форму входа и API от перебора — если на сервере ещё нет fail2ban, есть смысл поставить его сразу, инструкция в статье про установку fail2ban на VPS.

Частые вопросы