ER Architect / Развёртывание

для тех, кто разворачивает

Развёртывание

ER Architect — один процесс Node, который говорит обычным HTTP и хранит JSON на томе. Своей базы данных он не поднимает. Всё ниже предполагает, что репозиторий у вас уже склонирован.

Эта страница — карта, а не руководство. Полные инструкции лежат в репозитории в Markdown, рядом с кодом, который они описывают, — поэтому меняются вместе с ним. Каждая ссылка ниже ведёт в настоящий файл.

PKlocalЗапустить локально

Одна команда. Ставить базу не нужно, регистрироваться негде.

docker compose up --build -d

# http://localhost:8080 — вход admin / admin, после чего смените пароль

docker compose down сохраняет данные в именованном томе; down -v удаляет их.

База на этой же машине? Внутри контейнера 127.0.0.1 — это сам контейнер. Указывайте host.docker.internal.

PKcompanyРазвернуть в компании

Опубликованного образа пока нет, поэтому оба пути собирают из исходников. Kubernetes — две команды. Скрипт пишет overlay Kustomize: это набор поправок поверх базовых манифестов из deploy/k8s/base, который применяется штатным kubectl apply -k — ставить ничего не нужно, Kustomize встроен в kubectl.

# собирает образ, пушит его и пишет манифесты Kubernetes под ваш хост
./scripts/aa-deploy-k8s.sh --host er.example.com --registry registry.example.com

kubectl apply -k deploy/k8s/overlays/company

Скрипт также генерирует пароль администратора и AA_CONNECTION_KEY в файл secret.env, который держится вне git. Пароль печатается один раз. Полный список флагов — --help: класс ingress, имя TLS-секрета, размер тома, второе окружение.

На одной виртуальной машине используйте production-override для Compose за своим обратным прокси — он слушает только loopback. Примеры конфигов Caddy и nginx лежат в deploy/examples/.

FKdomainСвой домен

Со стороны продукта предусматривать ничего не нужно — он на это и рассчитан.

ГдеЧто задать
DNSЗапись A или AAAA для вашего хоста, указывающая на ingress или обратный прокси.
TLSТерминируется на прокси или ingress. Само приложение говорит обычным HTTP на 8080 и сертификатов не хранит.
ПриложениеAA_PUBLIC_URL=https://er.example.com и AA_COOKIE_SECURE=true.
Kuberneteshost и tls.secretName в сгенерированных манифестах — скрипт развёртывания заполняет оба из --host.
AA_PUBLIC_URL — не косметика. Это origin, который приложение отдаёт провайдеру идентификации как адрес возврата. Если он расходится с тем, что в адресной строке, вход возвращает на экран логина без сессии и без сообщения об ошибке. Самый частый и самый неочевидный способ сломать переезд на домен.

AA_COOKIE_SECURE намеренно не выводится из URL: приложение не решает молча, что вашим cookie пора стать Secure.

FKssoЕдиный вход

Google, Microsoft Entra ID или любой провайдер, соответствующий стандарту OIDC. Redirect URI, который отправляет приложение, — {AA_PUBLIC_URL}/api/auth/<provider>/callback: без завершающего слеша, путь включает /api.

Две вещи, на которых с Entra ID теряют вечер. Issuer обязан оканчиваться на /v2.0 — endpoint версии 1.0 публикует другой discovery-документ и не проходит проверку. И Entra часто оставляет claim email пустым, кладя адрес в preferred_username; если вход падает с жалобой на отсутствующий email, задайте AA_OIDC_EMAIL_CLAIM=preferred_username.

На свежем экземпляре первый вошедший становится администратором инстанса. Стоит знать до того, как направить на него целый тенант.

NbackupsРезервные копии и ключ шифрования

Всё живёт на одном томе: проекты, пользователи, сохранённые подключения и ключ, которым запечатаны пароли к ним.

ПутьСодержимое
projects/Сами диаграммы, по одному JSON-файлу на проект.
auth/auth.jsonПользователи, сессии, членства, заявки на доступ.
connections/Сохранённые подключения. Пароли запечатаны AES-256-GCM.
secrets/connection.keyКлюч шифрования, генерируется здесь, если не задан AA_CONNECTION_KEY.
Ключ храните отдельно от данных. Потеряете — все сохранённые пароли к базам станут невосстановимыми: проекты уцелеют, учётные данные нет.

NlimitsОграничения, о которых стоит знать заранее

  • oneТолько одна реплика API. Присутствие и блокировки живут в памяти, а том данных рассчитан на одного писателя. Не масштабируйте Deployment и не используйте --scale app=2.
  • offMigration Apply выключен на сервере. Diff формирует SQL, который человек читает и выполняет в другом месте. Это осознанное решение, а не недоделка.
  • noneSMTP нет. Приглашения — копируемой ссылкой. Настраивать нечего, и ничто не отправится молча мимо.
  • okТелеметрии нет. Исходящий трафик идёт только к адресам, которые вы настроили: ваша база, ваш провайдер идентификации, провайдер ИИ, если вы его включили.

PKreferenceПолный справочник в репозитории

Это первоисточники. Они лежат рядом с кодом и меняются вместе с ним.

  • Self-host в компании: VM и Kubernetes

    Быстрый старт, чеклист переменных для HTTPS, Compose за обратным прокси, устройство Kustomize и что поддерживает совместная работа на одном инстансе, а что нет. Есть русская версия.

    documentation/company-selfhost.md
  • Настройка единого входа

    Google, Microsoft Entra ID и произвольный OIDC: redirect URI, нужные scope и таблица «симптом → причина» для случаев, когда вход молча возвращает на экран логина.

    documentation/sso-setup.md
  • Резервные копии и восстановление доступа

    Что копировать, почему ключ шифрования хранится отдельно и что можно восстановить, потеряв одно из двух.

    documentation/credential-backup.md
  • Восстановление пароля администратора

    Аварийная процедура для случая, когда войти администратором уже никто не может.

    documentation/admin-password-recovery.md
  • Матрица поддержки

    Какие базы first-class, какие экспериментальные и что «экспериментальный» означает с точки зрения того, что реально проверяется.

    documentation/support-matrix.md
  • Политика безопасности

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

    SECURITY.md