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

MAATRIX

Каждый релиз с новой функцией — это риск: если что-то пошло не так, откатывать приходится весь деплой, а пока идёт разбор, фича видна всем пользователям. Feature flags решают эту проблему иначе — функция уже в коде, но включена только для тех, кому нужно, и выключается одним кликом без передеплоя. Unleash — open-source платформа для управления такими флагами, и её вполне реально поднять на собственном VPS за час, не отдавая данные о своих экспериментах в облачный SaaS.

Зачем self-hosted Unleash, а не облачный сервис

У Unleash есть облачная версия (Unleash Edge / Unleash.io), но у self-hosted варианта есть конкретные практические плюсы:

• Данные остаются у вас. Информация о том, каким пользователям какие функции показываются — это по сути карта вашего продукта и экспериментов. Хранить её на чужой инфраструктуре не всегда комфортно, особенно если в компании есть требования по локализации данных.
• Нет лимитов по количеству флагов или окружений, которые часто есть в бесплатных тарифах SaaS-версий.
• Полный контроль над версией. Можно закрепиться на стабильном релизе и не зависеть от обновлений провайдера, которые иногда меняют API без предупреждения.
• Дешевле в долгосрочной перспективе, если у вас уже есть VPS под другие сервисы — Unleash не требует много ресурсов (2 GB RAM хватает с запасом для команды до 20-30 человек).

Минус один — обслуживание на вас: обновления, бэкапы БД, мониторинг. Для команды это обычно разовая настройка на пару часов и потом периодические обновления образа.

Что нужно перед установкой

Unleash состоит из двух частей: сам сервер (Node.js-приложение с админ-панелью) и база данных PostgreSQL, где хранится вся конфигурация флагов. Проще всего поднять оба компонента через Docker Compose — это самый живучий и предсказуемый способ на 2026 год, официальный образ unleashorg/unleash-server поддерживается активно.

Понадобится:

• VPS с 2 vCPU / 2-4 GB RAM — этого достаточно для старта, PostgreSQL под нагрузкой feature-flag-конфигурации не требует много ресурсов;
• Ubuntu 24.04 (или любой дистрибутив, где работает Docker);
• установленные Docker и Docker Compose plugin;
• домен или поддомен, направленный на IP сервера (для SSL через nginx) — можно обойтись и без него, но тогда админка будет доступна только по IP и порту, что менее удобно и менее безопасно.

Если Docker ещё не установлен, ставится он в три команды:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

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

docker --version
docker compose version

Структура проекта и docker-compose.yml

Создаём рабочую директорию и файл .env с секретами — так пароли не попадают в сам compose-файл и в git, если вы решите держать конфиг под версионным контролем:

mkdir -p ~/unleash && cd ~/unleash

Файл .env:

POSTGRES_USER=unleash
POSTGRES_PASSWORD=замените-на-длинный-случайный-пароль
POSTGRES_DB=unleash
UNLEASH_ADMIN_PASSWORD=замените-на-пароль-администратора

Пароли лучше сгенерировать сразу, а не придумывать на ходу:

openssl rand -base64 24

Теперь docker-compose.yml:

services:
  unleash-db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - unleash-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "unleash"]
      interval: 5s
      timeout: 5s
      retries: 10
    networks:
      - unleash-net

  unleash:
    image: unleashorg/unleash-server:latest
    restart: unless-stopped
    depends_on:
      unleash-db:
        condition: service_healthy
    ports:
      - "127.0.0.1:4242:4242"
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@unleash-db:5432/${POSTGRES_DB}
      DATABASE_SSL: "false"
      LOG_LEVEL: warn
      INIT_ADMIN_API_TOKENS: "*:*.unleash-insecure-admin-api-token"
    networks:
      - unleash-net

networks:
  unleash-net:
    driver: bridge

volumes:
  unleash-db-data:

Обратите внимание на 127.0.0.1:4242:4242 — порт пробрасывается только на loopback-интерфейс, наружу сервис не торчит напрямую. Доступ снаружи мы дадим через nginx с SSL, а не голым портом — это заметно безопаснее, особенно для админки, где хранятся API-токены.

Переменная INIT_ADMIN_API_TOKENS создаёт стартовый admin-токен для API. Значение из примера — временное, его стоит заменить на собственное после первого запуска (как — ниже, в разделе про токены).

Поднимаем:

docker compose up -d
docker compose logs -f unleash

В логах должна появиться строка вида Unleash started on http://0.0.0.0:4242. Если Unleash не может подключиться к базе — проверьте, что unleash-db действительно прошёл healthcheck (docker compose ps покажет статус healthy), и что пароль в .env совпадает в обеих секциях.

Первый вход и создание рабочего пространства

