FlipFlag на сервере вашей компании

FlipFlag self-host размещает интерфейс, API и PostgreSQL в инфраструктуре заказчика. Одна установка обслуживает одну организацию с проектами, окружениями и пользователями. SDK обращаются к адресу вашей установки. Для Kubernetes используйте отдельную инструкцию.

Что получает заказчик

Полный комплект 0.3.0 для Linux AMD64 или ARM64 содержит установщик, Compose, Helm chart и готовые образы API, интерфейса, PostgreSQL и HTTPS proxy. Go, Node.js, исходники приложения и доступ к Docker registry для установки комплекта не нужны. Лицензия выдаётся поставщиком отдельно после подтверждения оплаты по договору.

Браузер администратора ─┐
                       ├─ HTTPS → ваш FlipFlag → API → PostgreSQL
SDK вашего приложения ─┘                 │
                                         └─ исходящий HTTPS → лицензирование FlipFlag
                                            только в онлайн-режиме

Бизнес-данные остаются у заказчика. Онлайн-проверка передаёт ключ активации и ID установки; содержимое БД, флаги и пользователи в этот запрос не входят. В изолированной сети используйте подписанный файл лицензии: обращения к поставщику не нужны.

1. Подготовьте сервер

Требование	Что проверить
Платформа	Linux, архитектура Docker-сервера AMD64 или ARM64
Docker	Работающий Docker Engine и доступ текущего пользователя к Docker
Compose	Plugin версии 2.24.4 или новее
Утилиты	Bash, curl, OpenSSL; доступный интерактивный терминал
Ресурсы для первого пилота	Начните с 2 vCPU, 4 ГБ RAM и SSD; ёмкость проверяется вашей нагрузкой
Онлайн-установка	Исходящий HTTPS к flipflag.ru для загрузки и лицензирования
Доступ пользователей	Свободный выбранный веб-порт; для автоматического HTTPS — DNS и TCP 80/443

Проверка:

docker info
docker compose version
bash --version
curl --version
openssl version

Установщик проверяет зависимости, но не устанавливает Docker, не меняет DNS и firewall. Docker API даёт доступ к секретам контейнеров: предоставляйте его только администраторам.

2. Запустите одну команду

Из каталога, в котором хотите хранить установку:

curl -fsSL https://flipflag.ru/selfhost/downloads/install.sh | bash

Загрузчик определит архитектуру Docker-сервера, скачает архив по HTTPS, проверит SHA-256 и запустит мастер. Файлы появятся в ./flipflag-selfhost. Для другого каталога:

curl -fsSL https://flipflag.ru/selfhost/downloads/install.sh \
  | FLIPFLAG_INSTALL_DIR=/opt/flipflag bash

Текущий пользователь должен иметь право записи в выбранный каталог. Для предварительного просмотра загрузчика сохраните его отдельно:

curl -fsSLo /tmp/flipflag-download.sh https://flipflag.ru/selfhost/downloads/install.sh
less /tmp/flipflag-download.sh
bash /tmp/flipflag-download.sh

SHA-256 проверяет целостность архива; доверие к загрузчику и checksum обеспечивается HTTPS.

3. Ответьте на вопросы мастера

Пример параметров — вводите их по приглашениям мастера:

Поле	Пример
Компания	Example Corp
Веб-порт	8088
Домен	Оставьте пустым для IP или введите flags.example.com
Режим доступа	IP / автоматический HTTPS / корпоративный proxy
Email администратора	admin@example.com
Имя администратора	Administrator
Пароль	Свой пароль, 12–72 байта; ввод скрыт и повторяется
Лицензия	Онлайн-ключ или путь к подписанному файлу

Мастер создаст пароли БД и JWT-секрет, загрузит готовые образы, запустит сервисы, активирует лицензию и создаст первого администратора. Он дождётся health checks и проверит вход. Адрес входа появится в конце установки. Пароль администратора не сохраняется в настройках мастера и не передаётся аргументом процесса.

Вариант A: IP и порт

Например: http://192.0.2.10:8088. Мастер предложит IP сервера и позволит исправить его. Веб-порт публикуется на интерфейсах сервера; сетевой доступ разрешается вашим firewall. HTTP подходит для доверенной тестовой сети. Для доступа через интернет подготовьте HTTPS.

Вариант B: домен и автоматический HTTPS

Заранее направьте DNS A/AAAA домена на сервер. TCP 80/443 должны быть свободны и доступны снаружи; ошибочная AAAA-запись также может помешать выдаче сертификата. Выберите автоматический HTTPS. Caddy получит сертификат и будет обновлять его. Пользователи откроют https://flags.example.com, внутренний веб-порт останется на loopback. Публичный ACME требует сетевой доступ к центру сертификации и доступ центра к серверу.

Вариант C: корпоративный reverse proxy

