Funkwhale на Ubuntu 24.04: пошаговая установка

MAATRIX

Если вы независимый музыкант, лейбл или просто устали от того, что стриминговые площадки удаляют треки по жалобам, режут доход роялти и меняют правила монетизации без предупреждения, разумная альтернатива — держать свою площадку самостоятельно. Funkwhale — открытая платформа для хранения, стриминга и распространения музыки, построенная на протоколе ActivityPub: она одновременно работает как личный музыкальный сервер и как часть федеративной сети, где независимые поды подписываются друг на друга и обмениваются треками, альбомами и плейлистами. Ниже — пошаговая установка на чистом Ubuntu 24.04 официальным Docker-способом: от подготовки сервера до HTTPS и первого запуска.

Что такое Funkwhale и чем он отличается от Navidrome и PeerTube

Funkwhale написан на Python (Django) с фронтендом на Vue.js и решает другую задачу, чем классические медиасерверы для личной коллекции. У Navidrome сервер один, доступ — только по логину и Subsonic API, федерации нет: это удобно для личного «Spotify из своей музыки», но не для публикации и обмена с другими площадками. Funkwhale устроен иначе — каждый под может быть публичным сервисом с открытой регистрацией, отдельными артистами и альбомами, которые видны и доступны для подписки с других подов через ActivityPub, точно так же как PeerTube делает это для видео.

Ключевые возможности Funkwhale:

• Загрузка музыки библиотеками (артист → альбом → трек) с автоматическим разбором тегов и обложек.
• Публичные и приватные библиотеки с гибкими настройками видимости — для себя, для подписчиков пода или для всей федерации.
• Радио на основе тегов, похожих треков и истории прослушивания.
• Подкасты как отдельный тип контента, с собственной RSS-выдачей.
• Мобильные клиенты и совместимость с частью Subsonic-приложений через прокладку-плагин.

Для личной коллекции без цели публиковаться Navidrome проще и легче в обслуживании. Funkwhale стоит выбирать, если нужна именно публичная или полу-публичная площадка с обменом контентом внутри фединверса.

Требования к серверу и подготовка

Официально поддерживаемый способ установки — Docker и Docker Compose, и это заметно надёжнее самостоятельной сборки Python/Node-окружения вручную, поэтому дальше пойдём этим путём. Понадобятся:

• VPS с Ubuntu 24.04, минимум 1-2 vCPU. По ориентировочным цифрам из документации проекта для небольшого пода хватает 1-2 ГБ RAM, но точный запас зависит от размера библиотеки, числа одновременных слушателей и включённого транскодирования — на слабой машине под нагрузкой лучше иметь запас.
• Домен, указывающий A-записью на IP сервера — без него не получится ни HTTPS, ни нормальной федерации (ActivityPub требует стабильного публичного адреса).
• Доступ по SSH, желательно по ключу, а не по паролю.
• Открытые порты 80 и 443 в файрволе.

Обновите систему и поставьте Docker с официального репозитория:

sudo apt update && sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Проверьте, что всё встало:

docker --version
docker compose version

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

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

Создайте рабочую директорию и скачайте официальные файлы конфигурации из репозитория проекта:

sudo mkdir -p /srv/funkwhale/nginx
cd /srv/funkwhale

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

Откройте .env и заполните ключевые переменные — файл большой и хорошо прокомментирован, но обязательно поменяйте как минимум эти:

FUNKWHALE_HOSTNAME=music.example.com
FUNKWHALE_PROTOCOL=https

DJANGO_SECRET_KEY=замените-на-случайную-строку
DJANGO_ALLOWED_HOSTS=music.example.com

POSTGRES_PASSWORD=замените-на-надёжный-пароль

MEDIA_ROOT=/srv/funkwhale/data/media
STATIC_ROOT=/srv/funkwhale/data/static
MUSIC_DIRECTORY_PATH=/srv/funkwhale/data/music

Секретный ключ Django сгенерируйте локально, не оставляйте значение из примера:

openssl rand -base64 45

Создайте директории под данные с правильными правами (Funkwhale в контейнерах работает от непривилегированного пользователя):

sudo mkdir -p /srv/funkwhale/data/{media,static,music}
sudo chown -R 1000:1000 /srv/funkwhale/data

Скачайте образы, указанные в docker-compose.yml — версия образа задаётся переменной FUNKWHALE_VERSION в .env, по умолчанию там актуальный стабильный релиз на момент выхода примера, но стоит свериться с текущим значением в документации проекта перед запуском:

