Перейти к содержанию

Production stack

Это runbook для production-контура портала и Authelia. Внешний reverse proxy обслуживается отдельным репозиторием и серверной конфигурацией.

  • portal - статический MkDocs-сайт в Docker;
  • authelia - аутентификация и authorization rules.
  • Этот runbook не описывает и не управляет серверным Caddy; он не должен останавливаться или проверяться как часть этого деплоя.

Деплой

  1. Запушить изменения в main.
  2. Дождаться workflow portal-docs.
  3. Workflow обнаруживает GitHub repos с docs/, синкает репозиторий на Ubuntu-host через SSH и генерирует portal/sources/repos.generated.yml.
  4. verify job публикует portal/.build/site как artifact, а deploy job забирает его перед rsync.
  5. Workflow генерирует runtime secret files в deploy/prod/authelia/secrets/ и users_database.yml, затем синкает их на сервер.
  6. Workflow запускает docker compose -f docker-compose.prod.yml up -d --build --pull always --remove-orphans.
  7. После синка runtime файлов workflow перезапускает wiki-portal-authelia, чтобы она перечитала users_database.yml и secret files.

Rollback

Самый безопасный rollback для текущего процесса - вернуть предыдущий commit и снова прогнать workflow.

  1. Найти последний рабочий commit.
  2. Создать revert commit или temporary rollback branch.
  3. Запушить rollback в main или вручную запустить workflow на rollback branch.
  4. После rollback снова проверить / и auth.portalgm.ru.

Если нужен прямой server-side rollback без нового commit, этот процесс надо отдельно усилить через release directories и symlink-based deploy.

Добавить пользователя

Production Authelia использует deploy/prod/authelia/users_database.yml, который workflow собирает из уже существующих GitHub Secrets:

  • AUTHELIA_STORAGE_ENCRYPTION_KEY
  • JWT_SECRET
  • SESSION_SECRET
  • WIKI_ADMIN_EMAIL
  • WIKI_ADMIN_PASSWORD
  • WIKI_DEV_LOGIN
  • WIKI_DEV_PASSWORD
  • WIKI_MARKETING_LOGIN
  • WIKI_MARKETING_PASSWORD

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

  • WIKI_MARKETING_LOGIN -> marketing / readers
  • WIKI_DEV_LOGIN -> dev / editors
  • WIKI_ADMIN_EMAIL -> admin / admins

В deploy/prod/authelia/configuration.yml включен поиск по email, поэтому для этих пользователей можно использовать как короткий логин, так и email из поля email.

  1. Сгенерировать новый password hash через Authelia:
docker run --rm authelia/authelia:4.39.19 authelia crypto hash generate sha2crypt --password 'new-password'
  1. Workflow сам собирает users DB на основании секретов выше.
  2. Убедиться, что user входит в нужную group:
  3. marketing -> readers
  4. dev -> editors
  5. admin -> admins
  6. Перезапустить workflow deploy.

Смена паролей и секретов

Ротация production secrets:

  • AUTHELIA_STORAGE_ENCRYPTION_KEY
  • SESSION_SECRET
  • JWT_SECRET

AUTHELIA_STORAGE_ENCRYPTION_KEY должен быть не короче 20 символов, иначе Authelia уходит в restart loop уже на старте.

Порядок:

  1. Сгенерировать новые random values.
  2. Обновить GitHub Secrets.
  3. Запустить deploy workflow.
  4. Проверить, что / и /admin/ снова открываются после логина.

Подключить новый repo

  1. Если repo находится в GitHub org и у него есть docs/, он подключается автоматически через portal/sources/repos.generated.yml.
  2. Для внешних репозиториев, не входящих в org, добавить source в portal/sources/repos.yml.
  3. Проверить, что PORTAL_GITHUB_TOKEN имеет доступ к private repos, иначе discovery и clone будут падать.
  4. Прогнать make build и production workflow.
  5. Не коммитить portal/docs/imported/, portal/docs/_generated/, portal/docs/admin/config.yml и portal/sources/repos.generated.yml; они генерируются при build/deploy.

Почему /admin не работает

Проверять по порядку:

  1. auth.portalgm.ru отвечает 200/302 без 5xx.
  2. В deploy/prod/authelia/configuration.yml есть rule для /admin.
  3. Пользователь входит в editors или admins.
  4. portal/docs/admin/config.yml сгенерирован build'ом.
  5. portal и authelia контейнеры запущены без restart loop.

Логи

Смотреть логи на host:

docker compose -f docker-compose.prod.yml logs -f portal
docker compose -f docker-compose.prod.yml logs -f authelia

Если нужен быстрый health-check, сначала проверить:

docker compose -f docker-compose.prod.yml ps