Миграция репо с docker на podman #10

Merged
pjandro merged 1 commits from podman-migration into main 2026-10-19 03:14:25 +03:00
15 changed files with 172 additions and 99 deletions
Showing only changes of commit 65746db9d2 - Show all commits
+6 -6
View File
@@ -2,7 +2,7 @@
## Project Overview ## Project Overview
Конвертер `.docx` → `.pdf` на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot 4.1.1 REST API); `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед `git push` — `mvn clean verify` (CI нет; SPA гейтуется `npm run build` + `npm run lint`). Вход стека — контейнер `gateway` (nginx), НЕ 8080. README устарел шире Docker-секции: лимиты (пишет 5 МБ/100 стр./6 МБ multipart — фактически 20 MiB/1000/100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что в проде она открыта без ключа, — авторитет этот файл. Конвертер `.docx` → `.pdf` на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot 4.1.1 REST API); `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед `git push` — `mvn clean verify` (CI нет; SPA гейтуется `npm run build` + `npm run lint`). Вход стека — контейнер `gateway` (nginx), НЕ 8080. README устарел шире секции про контейнеры: лимиты (пишет 5 МБ/100 стр./6 МБ multipart — фактически 20 MiB/1000/100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что в проде она открыта без ключа, — авторитет этот файл.
## Architecture & Data Flow ## Architecture & Data Flow
@@ -55,7 +55,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр
|`wordpdf-core/src/test/resources/samples/`|11 закоммиченных `.docx`-фикстур (единственные фикстуры)| |`wordpdf-core/src/test/resources/samples/`|11 закоммиченных `.docx`-фикстур (единственные фикстуры)|
|`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST API (10 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key для springdoc) + 4 класса исключений| |`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST API (10 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key для springdoc) + 4 класса исключений|
|`wordpdf-web/src/`|SPA (React 19 + TS + Vite + Tailwind): `api.ts` (вся сеть), `components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo)| |`wordpdf-web/src/`|SPA (React 19 + TS + Vite + Tailwind): `api.ts` (вся сеть), `components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo)|
|корневые `Dockerfile`, `docker-compose.yml`, `docker-compose.dev.yml`, `gateway/nginx.conf`|образ бэкенда (multi-stage maven:3.9-temurin-21 → temurin-21-jre, non-root, HEALTHCHECK actuator); compose app+web+gateway: web-образ со своим HEALTHCHECK (`wget /`), в обоих compose `depends_on web: condition: service_healthy` (без health web gateway не стартует); прод-compose интерполирует `WORDPDF_MAX_BYTES:-20971520`/`WORDPDF_MAX_PAGES:-1000`| |корневые `Containerfile`, `compose.yml`, `compose.dev.yml`, `gateway/nginx.conf`|образ бэкенда (multi-stage maven:3.9-temurin-21 → temurin-21-jre, non-root, HEALTHCHECK actuator); compose app+web+gateway: web-образ со своим HEALTHCHECK (`wget /`), в обоих compose `depends_on web: condition: service_healthy` (без health web gateway не стартует); прод-compose интерполирует `WORDPDF_MAX_BYTES:-20971520`/`WORDPDF_MAX_PAGES:-1000`; podman-специфика обоих compose: `x-podman.name_separator_compat` (docker-style имена контейнеров), явные `healthcheck` app/web (дубли Containerfile-HEALTHCHECK — OCI-выгрузка его теряет), зафиксированная подсеть `10.113.0.0/24` gw `10.113.0.1` под резолвер aardvark-dns; два repo-стенда одновременно не поднять (общая подсеть)|
|корневой `.env.example`|шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`; реальный прод `.env` — на прод-сервере (координаты: `/home/pjandro/prod/java-word-pdf/DEPLOY.md`, вне репо)| |корневой `.env.example`|шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`; реальный прод `.env` — на прод-сервере (координаты: `/home/pjandro/prod/java-word-pdf/DEPLOY.md`, вне репо)|
|`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `convert.pdf`, `1212.pdf`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать| |`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `convert.pdf`, `1212.pdf`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать|
@@ -70,7 +70,7 @@ mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotC
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен (test-jar core) mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен (test-jar core)
npm run dev # (wordpdf-web/) SPA :5173, vite-proxy /api → :8080 npm run dev # (wordpdf-web/) SPA :5173, vite-proxy /api → :8080
npm run build # (wordpdf-web/) tsc -b && vite build — гейт SPA; lint: npm run lint (oxlint) npm run build # (wordpdf-web/) tsc -b && vite build — гейт SPA; lint: npm run lint (oxlint)
docker compose -f docker-compose.dev.yml up -d --build # dev-стенд: http://<LAN-IP хоста>:9011 (0.0.0.0), без ключа, springdoc вкл podman-compose -f compose.dev.yml up -d --build # dev-стенд: http://<LAN-IP хоста>:9011 (0.0.0.0), без ключа, springdoc вкл
``` ```
Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — создана вручную, не перезаписывать): Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — создана вручную, не перезаписывать):
@@ -81,7 +81,7 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples
``` ```
Деплой. **Прод** — на пользовательском LAN-сервере; координаты сервера, каталог, restart-секвенция, ключ и гейты успешности — вне репо: `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (обязательно прочитать перед любым деплоем/перезапуском; в том каталоге лежат архивные файлы старого стека 88.14 — `restart.sh.old-88.14`, старый compose/nginx — **не поднимать**). Единая точка входа с dev-машины — `/home/pjandro/prod/java-word-pdf/restart.sh` (пробрасывает флаги удалённому скрипту: `--build` — пересборка образов из `origin/main` + перезапуск; без флага — restart контейнеров; предупреждает о не запушенном в `main`). В прод попадает только запушенное в `main` — рабочее дерево на сборку не влияет. Наружный вход `https://pjandro.ru/pdf-converter/` (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа дополнительно содержит `proxy_read_timeout 300s` — в репо её нет, дефолтные 60s рвут 2-минутные конвертации). Тот же наружный nginx в `location /pdf-converter/` добавляет `X-Forwarded-Host: $host` и `X-Forwarded-Prefix: /pdf-converter` — из них springdoc собирает server-URL спека и swagger-config под префиксом (без `X-Forwarded-Host` server = `https://app:8080`, gateway шлёт приложению `Host: app:8080`); канонический URL документации `https://pjandro.ru/pdf-converter/swagger-ui.html` — открыт без ключа. **Dev-стенд** — из репо `docker-compose.dev.yml` (проект `wordpdf-dev`, `9011:80` на все интерфейсы — вход по LAN-IP хоста, без env → ключ пуст, springdoc вкл). Репозиторный `docker-compose.yml` — третий вариант (проект `wordpdf`, `9010:80` на все интерфейсы, `WORDPDF_API_KEY` fail-closed без `.env` — `up` упадёт, `VITE_BASE` — build-arg `wordpdf-web/Dockerfile` — репо-compose НЕ передаёт: `compose build` без arg даёт base `/` и битые ассеты под префиксом, прод передаёт arg по DEPLOY.md). Запуск по просьбе пользователя = прод-стек; dev/`java -jar`/`npm run dev` — внутренняя отладка. Деплой. **Прод** — на пользовательском LAN-сервере (podman 5.8.2 + podman-compose 1.6.0, бинарников `docker`/`docker-compose` на сервере нет); координаты сервера, каталог, restart-секвенция, ключ и гейты успешности — вне репо: `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (обязательно прочитать перед любым деплоем/перезапуском; в том каталоге лежат архивные файлы старого стека 88.14 — `restart.sh.old-88.14`, старый compose/nginx — **не поднимать**). Единая точка входа с dev-машины — `/home/pjandro/prod/java-word-pdf/restart.sh` (пробрасывает флаги удалённому скрипту: `--build` — пересборка образов из `origin/main` + перезапуск; без флага — restart контейнеров; предупреждает о не запушенном в `main`). В прод попадает только запушенное в `main` — рабочее дерево на сборку не влияет. Прод-compose `/opt/wordpdf/docker-compose.yml` (вне git) содержит podman-специфику: `x-podman.name_separator_compat` (имена `wordpdf-prod-app-1`, от них зависит `restart.sh`), явные healthcheck app/web и фиксированную подсеть `10.112.0.0/24` gw `10.112.0.1`. Наружный вход `https://pjandro.ru/pdf-converter/` (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа отличается от репо только резолвером `10.112.0.1` — под свою подсеть — и `proxy_read_timeout 300s` — в репо его нет, дефолтные 60s рвут 2-минутные конвертации; resolver + `proxy_pass` через переменную есть и там и там). Тот же наружный nginx в `location /pdf-converter/` добавляет `X-Forwarded-Host: $host` и `X-Forwarded-Prefix: /pdf-converter` — из них springdoc собирает server-URL спека и swagger-config под префиксом (без `X-Forwarded-Host` server = `https://app:8080`, gateway шлёт приложению `Host: app:8080`); канонический URL документации `https://pjandro.ru/pdf-converter/swagger-ui.html` — открыт без ключа. **Dev-стенд** — из репо `compose.dev.yml` (проект `wordpdf-dev`, `9011:80` на все интерфейсы — вход по LAN-IP хоста, без env → ключ пуст, springdoc вкл). Репозиторный `compose.yml` — третий вариант (проект `wordpdf`, `9010:80` на все интерфейсы, `WORDPDF_API_KEY` fail-closed без `.env` — `up` упадёт, `VITE_BASE` — build-arg `wordpdf-web/Containerfile` — репо-compose НЕ передаёт: `compose build` без arg даёт base `/` и битые ассеты под префиксом, прод передаёт arg по DEPLOY.md). Запуск по просьбе пользователя = прод-стек; dev/`java -jar`/`npm run dev` — внутренняя отладка.
## Code Conventions & Common Patterns ## Code Conventions & Common Patterns
@@ -98,7 +98,7 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`. - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`.
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_BYTES` 20 MiB, `MAX_PAGES` 1000, `RENDER_CHARTS/SMARTART`); рантайм-конфигурации в ядре нет. - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_BYTES` 20 MiB, `MAX_PAGES` 1000, `RENDER_CHARTS/SMARTART`); рантайм-конфигурации в ядре нет.
- `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=100MB`, держит файл в памяти; в тон gateway `client_max_body_size 100m`), `wordpdf.convert-timeout=2m`, пустой `wordpdf.api-key`, `server.forward-headers-strategy=framework` (префикс прод-прокси для springdoc) + `springdoc.swagger-ui.persist-authorization=true`; `wordpdf.max-bytes`/`max-pages` здесь намеренно нет. - `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=100MB`, держит файл в памяти; в тон gateway `client_max_body_size 100m`), `wordpdf.convert-timeout=2m`, пустой `wordpdf.api-key`, `server.forward-headers-strategy=framework` (префикс прод-прокси для springdoc) + `springdoc.swagger-ui.persist-authorization=true`; `wordpdf.max-bytes`/`max-pages` здесь намеренно нет.
- `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен Docker HEALTHCHECK `/actuator/health`); тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core. - `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен HEALTHCHECK контейнера `/actuator/health`); тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.
- `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app). - `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app).
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (test), 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`. - Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (test), 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`.
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF. - `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF.
@@ -110,7 +110,7 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
- Java 21 + Maven (обязательны; wrapper `mvnw` нет); UTF-8. Только Maven — никакого Gradle/Ant. - Java 21 + Maven (обязательны; wrapper `mvnw` нет); UTF-8. Только Maven — никакого Gradle/Ant.
- Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement); новые зависимости — latest stable. - Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement); новые зависимости — latest stable.
- Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/oxlint из lockfile), npm с закоммиченным `package-lock.json` (`npm ci`); vite `^8.3.0`, React `^19.2`, TS `~6.0` (**`strict` нигде не включён** — `npm run build` не является strict-гейтом), Tailwind `^4.3`, oxlint `^1.81`; docker-сборка web на `node:24-alpine`. - Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/oxlint из lockfile), npm с закоммиченным `package-lock.json` (`npm ci`); vite `^8.3.0`, React `^19.2`, TS `~6.0` (**`strict` нигде не включён** — `npm run build` не является strict-гейтом), Tailwind `^4.3`, oxlint `^1.81`; podman-сборка web на `node:24-alpine`.
- CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна: `mvn clean verify`. - CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна: `mvn clean verify`.
- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят; `BundledFontsTest#listedFilesCoverAllTtfInResources` требует `file:`-протокол classpath — только surefire, не fat-jar). - Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят; `BundledFontsTest#listedFilesCoverAllTtfInResources` требует `file:`-протокол classpath — только surefire, не fat-jar).
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`, `main`/`dev` защищены (правила глобального AGENTS.md; локально только `main`, `dev` нет; на origin висит остаточная смерженная `docs/regenerate-agents-md`). - Git: origin `git.pjandro.ru:pjandro/java-word-pdf`, `main`/`dev` защищены (правила глобального AGENTS.md; локально только `main`, `dev` нет; на origin висит остаточная смерженная `docs/regenerate-agents-md`).
+6 -3
View File
@@ -1,4 +1,6 @@
FROM maven:3.9-eclipse-temurin-21 AS build # FROM с полным именем реестра: podman не резолвит short-name без
# unqualified-search-registries в /etc/containers/registries.conf.
FROM docker.io/library/maven:3.9-eclipse-temurin-21 AS build
WORKDIR /build WORKDIR /build
COPY pom.xml . COPY pom.xml .
COPY wordpdf-core/pom.xml wordpdf-core/ COPY wordpdf-core/pom.xml wordpdf-core/
@@ -7,11 +9,12 @@ RUN mvn -B -q dependency:go-offline
COPY . . COPY . .
RUN mvn -B -q -DskipTests package RUN mvn -B -q -DskipTests package
FROM eclipse-temurin:21-jre FROM docker.io/library/eclipse-temurin:21-jre
# curl — только для HEALTHCHECK; runtime полный jre (не alpine-slim): Java2D # curl — только для HEALTHCHECK; runtime полный jre (не alpine-slim): Java2D
# chart-движка нужны AWT и fontconfig-нативки; бандл-шрифты лежат в jar, # chart-движка нужны AWT и fontconfig-нативки; бандл-шрифты лежат в jar,
# системные шрифты не нужны. Тесты в образе не гоняем — гейт mvn clean verify. # системные шрифты не нужны. Тесты в образе не гоняем — гейт mvn clean verify.
# Прокси из docker-config подмешивается в HEALTHCHECK-шелл и ломает curl # Прокси-переменные хоста (HTTP_PROXY/HTTPS_PROXY/http_proxy/https_proxy)
# podman/buildah подмешивает в шелл RUN/HEALTHCHECK и ломает curl
# (127.0.0.1:proxy внутри контейнера недоступен) — обнуляем на команде. # (127.0.0.1:proxy внутри контейнера недоступен) — обнуляем на команде.
RUN apt-get update \ RUN apt-get update \
&& apt-get install -y --no-install-recommends curl \ && apt-get install -y --no-install-recommends curl \
+3 -3
View File
@@ -86,17 +86,17 @@ Files.write(Path.of("out.pdf"), pdf);
больше ста) бросают `ConversionException`. Работа с файлами — забота больше ста) бросают `ConversionException`. Работа с файлами — забота
вызывающего: ядро пути не принимает. вызывающего: ядро пути не принимает.
### Веб-интерфейс и Docker ### Веб-интерфейс и контейнеры (podman)
```bash ```bash
docker compose up -d --build podman-compose up -d --build
``` ```
Всё на `http://localhost:8080/`: nginx-контейнер `web` раздаёт SPA и проксирует Всё на `http://localhost:8080/`: nginx-контейнер `web` раздаёт SPA и проксирует
`/api`, `/swagger-ui`, `/v3/api-docs` на бэкенд (контейнер `app` наружу не `/api`, `/swagger-ui`, `/v3/api-docs` на бэкенд (контейнер `app` наружу не
публикуется). публикуется).
Dev-режим без Docker: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar` Dev-режим без контейнеров: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar`
(порт 8080) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173` (порт 8080) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
(Vite проксирует `/api` на 8080, CORS не нужен). (Vite проксирует `/api` на 8080, CORS не нужен).
+54
View File
@@ -0,0 +1,54 @@
# Dev-стенд без ключа доступа: WORDPDF_API_KEY не задан → wordpdf.api-key пуст
# → ApiKeyFilter прозрачен, springdoc включён. Проект wordpdf-dev — собственные
# образы/контейнеры, с прод-запуском (wordpdf-prod, :9010) не конфликтует.
# Запуск: podman-compose -f compose.dev.yml up -d --build
# Вход: http://<LAN-IP хоста>:9011 (доступен из локальной сети; hostname -I на хосте)
name: wordpdf-dev
# podman-compose по умолчанию разделяет имя проекта/сервиса/номера подчёркиванием
# (wordpdf-dev_app_1). Compat-флаг возвращает docker-style имена (wordpdf-dev-app-1).
x-podman:
name_separator_compat: true
services:
app:
build: .
restart: unless-stopped
# Дублирует HEALTHCHECK из Containerfile: podman выгружает образы в OCI,
# где поля healthcheck нет — без явного healthcheck depends_on
# service_healthy ждал бы healthy вечно. Прокси обнуляем на команде.
healthcheck:
test: ["CMD-SHELL", "HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= curl -fsS http://127.0.0.1:8080/actuator/health >/dev/null || exit 1"]
interval: 10s
timeout: 3s
start_period: 45s
retries: 5
web:
build: ./wordpdf-web
restart: unless-stopped
# См. комментарий у app: дубль HEALTHCHECK из wordpdf-web/Containerfile
healthcheck:
test: ["CMD-SHELL", "http_proxy= https_proxy= wget -qO /dev/null http://127.0.0.1/ || exit 1"]
interval: 10s
timeout: 3s
start_period: 10s
gateway:
image: docker.io/library/nginx:alpine
volumes:
- ./gateway/nginx.conf:/etc/nginx/conf.d/default.conf:ro
ports: ["9011:80"]
depends_on:
app:
condition: service_healthy
web:
condition: service_healthy
restart: unless-stopped
networks:
# Подсеть зафиксирована намеренно: nginx в gateway/nginx.conf резолвит app/web
# через aardvark-dns на шлюзе сети (10.113.0.1), адрес обязан быть
# предсказуемым. Оба repo-стенда делят её осознанно: они взаимоисключающие
# варианты отладки, одновременно не поднимаются.
default:
ipam:
config:
- subnet: 10.113.0.0/24
gateway: 10.113.0.1
+59
View File
@@ -0,0 +1,59 @@
name: wordpdf
# podman-compose по умолчанию разделяет имя проекта/сервиса/номера подчёркиванием
# (wordpdf_app_1). Compat-флаг возвращает docker-style имена (wordpdf-app-1).
x-podman:
name_separator_compat: true
services:
app:
build: .
restart: unless-stopped
# Дублирует HEALTHCHECK из Containerfile: podman выгружает образы в OCI,
# где поля healthcheck нет — без явного healthcheck depends_on
# service_healthy ждал бы healthy вечно. Прокси обнуляем на команде.
healthcheck:
test: ["CMD-SHELL", "HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= curl -fsS http://127.0.0.1:8080/actuator/health >/dev/null || exit 1"]
interval: 10s
timeout: 3s
start_period: 45s
retries: 5
environment:
# без ключа стек не поднимется (:? на пустое/unset) — прод fail-closed
WORDPDF_API_KEY: "${WORDPDF_API_KEY:?WORDPDF_API_KEY not set: put it in .env (openssl rand -hex 32)}"
# документация в прод-интернете не нужна (в dev/java -jar остаётся включена)
SPRINGDOC_API_DOCS_ENABLED: "false"
SPRINGDOC_SWAGGER_UI_ENABLED: "false"
# лимиты входа (байты/страницы); значение из .env, иначе дефолты ядра;
# интерполяция :- подставляет и на unset, и на пустое — пустая строка
# сломала бы binding long/int
WORDPDF_MAX_BYTES: "${WORDPDF_MAX_BYTES:-20971520}"
WORDPDF_MAX_PAGES: "${WORDPDF_MAX_PAGES:-1000}"
web:
build: ./wordpdf-web
restart: unless-stopped
# См. комментарий у app: дубль HEALTHCHECK из wordpdf-web/Containerfile
healthcheck:
test: ["CMD-SHELL", "http_proxy= https_proxy= wget -qO /dev/null http://127.0.0.1/ || exit 1"]
interval: 10s
timeout: 3s
start_period: 10s
gateway:
image: docker.io/library/nginx:alpine
volumes:
- ./gateway/nginx.conf:/etc/nginx/conf.d/default.conf:ro
ports: ["9010:80"]
depends_on:
app:
condition: service_healthy
web:
condition: service_healthy
restart: unless-stopped
networks:
# Подсеть зафиксирована намеренно: nginx в gateway/nginx.conf резолвит app/web
# через aardvark-dns на шлюзе сети (10.113.0.1), адрес обязан быть
# предсказуемым. Отличается от прод-10.112.0.0/24, чтобы стенды не конфликтовали.
default:
ipam:
config:
- subnet: 10.113.0.0/24
gateway: 10.113.0.1
-24
View File
@@ -1,24 +0,0 @@
# Dev-стенд без ключа доступа: WORDPDF_API_KEY не задан → wordpdf.api-key пуст
# → ApiKeyFilter прозрачен, springdoc включён. Проект wordpdf-dev — собственные
# образы/контейнеры, с прод-запуском (wordpdf-prod, :9010) не конфликтует.
# Запуск: docker compose -f docker-compose.dev.yml up --build
# Вход: http://<LAN-IP хоста>:9011 (доступен из локальной сети; hostname -I на хосте)
name: wordpdf-dev
services:
app:
build: .
restart: unless-stopped
web:
build: ./wordpdf-web
restart: unless-stopped
gateway:
image: nginx:alpine
volumes:
- ./gateway/nginx.conf:/etc/nginx/conf.d/default.conf:ro
ports: ["9011:80"]
depends_on:
app:
condition: service_healthy
web:
condition: service_healthy
restart: unless-stopped
-30
View File
@@ -1,30 +0,0 @@
name: wordpdf
services:
app:
build: .
restart: unless-stopped
environment:
# без ключа стек не поднимется (:? на пустое/unset) — прод fail-closed
WORDPDF_API_KEY: "${WORDPDF_API_KEY:?WORDPDF_API_KEY not set: put it in .env (openssl rand -hex 32)}"
# документация в прод-интернете не нужна (в dev/java -jar остаётся включена)
SPRINGDOC_API_DOCS_ENABLED: "false"
SPRINGDOC_SWAGGER_UI_ENABLED: "false"
# лимиты входа (байты/страницы); значение из .env, иначе дефолты ядра;
# интерполяция :- подставляет и на unset, и на пустое — пустая строка
# сломала бы binding long/int
WORDPDF_MAX_BYTES: "${WORDPDF_MAX_BYTES:-20971520}"
WORDPDF_MAX_PAGES: "${WORDPDF_MAX_PAGES:-1000}"
web:
build: ./wordpdf-web
restart: unless-stopped
gateway:
image: nginx:alpine
volumes:
- ./gateway/nginx.conf:/etc/nginx/conf.d/default.conf:ro
ports: ["9010:80"]
depends_on:
app:
condition: service_healthy
web:
condition: service_healthy
restart: unless-stopped
+15 -5
View File
@@ -6,10 +6,20 @@ server {
# авторитетный лимит — свойство wordpdf.max-bytes (env WORDPDF_MAX_BYTES, # авторитетный лимит — свойство wordpdf.max-bytes (env WORDPDF_MAX_BYTES,
# дефолт 20 MiB). Без директивы upload режется HTML-413 от шлюза до бэкенда. # дефолт 20 MiB). Без директивы upload режется HTML-413 от шлюза до бэкенда.
client_max_body_size 100m; client_max_body_size 100m;
location /api/ { proxy_pass http://app:8080; } # app/web резолвятся aardvark-dns, который сидит на шлюзе сети стека
location /swagger-ui { proxy_pass http://app:8080; } # (подсеть зафиксирована в compose.yml / compose.dev.yml, адрес стабилен).
location /v3/api-docs { proxy_pass http://app:8080; } # Статический proxy_pass резолвит имя ровно один раз при старте nginx:
# если gateway поднялся раньше app (так стартует podman-restart.service при
# загрузке хоста), апстрим навсегда оставался мёртвым — 502 до перезапуска
# gateway. resolver + переменная заставляют резолвить на каждый запрос.
resolver 10.113.0.1 valid=10s ipv6=off;
set $upstream_app http://app:8080;
set $upstream_web http://web:80;
location /api/ { proxy_pass $upstream_app; }
location /swagger-ui { proxy_pass $upstream_app; }
location /v3/api-docs { proxy_pass $upstream_app; }
# открыт фильтром приложения (wordpdf.api-key его не проверяет) — мониторинг/HEALTHCHECK снаружи # открыт фильтром приложения (wordpdf.api-key его не проверяет) — мониторинг/HEALTHCHECK снаружи
location /actuator { proxy_pass http://app:8080; } location /actuator { proxy_pass $upstream_app; }
location / { proxy_pass http://web:80; } location / { proxy_pass $upstream_web; }
} }
+1 -1
View File
@@ -41,7 +41,7 @@
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency> </dependency>
<!-- /actuator/health — open-эндпоинт для Docker HEALTHCHECK --> <!-- /actuator/health — open-эндпоинт для HEALTHCHECK контейнера -->
<dependency> <dependency>
<groupId>org.springframework.boot</groupId> <groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId> <artifactId>spring-boot-starter-actuator</artifactId>
@@ -15,7 +15,7 @@ import java.security.MessageDigest;
/** /**
* Единственная граница доступа: заголовок {@value #HEADER} обязан совпадать с * Единственная граница доступа: заголовок {@value #HEADER} обязан совпадать с
* {@code wordpdf.api-key}. Пустое свойство = фильтрация выключена (dev/тесты). * {@code wordpdf.api-key}. Пустое свойство = фильтрация выключена (dev/тесты).
* Наружу без ключа открыты {@code /actuator/**} (им дышит Docker HEALTHCHECK) * Наружу без ключа открыты {@code /actuator/**} (им дышит HEALTHCHECK контейнера)
* и документация springdoc ({@code /swagger-ui*}, {@code /v3/api-docs*}) — * и документация springdoc ({@code /swagger-ui*}, {@code /v3/api-docs*}) —
* браузер не может положить ключ в заголовок при загрузке UI; ключ обязателен * браузер не может положить ключ в заголовок при загрузке UI; ключ обязателен
* для всего остального (фактически {@code /api/**}). Ответ 401 пишется здесь же, * для всего остального (фактически {@code /api/**}). Ответ 401 пишется здесь же,
@@ -30,7 +30,7 @@ final class ApiKeyFilter extends OncePerRequestFilter {
static final String HEADER = "X-API-Key"; static final String HEADER = "X-API-Key";
/** Открытые пути без ключа: actuator (Docker HEALTHCHECK) и springdoc-документация. */ /** Открытые пути без ключа: actuator (HEALTHCHECK контейнера) и springdoc-документация. */
private static final String[] OPEN_PREFIXES = {"/actuator/", "/swagger-ui", "/v3/api-docs"}; private static final String[] OPEN_PREFIXES = {"/actuator/", "/swagger-ui", "/v3/api-docs"};
/** null — аутентификация выключена. */ /** null — аутентификация выключена. */
@@ -66,7 +66,7 @@ final class ApiKeyFilter extends OncePerRequestFilter {
* Путь приложения без forwarded-префикса: при * Путь приложения без forwarded-префикса: при
* server.forward-headers-strategy=framework заголовок X-Forwarded-Prefix * server.forward-headers-strategy=framework заголовок X-Forwarded-Prefix
* становится contextPath, и getRequestURI() возвращает URI уже с ним — * становится contextPath, и getRequestURI() возвращает URI уже с ним —
* матч по сырому URI теряет /actuator/ (Docker HEALTHCHECK получил бы 401). * матч по сырому URI теряет /actuator/ (HEALTHCHECK контейнера получил бы 401).
*/ */
private static String path(HttpServletRequest request) { private static String path(HttpServletRequest request) {
return request.getRequestURI().substring(request.getContextPath().length()); return request.getRequestURI().substring(request.getContextPath().length());
@@ -15,7 +15,7 @@ spring.servlet.multipart.file-size-threshold=100MB
wordpdf.convert-timeout=2m wordpdf.convert-timeout=2m
# Ключ доступа (заголовок X-API-Key). Пусто = аутентификация выключена # Ключ доступа (заголовок X-API-Key). Пусто = аутентификация выключена
# (dev: java -jar / тесты). В docker-compose задан ${WORDPDF_API_KEY:?} — fail-closed. # (dev: java -jar / тесты). В compose.yml задан ${WORDPDF_API_KEY:?} — fail-closed.
wordpdf.api-key= wordpdf.api-key=
# Работа за префикс-срезающим прокси (прод: наружный nginx срезает # Работа за префикс-срезающим прокси (прод: наружный nginx срезает
@@ -81,7 +81,7 @@ class ApiKeyFilterTest {
@Test @Test
void healthOpenWithoutKey() throws Exception { void healthOpenWithoutKey() throws Exception {
// Docker HEALTHCHECK дышит /actuator/** без ключа — иначе контейнер // HEALTHCHECK контейнера дышит /actuator/** без ключа — иначе контейнер
// никогда не станет healthy // никогда не станет healthy
mockMvc.perform(get("/actuator/health")) mockMvc.perform(get("/actuator/health"))
.andExpect(status().isOk()); .andExpect(status().isOk());
+22
View File
@@ -0,0 +1,22 @@
# FROM с полным именем реестра: podman не резолвит short-name без
# unqualified-search-registries в /etc/containers/registries.conf.
FROM docker.io/library/node:24-alpine AS build
# buildah подмешивает прокси-переменные хоста в каждый RUN (ENV не перебивает),
# а 127.0.0.1 внутри контейнера недостижим — npm ci падает с ECONNREFUSED на
# 127.0.0.1:proxy. Контейнер в сеть ходит напрямую, потому обнуляем прокси
# на самой команде.
WORKDIR /build
COPY package.json package-lock.json ./
RUN HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= ALL_PROXY= all_proxy= npm ci
COPY . .
# base для сборки SPA под префиксом: прод pjandro.ru — /pdf-converter/
# (compose прод-запуска передаёт arg); дефолт '/' — standalone
ARG VITE_BASE=/
ENV VITE_BASE=${VITE_BASE}
RUN npm run build
FROM docker.io/library/nginx:alpine
COPY --from=build /build/dist /usr/share/nginx/html
# прокси-переменные хоста подмешиваются в HEALTHCHECK-шелл — обнуляем на команде
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s \
CMD http_proxy= https_proxy= wget -qO /dev/null http://127.0.0.1/ || exit 1
-21
View File
@@ -1,21 +0,0 @@
FROM node:24-alpine AS build
# docker-прокси из ~/.docker/config.json BuildKit подмешивает в каждый RUN
# (ENV не перебивает), а 127.0.0.1 внутри контейнера недостижим — npm ci падает
# с ECONNREFUSED. Контейнер в сеть ходит напрямую, потому обнуляем прокси
# на самой команде.
WORKDIR /build
COPY package.json package-lock.json ./
RUN HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= ALL_PROXY= all_proxy= npm ci
COPY . .
# base для сборки SPA под префиксом: прод pjandro.ru — /pdf-converter/
# (compose прод-запуска передаёт arg); дефолт '/' — standalone
ARG VITE_BASE=/
ENV VITE_BASE=${VITE_BASE}
RUN npm run build
FROM nginx:alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /build/dist /usr/share/nginx/html
# прокси из docker-config подмешивается в HEALTHCHECK-шелл — обнуляем на команде
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s \
CMD http_proxy= https_proxy= wget -qO /dev/null http://127.0.0.1/ || exit 1
+1 -1
View File
@@ -2,7 +2,7 @@
SPA-фронт конвертера Word → PDF: React 19 + TypeScript + Vite + Tailwind CSS v4. SPA-фронт конвертера Word → PDF: React 19 + TypeScript + Vite + Tailwind CSS v4.
В Maven-сборку не входит; деплоится отдельным nginx-контейнером (см. В Maven-сборку не входит; деплоится отдельным nginx-контейнером (см.
`Dockerfile`/`nginx.conf` и корневой `docker-compose.yml`). `Containerfile`/`nginx.conf` и корневой `compose.yml`).
## Dev ## Dev