sudo docker compose pull

Инициализация базы данных и первый запуск

Перед первым стартом нужно накатить миграции базы данных и создать администратора. Это делается разовыми запусками контейнера api без поднятия всего стека:

sudo docker compose run --rm api python manage.py migrate
sudo docker compose run --rm api python manage.py createsuperuser

При создании суперпользователя укажите email и пароль — логин для веб-интерфейса и API. После этого поднимайте весь стек:

sudo docker compose up -d
sudo docker compose ps

В выводе ps все сервисы (postgres, redis, api, celeryworker, nginx и другие, перечисленные в docker-compose.yml) должны быть в состоянии running или healthy. Если какой-то контейнер перезапускается в цикле, смотрите логи конкретного сервиса:

sudo docker compose logs -f api
sudo docker compose logs -f celeryworker

Чаще всего на этом шаге всплывают опечатки в .env — неверный пароль к Postgres или несовпадающий FUNKWHALE_HOSTNAME.

Nginx как reverse proxy и HTTPS

Контейнер nginx из стека Funkwhale слушает только на локальном интерфейсе — какой именно IP и порт, задаёт переменная NGINX_PORT в .env (в примере обычно это порт на 127.0.0.1, значение стоит проверить в скачанном файле перед следующим шагом). Наружу трафик отдаёт уже системный Nginx с SSL — то есть перед контейнерным Nginx нужен ещё один, обычный reverse proxy на хосте.

Поставьте Nginx на хост и создайте конфиг /etc/nginx/sites-available/funkwhale, подставив реальный порт из .env:

server {
    listen 80;
    server_name music.example.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        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;

        client_max_body_size 100M;
        proxy_read_timeout 300s;
    }
}

Активируйте сайт и получите сертификат через Let's Encrypt:

sudo ln -s /etc/nginx/sites-available/funkwhale /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d music.example.com

Certbot допишет listen 443 ssl и редирект с HTTP на HTTPS. Не забудьте открыть нужные порты в UFW, если он включён:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

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

Федерация: подписка на другие поды и настройка приватности

Главное отличие Funkwhale от обычного медиасервера — фединверс-идентичность вида @ваш_логин@music.example.com, по которой ваш аккаунт находят и на него подписываются с других подов Funkwhale, а в некоторых случаях — и с других ActivityPub-платформ, поддерживающих аудио.

Настройки федерации и модерации живут в админке (/manage/federation для списка подов и /manage/library для контента):

• Видимость библиотеки задаётся при загрузке контента: только себе, подписчикам, всем на этом поде или всей федерации — управляется отдельно для каждого альбома.
• Список известных подов пополняется автоматически, когда кто-то с вашего пода подписывается на внешний аккаунт, либо вручную через админку.
• Блокировка подов и доменов — если не хотите федерироваться с конкретным сервером, добавьте его в чёрный список инстанса.
• Открытая или закрытая регистрация переключается переменной FUNKWHALE_REGISTRATION в .env — по умолчанию новые пользователи не смогут зарегистрироваться сами, пока вы явно это не разрешите.

Загрузка музыки — через веб-интерфейс (раздел «Загрузки» в библиотеке) с перетаскиванием файлов, или пакетно через management-команду import_files внутри контейнера api, если у вас уже большая коллекция на диске и заливать её по одному треку через браузер неудобно.

Обновления, бэкапы и обслуживание

Обновление стека — стандартный цикл Docker Compose с обязательными миграциями после смены версии:

cd /srv/funkwhale
sudo docker compose pull
sudo docker compose run --rm api python manage.py migrate
sudo docker compose up -d

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

Бэкапить нужно две вещи отдельно: базу PostgreSQL и файлы медиатеки.

# дамп базы
sudo docker compose exec postgres pg_dump -U funkwhale funkwhale > funkwhale-$(date +%F).sql

# файлы (обложки, загруженные треки, транскодированные версии)
sudo tar -czf funkwhale-media-$(date +%F).tar.gz /srv/funkwhale/data/media /srv/funkwhale/data/music

Регулярный бэкап стоит вынести в cron и хранить копии вне сервера — если под федерирован и на него подписаны внешние пользователи, потеря базы означает не только ваши данные, но и разрыв всех подписок и федеративных связей, которые придётся выстраивать заново.

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