По умолчанию Unleash поднимает временный сервер напрямую на 4242 без TLS. Пока не настроен nginx, можно временно пробросить порт через SSH-туннель для первой проверки:

ssh -L 4242:localhost:4242 user@ваш-сервер

Открываем http://localhost:4242 в браузере. Стандартные логин/пароль при первом запуске — admin / unleash4all. Система сразу заставит сменить пароль — используйте тот, что заготовили в .env, или сгенерируйте новый прямо в форме.

После входа система предложит:

1. Создать первый проект (Project) — логическую группу флагов, например main для основного приложения.
2. Создать окружения (Environments) — по умолчанию есть development и production, можно добавить staging.
3. Настроить API-токены — отдельно для клиентского SDK (только чтение флагов) и для админ-операций.

Токены создаются в разделе Settings → API access. Для клиентских приложений создавайте токены с типом CLIENT и областью действия на конкретный проект — не выдавайте приложениям токены с полным admin-доступом, это лишний риск при утечке.

Публикация через nginx и SSL

Держать Unleash доступным только по SSH-туннелю неудобно для команды. Правильный вариант — обратный прокси с TLS-сертификатом. Если nginx на сервере ещё не настроен как reverse proxy, механику разворачивания подробно разбирали в статье про nginx как обратный прокси на VPS.

Конфиг для Unleash:

server {
    listen 80;
    server_name flags.вашдомен.ru;

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

Сертификат через Certbot:

sudo certbot --nginx -d flags.вашдомен.ru

После выпуска сертификата certbot сам допишет блок для порта 443 и редирект с http на https. Если сертификат не обновится автоматически через 90 дней — типовые причины и разбор разобраны в статье SSL-сертификат не обновился.

Дополнительно стоит закрыть 4242-й порт от внешнего мира на уровне файрвола, если он вдруг где-то был открыт — например, если вы тестировали без 127.0.0.1: в проброшенном порту:

sudo ufw deny 4242/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Про базовую настройку файрвола на Ubuntu подробно — в статье про настройку UFW.

Подключение SDK к приложению

Feature flags работают только тогда, когда приложение реально их спрашивает. Unleash даёт SDK для большинства популярных языков — Node.js, Python, Go, Java, .NET, PHP, Ruby. Пример для Node.js:

npm install unleash-client

const { initialize, isEnabled } = require('unleash-client');

const unleash = initialize({
  url: 'https://flags.вашдомен.ru/api/',
  appName: 'my-app',
  customHeaders: { Authorization: 'ваш-client-токен' },
});

unleash.on('synchronized', () => {
  if (isEnabled('new-checkout-flow')) {
    // включить новую логику
  } else {
    // старая логика
  }
});

SDK по умолчанию опрашивает сервер раз в 15 секунд и кэширует флаги локально — если Unleash-сервер временно недоступен, приложение продолжит работать на последнем известном состоянии флагов, а не упадёт. Это важное архитектурное решение самого Unleash: сервер не должен быть точкой отказа для продакшена.

Для фронтенда (браузерных приложений) используется отдельный компонент — Unleash Edge или Unleash Proxy — прослойка, которая не отдаёт клиенту полный список всех флагов и правил, а только вычисленный результат для конкретного пользователя. Раздавать браузеру прямой доступ к Admin API нельзя — там видна вся бизнес-логика активации фич.

Стратегии активации и таргетинг

Сила Unleash не в простом on/off, а в стратегиях — правилах, по которым флаг включается для одних пользователей и не включается для других. Из коробки доступны:

Стратегии настраиваются в UI без единой строки кода на стороне приложения — приложение просто спрашивает isEnabled('flag-name'), а всю логику "кому включать" Unleash считает сам на основе контекста (userId, IP, кастомные поля), который вы передаёте вместе с запросом.

Бэкапы и обновление

Вся конфигурация Unleash живёт в PostgreSQL, поэтому бэкапить нужно именно базу:

docker compose exec unleash-db pg_dump -U unleash unleash > unleash_backup_$(date +%Y%m%d).sql

Разумно вынести это в cron и хранить бэкапы отдельно от сервера — на S3-совместимом хранилище или через rsync на другую машину. Восстановление из бэкапа:

cat unleash_backup_20260825.sql | docker compose exec -T unleash-db psql -U unleash unleash

Обновление образа — стандартная процедура для Docker Compose:

docker compose pull unleash
docker compose up -d unleash

Перед мажорным обновлением версии (например, с 6.x на 7.x) стоит свериться с release notes на GitHub проекта — Unleash иногда меняет формат хранения стратегий между крупными версиями, и туда добавляют миграции, которые применяются автоматически при старте, но лучше держать свежий бэкап под рукой на этот случай.

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