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 (блокировка мержа до зелёных проверок)