docs: сайт документации на MkDocs Material

- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
Pjandro
2026-11-22 21:39:08 +03:00
parent ae7c8b755a
commit b3511f8b74
27 changed files with 1616 additions and 0 deletions
+54
View File
@@ -0,0 +1,54 @@
# Деплой (прод)
Наружный вход прода — **`https://pjandro.ru/pdf-converter/`** (пользовательский
nginx режет префикс и проксирует на стек конвертера). Публикация полностью
автоматизрована: **push в `main` → Gitea Actions**.
## Пайплайн `main.yml`
```
java + web (тесты/гейты) ──> images-app + images-web (build+push в реестр)
──> deploy (рендер прод-стека, pull, up, health-гейты, автооткат)
──> autotests (pytest против живого прода; провал → rollback)
```
1. **`java` / `web`** — те же гейты, что на PR (`mvn clean verify` в контейнере
без fontconfig; `npm ci`/build/lint).
2. **`images-app` / `images-web`** — сборка Containerfile в Nexus-реестр, теги
`prod` + неизменяемый `sha-<7 символов>`; web печётся с
`VITE_BASE=/pdf-converter/` (путь публикации запекается в образ).
3. **`deploy`** — job **рендерит** `docker-compose.yml` и `nginx.conf` в директорию
деплоя из Gitea Variables (прод-хост не хранит ни конфигураций, ни секретов;
API-ключ — из Secret через окружение деплоя, на диск не пишется), затем
login/pull/`up -d --force-recreate app web`, гейты healthy + recreate gateway.
Единственное состояние на проде — `.rollback.env` (image id предыдущего рана).
4. **`autotests`** — 31 pytest-проверка против живого стенда; провал → откат
на образ из `.rollback.env`.
## Где креды и координаты
Всё вне репозитория — **Gitea Actions Variables/Secrets** (полный список и настройка
branch protection: [`GITEA-vars.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/GITEA-vars.md)).
Прод-ключ `WORDPDF_API_KEY` — только Secret. В репо и на диске прод-хоста ключа нет.
## Ручные операции
!!! warning "Перед ручным перезапуском прода"
Прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (живёт на прод-хосте,
вне репозитория) — там актуальные координаты и процедура. Ручных скриптов
деплоя в репозитории нет и не заводить.
Прод-образ/`compose` правятся только через CI-рендер; копий прод-стека на хосте
или в репо быть не должно.
## Проверка после деплоя
CI сам докладывает по job'ам (`/actions/runs/<id>/jobs`); руками:
```bash
curl -sf https://pjandro.ru/pdf-converter/actuator/health # 200 {"status":"UP"}
curl -s -o /dev/null -w '%{http_code}\n' https://pjandro.ru/pdf-converter/ # 200 SPA
```
Глубина (нюансы runner'ов, `DOCKER_BUILDKIT=0`, реестр, rollback-механика) —
[ci-cd.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/ci-cd.md).