diff --git a/.ci/maven-settings.xml b/.ci/maven-settings.xml
new file mode 100644
index 0000000..542e653
--- /dev/null
+++ b/.ci/maven-settings.xml
@@ -0,0 +1,20 @@
+
+
+
+
+
+ nexus-mirror
+ *
+ ${env.MAVEN_MIRROR_URL}
+
+
+
diff --git a/.gitea/workflows/main.yml b/.gitea/workflows/main.yml
index 1584dd7..0fcfb82 100644
--- a/.gitea/workflows/main.yml
+++ b/.gitea/workflows/main.yml
@@ -11,6 +11,15 @@ jobs:
steps:
- uses: actions/checkout@v5
+ - name: Check maven mirror var
+ env:
+ MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
+ run: |
+ [ -n "$MAVEN_MIRROR_URL" ] || {
+ echo "Задайте Actions Variable MAVEN_MIRROR_URL — см. GITEA-vars.md" >&2
+ exit 1
+ }
+
- name: Setup JDK 17
uses: actions/setup-java@v5
with:
@@ -30,7 +39,9 @@ jobs:
echo "/opt/apache-maven-3.9.16/bin" >> "$GITHUB_PATH"
- name: Build and test (PMD gate included)
- run: mvn -B clean verify
+ env:
+ MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
+ run: mvn -B -s .ci/maven-settings.xml clean verify
- name: Coverage summary
if: always()
@@ -126,11 +137,12 @@ jobs:
- name: Check registry vars and secret
env:
REGISTRY: ${{ vars.REGISTRY }}
+ MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
run: |
- [ -n "$REGISTRY" ] && [ -n "$REGISTRY_USER" ] && [ -n "$REGISTRY_PASSWORD" ] || {
- echo "Задайте Actions Variable REGISTRY и Secrets REGISTRY_USER/REGISTRY_PASSWORD — см. GITEA-vars.md" >&2
+ [ -n "$REGISTRY" ] && [ -n "$MAVEN_MIRROR_URL" ] && [ -n "$REGISTRY_USER" ] && [ -n "$REGISTRY_PASSWORD" ] || {
+ echo "Задайте Actions Variables REGISTRY/MAVEN_MIRROR_URL и Secrets REGISTRY_USER/REGISTRY_PASSWORD — см. GITEA-vars.md" >&2
exit 1
}
@@ -147,11 +159,13 @@ jobs:
- name: Build and push app image
env:
REGISTRY: ${{ vars.REGISTRY }}
+ MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
run: |
sha="${GITHUB_SHA:0:7}"
# DOCKER_BUILDKIT=0: daemon за раннером — podman, BuildKit-сессий нет,
# только classic /build (buildah).
DOCKER_BUILDKIT=0 docker build -f Containerfile \
+ --build-arg MAVEN_MIRROR_URL="$MAVEN_MIRROR_URL" \
-t "$REGISTRY/wordpdf-app:prod" -t "$REGISTRY/wordpdf-app:sha-$sha" .
docker push "$REGISTRY/wordpdf-app:prod"
docker push "$REGISTRY/wordpdf-app:sha-$sha"
diff --git a/.gitea/workflows/pr.yml b/.gitea/workflows/pr.yml
index b790fb5..a2bb1fe 100644
--- a/.gitea/workflows/pr.yml
+++ b/.gitea/workflows/pr.yml
@@ -10,6 +10,15 @@ jobs:
steps:
- uses: actions/checkout@v5
+ - name: Check maven mirror var
+ env:
+ MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
+ run: |
+ [ -n "$MAVEN_MIRROR_URL" ] || {
+ echo "Задайте Actions Variable MAVEN_MIRROR_URL — см. GITEA-vars.md" >&2
+ exit 1
+ }
+
- name: Setup JDK 17
uses: actions/setup-java@v5
with:
@@ -29,7 +38,9 @@ jobs:
echo "/opt/apache-maven-3.9.16/bin" >> "$GITHUB_PATH"
- name: Build and test (PMD gate included)
- run: mvn -B clean verify
+ env:
+ MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
+ run: mvn -B -s .ci/maven-settings.xml clean verify
- name: Coverage summary
if: always()
diff --git a/AGENTS.md b/AGENTS.md
index acc2ad6..71da84d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -181,6 +181,7 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
- `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app); JaCoCo execution `check` переопределён (LINE 0.90 + BRANCH 0.85).
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, commons-compress `1.28.0`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox/fontbox `3.0.8` (`fontbox` — compile в core: глиф-движок `GlyphFont`; `pdfbox` — test в обоих модулях; commons-logging исключён, мост — `jcl-over-slf4j`), POI `5.5.1` (test), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`, PMD `3.28.0`, JaCoCo `0.8.15`; пустой дефолт `` (для `-Djacoco.skip=true`).
- `pmd-ruleset.xml` — ruleset PMD (см. Code Conventions).
+- `.ci/maven-settings.xml` — Maven-зеркало Nexus с URL из `${env.MAVEN_MIRROR_URL}` (общий файл CI-job'ов `java` и Containerfile; координаты стенда в репо не хранятся — Variable/build-arg).
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF.
- `gateway/nginx.conf` — единственный вход: `/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app:8080`, остальное → `web:80`; `client_max_body_size 100m` (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API); `proxy_read_timeout`/`proxy_send_timeout 300s` (дефолтные 60s рвут 2-минутные конвертации 504 раньше app-ного 504); `resolver 10.113.0.1` + `proxy_pass` через переменные (статический `proxy_pass` резолвит имя один раз при старте — gateway, поднявшийся раньше app, получал бы 502 до перезапуска).
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур; `ChartTypesDocxGenerator.java` — генератор `chart-types.docx`.
@@ -190,6 +191,7 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
- Java 17 + Maven (обязательны; wrapper `mvnw` нет — только системный Maven); UTF-8. Только Maven — никаких Gradle/Ant. Java/Maven/Node/Python для локальной разработки ставит project-local mise (бинарь в `.mise/`, вне системы), версии пинятся в корневом `mise.toml` (`java = temurin-17`, `maven = 3.9.16`, `node = 24`, `python = 3.15`), ежедневный запуск — `./mise.sh` / `.\mise.ps1`. Bootstrap качает mise `2026.10.19` → `./.mise/bin`, затем `mise trust` → `mise install` → `mise run web-install`.
- Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement); новые зависимости — latest stable.
+- Зависимости Maven — через зеркало Nexus `maven-central`: локально `~/.m2/settings.xml` (литеральный URL, файл вне репо), CI/Containerfile — `.ci/maven-settings.xml` + `MAVEN_MIRROR_URL` (Variable / build-arg).
- Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/rolldown/oxlint из `package-lock.json` — в `package.json` секции `engines` нет), npm с закоммиченным `package-lock.json` (`npm ci`); vite `^8.3`, React `^19.2`, TS `~6.0` (**`strict` нигде не включён** — `npm run build` не является strict-гейтом), Tailwind `^4.3`, oxlint `^1.81`; сборка web-образа на `node:24-alpine`.
- Контейнеры (podman/buildah): `FROM` только FQDN (`docker.io/library/...` — short-name не резолвится без `unqualified-search-registries`); buildah подмешивает хостовые прокси-переменные в `RUN`/`HEALTHCHECK` — обнулять `HTTP_PROXY= http_proxy= …` **на самой команде** (ENV не перебивает). Chart-движку нужен только модуль `java.desktop` (Graphics2D, он внутри JRE); fontconfig и системные шрифты рантайму не нужны — текст рисуется глифами fontbox (`fonts/GlyphFont`), проверено на musl-стенде без libfontconfig/`/etc/fonts`.
- Локальная проверка одна: `mvn clean verify` (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD.
@@ -198,13 +200,13 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
## CI/CD (Gitea Actions)
-Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`): job `java` (temurin 17, кеш `~/.m2`, Maven 3.9.16 с dlcdn, `mvn -B clean verify`) → `Coverage summary` (разбор `target/site/jacoco/jacoco.xml` python-сниппетом в step summary) → `Comment coverage on PR` (тот же текст комментарием; создаётся один раз, повторные push обновляют по маркеру ``; `continue-on-error`). job `web` (кеш `~/.npm`, `npm ci` → `build` → `lint`).
+Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`): job `java` (temurin 17, кеш `~/.m2`, Maven 3.9.16 с dlcdn, `mvn -B -s .ci/maven-settings.xml clean verify` через зеркало Nexus `maven-central` (fail-closed проверка Variable `MAVEN_MIRROR_URL` первым шагом)) → `Coverage summary` (разбор `target/site/jacoco/jacoco.xml` python-сниппетом в step summary) → `Comment coverage on PR` (тот же текст комментарием; создаётся один раз, повторные push обновляют по маркеру ``; `continue-on-error`). job `web` (кеш `~/.npm`, `npm ci` → `build` → `lint`).
-`.gitea/workflows/main.yml` — `Main: tests, deploy, autotests` (`push` в `main` + `workflow_dispatch`): те же `java`/`web` (байт-байт дубль — workflow-файлы самодостаточны, reusable-workflow не вводить) → `images-app`/`images-web` (build+push каждого Containerfile в Nexus-реестр `${{ vars.REGISTRY }}`, теги `prod` + immovable `sha-<7 символов GITHUB_SHA>`; web печётся с `--build-arg VITE_BASE=/pdf-converter/`; `DOCKER_BUILDKIT=0` обязателен — daemon за раннером podman, BuildKit-сессий нет; креды — вручную пишется `~/.docker/config.json`) → `deploy` (SSH на прод: рендер конфигов heredoc'ами в workspace раннера — appleboy/ssh-action непригоден, ломает heredoc; валидация PyYAML; сохранение `.rollback.env`; `login/pull/timeout 90 podman-compose up -d --force-recreate app web`; гейты healthy и image; gateway пересоздаётся последним; health-check) → `autotests` (venv + `prod-autotests/` против прода) → `rollback` (`if: failure()` — перерендер/перезалив прод-файлов тем же шагом, retag прежних image ID на `:prod`, `--force-recreate app web`, пересоздание gateway).
+`.gitea/workflows/main.yml` — `Main: tests, deploy, autotests` (`push` в `main` + `workflow_dispatch`): те же `java`/`web` (байт-байт дубль — workflow-файлы самодостаточны, reusable-workflow не вводить) → `images-app`/`images-web` (build+push каждого Containerfile в Nexus-реестр `${{ vars.REGISTRY }}`, теги `prod` + immovable `sha-<7 символов GITHUB_SHA>`; app печётся с `--build-arg MAVEN_MIRROR_URL=…` (зеркало Nexus в Containerfile); web печётся с `--build-arg VITE_BASE=/pdf-converter/`; `DOCKER_BUILDKIT=0` обязателен — daemon за раннером podman, BuildKit-сессий нет; креды — вручную пишется `~/.docker/config.json`) → `deploy` (SSH на прод: рендер конфигов heredoc'ами в workspace раннера — appleboy/ssh-action непригоден, ломает heredoc; валидация PyYAML; сохранение `.rollback.env`; `login/pull/timeout 90 podman-compose up -d --force-recreate app web`; гейты healthy и image; gateway пересоздаётся последним; health-check) → `autotests` (venv + `prod-autotests/` против прода) → `rollback` (`if: failure()` — перерендер/перезалив прод-файлов тем же шагом, retag прежних image ID на `:prod`, `--force-recreate app web`, пересоздание gateway).
Артефактов покрытия нет намеренно: `upload-artifact@v4` Gitea не поддерживает, `@v3` на этом стенде зависает. HTML-отчёт — локально `target/site/jacoco/`, `web` (кеш `~/.npm`).
-**Правило: координаты прода и креды в коммитимые файлы не попадают** — ни внутренние IP, ни SSH-пользователи/логины, ни хосты, ни директория деплоя, ни ключи/токены/пароли. Координаты стенда — Gitea Actions **Variables** (`DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_DIR`, `WORDPDF_BASE_URL`, `WORDPDF_MAX_PAGES`, `WORDPDF_MAX_MB`, `REGISTRY`, `PIP_INDEX_URL`), креды — **Secrets** (`DEPLOY_SSH_KEY`, `DEPLOY_KNOWN_HOSTS`, `WORDPDF_API_KEY`, `REGISTRY_USER`, `REGISTRY_PASSWORD`); workflow-файлы ссылаются на них только `${{ vars.* }}`/`${{ secrets.* }}`. Смена лимитов = правка Variables, PR не нужен. Защита ветки `main`: required-контексты **`PR checks / java (pull_request)`, `PR checks / web (pull_request)`** (deploy/autotests в список НЕ включать — на PR не бегут, мерж блокировался бы навсегда).
+**Правило: координаты прода и креды в коммитимые файлы не попадают** — ни внутренние IP, ни SSH-пользователи/логины, ни хосты, ни директория деплоя, ни ключи/токены/пароли. Координаты стенда — Gitea Actions **Variables** (`DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_DIR`, `WORDPDF_BASE_URL`, `WORDPDF_MAX_PAGES`, `WORDPDF_MAX_MB`, `REGISTRY`, `PIP_INDEX_URL`, `MAVEN_MIRROR_URL`), креды — **Secrets** (`DEPLOY_SSH_KEY`, `DEPLOY_KNOWN_HOSTS`, `WORDPDF_API_KEY`, `REGISTRY_USER`, `REGISTRY_PASSWORD`); workflow-файлы ссылаются на них только `${{ vars.* }}`/`${{ secrets.* }}`. Смена лимитов = правка Variables, PR не нужен. Защита ветки `main`: required-контексты **`PR checks / java (pull_request)`, `PR checks / web (pull_request)`** (deploy/autotests в список НЕ включать — на PR не бегут, мерж блокировался бы навсегда).
## Testing & QA
diff --git a/Containerfile b/Containerfile
index 7784050..f1ccb39 100644
--- a/Containerfile
+++ b/Containerfile
@@ -2,12 +2,24 @@
# unqualified-search-registries в /etc/containers/registries.conf.
FROM docker.io/library/maven:3.9-eclipse-temurin-17 AS build
WORKDIR /build
+# Зеркало Nexus (в CI приходит --build-arg MAVEN_MIRROR_URL из Gitea Variable).
+# Без ARG — прямой Central: локальные podman-сборки (compose.dev.yml) работают
+# без аргументов. settings.xml — общий с CI-job'ами файл .ci/maven-settings.xml,
+# URL интерполируется из env MAVEN_MIRROR_URL (интерполяция ${env.*} в settings.xml
+# проверена); mvn -s /dev/stdin не работает — файл обязан быть реальным.
+ARG MAVEN_MIRROR_URL=
+ENV MAVEN_MIRROR_URL=${MAVEN_MIRROR_URL}
+COPY .ci/maven-settings.xml /tmp/ci-maven-settings.xml
+RUN if [ -n "$MAVEN_MIRROR_URL" ]; then mkdir -p /root/.m2 && cp /tmp/ci-maven-settings.xml /root/.m2/settings.xml; fi
COPY pom.xml .
COPY wordpdf-core/pom.xml wordpdf-core/
COPY wordpdf-app/pom.xml wordpdf-app/
-RUN mvn -B -q dependency:go-offline
+# Прокси обнуляем на самой команде (тот же приём, что в HEALTHCHECK): к Nexus
+# ходим напрямую по LAN, подмешанные buildah хостовые прокси-переменные
+# (127.0.0.1:порт внутри контейнера) не должны перехватывать запросы.
+RUN HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= mvn -B -q dependency:go-offline
COPY . .
-RUN mvn -B -q -DskipTests package
+RUN HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= mvn -B -q -DskipTests package
FROM docker.io/library/eclipse-temurin:17-jre-alpine
# runtime alpine (минимальный): chart-движку нужен только модуль java.desktop
diff --git a/GITEA-vars.md b/GITEA-vars.md
index a63635a..cf3d5ca 100644
--- a/GITEA-vars.md
+++ b/GITEA-vars.md
@@ -30,31 +30,39 @@ job'ах `images-app`/`images-web` (проверка `REGISTRY`/`REGISTRY_USER`/
|`WORDPDF_MAX_PAGES`|Лимит страниц на проде (сейчас `100`)|
|`WORDPDF_MAX_MB`|Лимит размера входного .docx, МБ (сейчас `5`)|
|`REGISTRY`|Адрес docker-реестра `host:port` без схемы (Nexus docker-registry на прод-сервере, коннектор `:5000`)|
-|`PIP_INDEX_URL`|Полный URL pypi-proxy индекса Nexus без кредов, вида `http://:/repository/pypi-proxy/simple` (репозиторий заводится по разделу «Nexus: pypi-proxy» ниже; HTTP-порт Nexus — не docker-коннектор `:5000`)|
+|`PIP_INDEX_URL`|Полный URL pypi-proxy индекса Nexus без кредов, вида `http://:/repository/pypi-proxy/simple` (репозиторий заводится по разделу «Nexus: анонимный доступ CI» ниже; HTTP-порт Nexus — не docker-коннектор `:5000`)|
+|`MAVEN_MIRROR_URL`|Полный URL зеркала Nexus maven-central со слэшем на конце: `http://:/repository/maven-central/` (репозиторий `maven-central` — штатный proxy на Central из коробки Nexus 3, создавать не надо; заводка доступа — раздел «Nexus: анонимный доступ CI» ниже)|
При смене лимитов прода — править `WORDPDF_MAX_PAGES`/`WORDPDF_MAX_MB` в Variables, PR не нужен: job `deploy` прокидывает их в прод-stack (app пересоздаётся с новыми лимитами), job `autotests` сверяет проверки с ними же. Без обеих Variables job'ы `deploy`/`autotests` падают на проверке — fail-closed.
-## Nexus: pypi-proxy (для job `autotests`)
+## Nexus: анонимный доступ CI (pypi-proxy + maven-central)
-Заводится **до мержа** PR, использующего `PIP_INDEX_URL`: иначе `autotests` упадёт на
-fail-closed проверке и `rollback` откатит предыдущий деплой. Nexus 3 поддерживает PEP 503
-(Simple Repository API) для pypi-proxy — https://help.sonatype.com/en/pypi-repositories.html.
+Заводится **до мержа** PR'ов, использующих `PIP_INDEX_URL`/`MAVEN_MIRROR_URL`: иначе
+соответствующие job'ы упадут на fail-closed проверке (а `autotests` ещё и спровоцирует
+`rollback`). Nexus 3 поддерживает PEP 503 (Simple Repository API) для pypi-proxy —
+https://help.sonatype.com/en/pypi-repositories.html; `maven-central` (proxy на Central)
+и `maven-public` (group) есть из коробки Nexus — создавать нечего.
1. Settings → Repositories → Create repository: format **PyPI**, type **Proxy**, name
**`pypi-proxy`**, Remote storage URL **`https://pypi.org/`**, blob store — тот же, что у
docker-репозиториев.
-2. Read-доступ CI без новых секретов — анонимный доступ, ограниченный одним репозиторием
- (контент pypi публичный):
- - Roles → Create role: name `pypi-anonymous`, Role type **Simple**, memberships —
- `nx-anonymous`, privileges — `nx-repository-view-pypi-pypi-proxy-read` и
- `nx-repository-view-pypi-pypi-proxy-browse`.
- - Security → Anonymous Access: включить, **Anonymous User Role IDs = `pypi-anonymous`**
- (не `nx-anonymous` — иначе анонимы получат вид на все репозитории).
+2. Read-доступ CI без новых секретов — анонимный доступ, ограниченный двумя репозиториями
+ (контент pypi/maven central публичный):
+ - Roles → Create role: name `ci-anonymous`, Role type **Simple**, memberships —
+ `nx-anonymous`, privileges — `nx-repository-view-pypi-pypi-proxy-read`,
+ `nx-repository-view-pypi-pypi-proxy-browse`,
+ `nx-repository-view-maven2-maven-central-read`,
+ `nx-repository-view-maven2-maven-central-browse`.
+ Если роль `pypi-anonymous` уже заведена по прежней инструкции — переименовать её
+ в `ci-anonymous` и добавить два maven-привилегия.
+ - Security → Anonymous Access: включить, **Anonymous User Role IDs = `ci-anonymous`**
+ (единственная роль; не `nx-anonymous` — иначе анонимы получат вид на все репозитории).
3. Проверка с любой машины LAN (порт — HTTP-коннектор Nexus, дефолт `8081`, не `:5000`):
- `curl -fsS 'http://:<порт>/repository/pypi-proxy/simple/pytest/'` отдаёт PEP 503-лист
- без кредов; docker-репозиторий анониму по-прежнему 401/403.
+ `curl -fsS 'http://:<порт>/repository/pypi-proxy/simple/pytest/'` — PEP 503-лист
+ без кредов; `curl -fsS 'http://:<порт>/repository/maven-central/org/apache/maven/maven-core/3.9.16/maven-core-3.9.16.pom'`
+ — XML; docker-репозиторий анониму по-прежнему 401/403.
-Затем — Variable `PIP_INDEX_URL` (см. таблицу выше).
+Затем — Variables `PIP_INDEX_URL` и `MAVEN_MIRROR_URL` (см. таблицу выше).
## Защита ветки main (блокировка мержа до зелёных проверок)