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

Все сервисы экосистемы используют одну модель развёртывания. Эта страница её описывает.

Конкретики по хостам здесь нет

Эксплуатационные детали — адреса серверов, имена пользователей, секретные настройки — на этот публичный сайт не попадают. Они находятся в закрытом runbook внутри соответствующего репозитория.

Общая схема¶

        Интернет
            │
            ▼
   ┌─────────────────┐
   │   edge nginx    │  TLS termination · HSTS · rate limit
   │   (контейнер)   │  каждый vhost → внутренний сервис
   └────────┬────────┘
            │  общая сеть Docker
   ┌────────┴──────────────────────────────┐
   │                                       │
   ▼                ▼                      ▼
 прил. A          прил. B              статический сайт
 (Go + Next)     (Go + Next)            (nginx)
   │                │
   └────────┬───────┘
            ▼
   PostgreSQL · Redis  (общие)

Основные принципы:

Один edge, много vhost. Снаружи единственный контейнер nginx владеет портами 80/443. У каждого домена свой блок server, проксирующий на внутренний сервис.
Внутренние сервисы наружу не открыты. Приложения слушают только общую сеть Docker либо привязываются к 127.0.0.1. Снаружи к ним не обратиться.
Общая инфраструктура. Один экземпляр PostgreSQL и один Redis обслуживают несколько приложений; у каждого приложения своя БД/схема.
Docker Compose — у каждого приложения свой compose-стек, подключённый к общей сети.

Edge nginx¶

Edge отвечает за:

Роль	Пояснение
TLS termination	Сертификаты Let's Encrypt, автоматическое обновление
HSTS	`max-age=63072000; includeSubDomains`
Rate limit	По зонам: `auth` (жёсткая) · `app` (мягкая) · `api`
Обратный прокси	vhost → внутренний сервис
Отказ неизвестным хостам	Default server → разрыв соединения

Конфигурация edge управляется через git

Каталог conf.d у edge nginx синхронизируется из определённого репозитория через git. Любая правка вручную на хосте будет затёрта командой git reset --hard при следующем деплое.

Поэтому добавление или изменение vhost выполняется коммитом в репозиторий, а CI это распространяет.

Вторая модель — сервис владеет собственным vhost

Есть и модель, при которой vhost, относящийся только к одному сервису, лежит в репозитории этого сервиса, а не в центральном файле, и его деплой сам устанавливает конфиг в conf.d edge отдельным файлом.

Плюс: изменение заканчивается внутри одного репозитория и не ждёт деплоя другой команды. Условие: конфиг должен быть полностью самодостаточным — он не может зависеть от зоны rate-limit или default server, объявленных в другом файле.

Этот сайт работает именно так — см. Платформа этой документации.

Сертификаты¶

Let's Encrypt, через certbot в режиме webroot.
ACME challenge обслуживается на порту 80 по пути /.well-known/acme-challenge/.
Обновление автоматическое, еженедельно по cron; при успехе nginx перезагружается.

Чтобы добавить новый домен:

Направьте DNS на сервер.
Добавьте домен в блок ACME на порту 80.
Получите сертификат через certbot.
Добавьте HTTPS-vhost и укажите в нём сертификат.
Выполните nginx -t, затем reload.

Статические сайты (порталы документации)¶

Сайты документации — это заранее собранный статический HTML. Простейшая модель их запуска:

собрать site/ с помощью MkDocs,
скопировать результат на сервер,
отдавать его маленьким контейнером nginx:alpine,
проксировать на него с edge nginx.

Runtime приложения отсутствует, поэтому ресурсов нужно мало и ломаться почти нечему.

Этот сайт работает именно так — подробности на странице Платформа этой документации.

Деплой приложений¶

Для приложений используются две модели:

Модель	Пояснение
Сборка на хосте	CI синхронизирует репозиторий на хост и запускает `docker compose build && up -d`
Через registry	CI собирает образ и пушит его в registry; хост выполняет `pull && up -d`

Тенденция — сокращать зависимости: есть случаи перехода от внешнего registry к сборке прямо на хосте.

Частичный деплой: CI по изменившимся путям (paths-filter) определяет, какие сервисы пересобрать. Изменение в одном приложении не затрагивает остальные.

Откат¶

Статический сайт — распаковать архив предыдущей сборки.
Приложение — вернуться к предыдущему тегу образа (его можно закрепить переменной <SVC>_IMAGE_TAG).

Проверки работоспособности¶

У каждого сервиса есть endpoint /health. Директивы healthcheck в compose проверяют готовность инфраструктуры (PostgreSQL, Redis) и запускают приложение только после неё.

Чек-лист деплоя¶

[ ] DNS указывает верно
[ ] Сертификат выпущен и охвачен автообновлением
[ ] Edge vhost добавлен и закоммичен в репозиторий
[ ] nginx -t проходит успешно
[ ] Внутренние сервисы наружу не открыты
[ ] /health отвечает
[ ] Секреты через переменные окружения, в репозитории отсутствуют
[ ] Способ отката понятен

Подробности автоматизации — на странице CI/CD.