Выберите соответствующий режим. Установка покажет upstream, например http://127.0.0.1:8088. Направьте весь внешний сайт на него, включая /v1/ и /config.js. Пример для nginx на том же хосте, после получения корпоративного сертификата:

server {
    listen 443 ssl;
    server_name flags.example.com;
    ssl_certificate     /etc/nginx/tls/fullchain.pem;
    ssl_certificate_key /etc/nginx/tls/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Если proxy в другом контейнере/на другом узле, его 127.0.0.1 не является адресом хоста FlipFlag. Подготовьте маршрут через общую сеть или приватный адрес; измените BIND_ADDRESS и ограничьте доступ сетевыми правилами. Внешний домен заработает после настройки proxy. API и PostgreSQL отдельно наружу не публикуются.

4. Активируйте лицензию

Онлайн

Вставьте полученный от поставщика ключ в скрытое поле мастера. При первой активации он привязывается к ID установки. Сервер получает подписанный допуск, проверяет его локально и запрашивает обновление при запуске и затем раз в час.

Допуск действует не более 72 часов с выдачи и никогда не дольше оплаченного срока. 72 часа — предел ранее выданного допуска при потере связи, а не дополнительные дни подписки. При обычном продлении поставщик подтверждает оплату; менять ключ не требуется.

Закрытая сеть и офлайн-файл

На машине с интернетом скачайте комплект и checksum. Пример для AMD64:

curl -fSLO https://flipflag.ru/selfhost/downloads/flipflag-selfhost-0.3.0-linux-amd64.tar.gz
curl -fSLO https://flipflag.ru/selfhost/downloads/flipflag-selfhost-0.3.0-linux-amd64.tar.gz.sha256
sha256sum -c flipflag-selfhost-0.3.0-linux-amd64.tar.gz.sha256

Для ARM64 замените amd64 на arm64 в обоих именах. Перенесите оба файла в закрытую сеть, повторите проверку, затем:

tar -xzf flipflag-selfhost-0.3.0-linux-amd64.tar.gz
cd flipflag-selfhost-0.3.0-linux-amd64
./install.sh

Выберите активацию файлом. Мастер покажет ID установки: передайте его поставщику, получите подписанный файл и укажите путь к нему. Интернет и доступ к registry не требуются. Файл действует до оплаченной даты; для следующего периода получите новый файл для того же ID. Для HTTPS в закрытой сети используйте корпоративный proxy и сертификат.

5. Проверьте работу и подключите приложение

Все дальнейшие команды выполняются из каталога установки:

cd flipflag-selfhost
docker compose ps
docker compose exec -T api ./flipflag-api license-status
curl -fsS http://127.0.0.1:8088/healthz
curl -fsS http://127.0.0.1:8088/v1/license/status

Подставьте свой порт и адрес. Войдите под созданным администратором, создайте проект, окружение и тестовый флаг, выпустите SDK-ключ. SDK-ключ проекта и ключ активации on-prem — разные секреты. Ключ активации не помещают в браузер или мобильное приложение.

import { createClient } from "@flipfeatureflag/js";

const flags = createClient({
  url: "https://flags.example.com", // без добавления /v1
  sdkKey: "PROJECT_SDK_KEY",
  env: "prod",
  context: { userId: "user-123" },
});

await flags.start();
const newCheckout = flags.isEnabled("new_checkout", false);
// false должен вести к рабочему старому checkout, а не к пустому экрану.

Для браузерного SDK укажите origin приложения в CORS_ALLOW_ORIGINS API, например https://shop.example.com. Сам интерфейс установки также должен оставаться в разрешённом списке. В базовом Compose значение берётся из PUBLIC_ORIGIN; для нескольких origins добавьте отдельный Compose override с точным списком через запятую. Пример отдельного compose.cors.yaml:

services:
  api:
    environment:
      CORS_ALLOW_ORIGINS: https://flags.example.com,https://shop.example.com

Добавьте compose.cors.yaml в конец существующего COMPOSE_FILE в .env, сохранив уже выбранные файлы HTTPS/proxy/внешней БД. Если списка нет, используйте COMPOSE_FILE=compose.yaml:compose.cors.yaml. Затем примените конфигурацию:

docker compose up -d --no-build --pull never --force-recreate api

Серверным SDK браузерный CORS не нужен. Не храните секретные значения во флагах, которые доступны браузерным/мобильным SDK-ключам.

Продление и окончание подписки

Проверить состояние можно без действующей лицензии. Новый файл/ключ передаётся через stdin:

docker compose exec -T api ./flipflag-api license-install < /secure/renewed.license
# Для замены онлайн-ключа или немедленной повторной активации после оплаты:
docker compose exec -T api ./flipflag-api license-activate < /secure/activation.key

Импорт офлайн-файла в Compose отключает сохранённую онлайн-активацию. По окончании допуска бизнес API, включая login и SDK evaluate/metrics, отвечает HTTP 402 Payment Required. Контейнеры и БД продолжают работать; данные не удаляются. Команды обновления лицензии, health endpoints и /v1/license/status доступны.

SDK сохраняют последний успешный снимок в памяти и используют defaults при его отсутствии. Новые процессы/страницы не наследуют этот кэш. Отсутствие ответа не должно блокировать работу приложения: предусмотрите defaults и обработку ошибок; подробнее в разделе об ошибках SDK. Отзыв онлайн-доступа приходит при следующей успешной проверке. В изолированной сети ранее выданный файл нельзя отозвать удалённо до его окончания.

Корпоративный PostgreSQL

Подготовьте две отдельные базы — control и tenant — и LOGIN-роль без SUPERUSER/CREATEDB/CREATEROLE. Роль должна владеть базами/объектами миграций. Расширение uuid-ossp заранее устанавливает DBA, если приложение не вправе его создать. Мастер с встроенной БД — самый простой путь; внешний PostgreSQL подключается отдельно:

1. Загрузите образы: docker load -i images/flipflag-images.tar. Для AMD64 скопируйте compose.amd64.env.example в .env перед ./scripts/init.sh; для ARM64 используется .env.example. Выполните ./scripts/init.sh и задайте .env: PUBLIC_ORIGIN, порт, стабильный ID и параметры лицензирования.
2. Замените secrets/control_dsn и secrets/tenant_dsn настоящими URI с sslmode=verify-full. Tenant URI фиксированный, без %s. Пароли percent-encode.
3. Сохраните mode 0444 файлов внутри закрытого каталога secrets/ (0700).
4. Добавьте в .env COMPOSE_FILE=compose.yaml:compose.external.yaml.
5. Запустите docker compose up -d --no-build --pull never --wait, активируйте лицензию и однократно создайте администратора.

BOOTSTRAP_EMAIL=admin@example.com BOOTSTRAP_ORG_NAME='Example Corp' \
  BOOTSTRAP_NAME=Administrator ./scripts/bootstrap.sh < /secure/admin-password

Для частного CA смонтируйте сертификат read-only в API и dbtools через override; укажите один и тот же sslrootcert в обеих DSN. Смена DSN требует пересоздания API. Не запускайте мастер встроенной БД поверх вручную настроенной внешней установки.

Резервные копии, перезапуск и обновления

./scripts/backup.sh
# Пример пути: backups/20261010T120000Z

Backup на короткое время останавливает API/UI, создаёт два согласованных дампа и запускает сервисы обратно. Копируйте дампы в зашифрованное внешнее хранилище. Отдельно сохраняйте .env, secrets/, installation/, данные лицензии из volume и, если нужно, сертификаты Caddy. Дампы БД не содержат весь этот набор. Сохраняйте ID установки при переносе и заранее проверяйте восстановление.

Восстановление заменяет данные

Команда ниже перезаписывает обе базы данными из backup. Сначала проверьте восстановление на отдельной установке и сохраните текущие данные. При ошибке приложение остаётся остановленным.

./scripts/restore.sh backups/20261010T120000Z

Для обычного перезапуска без удаления данных:

docker compose restart

Не используйте docker compose down -v: ключ -v удаляет постоянные volumes. Для обновления получите новый полный комплект от поставщика, сделайте backup, загрузите новые образы, обновите Compose/настройки по инструкции выпуска и выполните docker compose up -d --wait. Повтор загрузчика версии 0.3.0 — продолжение установки, а не автоматическое обновление на будущий релиз. Миграции могут быть несовместимы со старым бинарником: откат требует прежних образов и обоих согласованных дампов.

Если установка прервалась

Повторите ту же команду загрузчика из того же родительского каталога либо ./install.sh из уже распакованного комплекта. Мастер сохранит существующие настройки и секреты, не заменит созданного администратора. Не удаляйте .env, secrets/ или installation/.

Симптом	Что проверить
Docker/Compose не найден	Установите зависимости; Compose должен быть 2.24.4+
Порт занят	Освободите его либо исправьте HTTP_PORT и порт в PUBLIC_ORIGIN перед повтором
Сертификат не выдан	DNS A/AAAA, доступность и занятость 80/443, исходящий ACME
Неверный ключ / отказ активации	Оплату, выбранный ключ и привязку к ID; проверьте исходящий HTTPS
HTTP 402	license-status, оплаченную дату, часы сервера и получение продления
Контейнер healthy, но API заблокирован	Health check проверяет инфраструктуру, а не право на бизнес API
Браузерный SDK получает CORS-ошибку	Разрешённый origin приложения и проксирование /v1/
Не удаётся войти после восстановления	Согласованность обеих БД, JWT-секрета и настроек установки

docker compose ps
docker compose logs --tail=100 api web

Перед передачей логов удаляйте токены, SDK-ключи, DSN и пользовательские данные. Один сервер не обеспечивает HA. SSO/SCIM и автоматическая retention метрик не входят в текущую поставку; требования корпоративного внедрения согласуются отдельно.