188 lines
12 KiB
Markdown
188 lines
12 KiB
Markdown
# Docker con PostgreSQL externo
|
||
|
||
## Preparación
|
||
|
||
Requiere Docker con contenedores Linux y Compose v2. La imagen compila con JDK 21 y ejecuta con JRE 21; no requiere Java/Maven en el anfitrión. PostgreSQL y el proveedor JWT son externos.
|
||
|
||
1. Usar la base externa existente. Actualmente server02:30432/orquestador ejecuta PostgreSQL 9.6.2 y requiere el perfil postgres96; se conserva PostgreSQL 17 como alternativa futura. Permitir conexión desde Docker según firewall, listen_addresses y pg_hba.conf del servidor.
|
||
2. Copiar `.env.example` a `.env`, sin sobrescribir uno ya configurado.
|
||
3. Completar DB_URL, DB_USERNAME, DB_PASSWORD, JWT_ISSUER_URI, JWT_JWK_SET_URI y JWT_AUDIENCE.
|
||
|
||
| Variable | Uso |
|
||
|---|---|
|
||
| DB_URL | JDBC de la base externa: jdbc:postgresql://db.interna:5432/orquestador |
|
||
| SPRING_PROFILES_ACTIVE | postgres96 para la instancia disponible; selecciona PostgreSQLLegacyDialect de Hibernate |
|
||
| DB_USERNAME / DB_PASSWORD | Credenciales del usuario de la base existente |
|
||
| JWT_ISSUER_URI | Issuer exacto de los tokens |
|
||
| JWT_JWK_SET_URI | Endpoint JWKS correspondiente, accesible desde Docker |
|
||
| JWT_AUDIENCE | Audiencia esperada |
|
||
| APP_PORT | Puerto publicado; predeterminado 8080 |
|
||
| APP_BIND_ADDRESS | Interfaz publicada; predeterminado 127.0.0.1; usar 0.0.0.0 para acceso remoto |
|
||
|
||
Si PostgreSQL corre en el anfitrión, usar `jdbc:postgresql://host.docker.internal:5432/orquestador`. Compose incluye host-gateway para Linux. `localhost` dentro del contenedor apunta al propio contenedor. La misma consideración aplica al endpoint JWKS; conservar el issuer exacto de los tokens.
|
||
|
||
Si el proveedor requiere TLS, añadir los parámetros JDBC requeridos, por ejemplo `?sslmode=verify-full`; montar el certificado raíz y configurar `sslrootcert` cuando corresponda. Contraseñas con `$` pueden escribirse entre comillas simples en `.env` para conservar su valor literal.
|
||
|
||
## Levantar y comprobar
|
||
|
||
```powershell
|
||
Copy-Item .env.example .env
|
||
# Editar .env con valores del entorno externo.
|
||
docker compose config --quiet
|
||
docker compose up --build -d
|
||
docker compose ps
|
||
docker compose logs -f orquestador
|
||
curl.exe --fail http://localhost:8080/actuator/health/readiness
|
||
curl.exe --fail http://localhost:8080/actuator/health/liveness
|
||
```
|
||
|
||
En Linux/macOS usar `cp` y `curl`. Compose carga `.env` y pasa explícitamente las variables al contenedor. Las variables exportadas en la sesión tienen precedencia. `.env` está excluido de la imagen.
|
||
|
||
Salud debe devolver HTTP 200 y status UP. Readiness comprueba PostgreSQL; liveness no depende de proveedores. El healthcheck interno usa 8080 aunque APP_PORT cambie. Otra ruta sin token debe devolver 401. No hay endpoints de negocio implementados todavía.
|
||
|
||
El build ejecuta `package`, incluyendo pruebas unitarias. La suite de integración se ejecuta fuera del build con `clean verify` y Docker disponible. No se monta el socket Docker dentro del build. Se requiere acceso a Maven Central, Docker Hub y repositorios Ubuntu durante la construcción.
|
||
|
||
## Operación
|
||
|
||
```powershell
|
||
docker compose up --build -d # Reconstruir tras cambios de código
|
||
docker compose up -d # Aplicar cambios en .env
|
||
docker compose stop # Detener el servicio
|
||
docker compose down # Eliminar contenedor y red de Compose
|
||
```
|
||
|
||
Estos comandos no administran la base externa. Flyway permanece habilitado y aplicará las migraciones incluidas al arrancar; se incluyen V1/V2 del modelo T03. La base debe existir antes del arranque. Las credenciales de migración pueden separarse según las instrucciones al final de este documento.
|
||
|
||
## Ejecución desde el IDE
|
||
|
||
Para el servidor actual configurar `DB_URL=jdbc:postgresql://server02:30432/orquestador`, `DB_USERNAME=pgadmin` y `SPRING_PROFILES_ACTIVE=postgres96`; la contraseña sólo en el entorno local. El argumento de perfil local del ejemplo siguiente debe reemplazarse por postgres96 cuando se use PostgreSQL 9.6.
|
||
|
||
Configurar JDK 21 y las seis variables DB/JWT en la sesión o Run Configuration. Spring Boot no importa `.env` automáticamente fuera de Compose.
|
||
|
||
```powershell
|
||
.\mvnw.cmd clean verify
|
||
.\mvnw.cmd spring-boot:run '-Dspring-boot.run.profiles=local'
|
||
```
|
||
|
||
## Diagnóstico
|
||
|
||
### Prueba de compatibilidad con PostgreSQL 9.6
|
||
|
||
Con JDK 21 y las seis variables DB/JWT exportadas, ejecutar:
|
||
|
||
```powershell
|
||
.\mvnw.cmd clean verify -Ppostgres96-check
|
||
```
|
||
|
||
La prueba arranca el checkout local en 127.0.0.1 con puerto aleatorio y cierra el contexto al terminar. Fuerza PostgreSQL default_transaction_read_only=on, desactiva el inicializador automático Flyway y SQL init sólo en la prueba, conserva ddl-auto=validate y ejecuta Flyway.validate() sin crear schemas ni migrar. Comprueba versión 9.6, dialecto legacy, health/readiness/liveness UP y 401 sin token. No corre en el build normal ni depende de Docker. No sustituye pruebas de migraciones, DML/concurrencia ni Testcontainers de T03.
|
||
|
||
Hibernate community-dialects se alinea al BOM (7.4.13.Final). Flyway 12.4.0 detecta 9.6 y valida; informa que esa versión queda fuera de soporte comunitario de Redgate. La compatibilidad verificada se limita al arranque/conexión actual, todavía sin entidades ni migraciones de negocio.
|
||
|
||
Para automatizar la comprobación del despliegue con JDK 21:
|
||
|
||
```powershell
|
||
.\mvnw.cmd clean verify -Pdeployment-smoke '-Dsmoke.baseUrl=http://server02:8787'
|
||
```
|
||
|
||
Son cinco pruebas de sólo lectura; resultados en `target/failsafe-reports`. El servicio debe estar iniciado con su PostgreSQL externo. La URL es obligatoria; no hay omisión silenciosa por falta de conectividad. El perfil no despliega la aplicación ni cambia la configuración del servidor. El build normal no ejecuta este smoke remoto, para no depender de la red privada desde CI.
|
||
|
||
- Variable faltante: completar el valor requerido en `.env`.
|
||
- Conexión rechazada/timeout: revisar DNS, puerto, firewall y acceso desde Docker; no usar localhost para el anfitrión.
|
||
- Error de autenticación PostgreSQL: comprobar usuario, contraseña y permisos.
|
||
- Readiness DOWN/unhealthy: consultar logs y conectividad PostgreSQL. Un healthcheck fallido marca el estado, no reinicia automáticamente.
|
||
- JWT inválido: revisar issuer/audiencia y acceso a JWKS.
|
||
- Fallo de build: comprobar acceso a los repositorios de dependencias.
|
||
|
||
Registrar evidencia en PROGRESS. No considerar verificado el arranque si no se ejecutó contra Docker y PostgreSQL externo.
|
||
|
||
## Pruebas T03 sobre PostgreSQL externo
|
||
|
||
Con JDK 21, sin Docker local, usar exclusivamente la base aislada creada para
|
||
pruebas. Las credenciales se suministran como variables de proceso:
|
||
|
||
```powershell
|
||
$env:MIGRATION_TEST_DB_URL='jdbc:postgresql://server02:30432/orquestador_test'
|
||
$env:MIGRATION_TEST_DB_USER='pgadmin'
|
||
# Establecer MIGRATION_TEST_DB_PASSWORD mediante el entorno local.
|
||
.\mvnw.cmd --batch-mode --no-transfer-progress clean verify -Pmigration-tests-external
|
||
```
|
||
|
||
El perfil no utiliza DB_URL y rechaza cualquier base distinta de orquestador_test.
|
||
Crea un esquema t03_<UUID>, ejecuta las migraciones y lo elimina al finalizar.
|
||
No toca otros esquemas. Crea un rol NOLOGIN temporal dentro de una transacción
|
||
revertida. Requiere permiso de crear esquemas y roles. Si el proceso se interrumpe
|
||
abruptamente, un administrador puede revisar el esquema temporal que haya quedado;
|
||
no borrar otros esquemas ni ejecutar Flyway clean.
|
||
|
||
Sin ese perfil, verify requiere Docker y ejecuta la misma suite con Testcontainers
|
||
postgres:9.6.24. No hay fallback silencioso ni pruebas omitidas sin Docker.
|
||
El perfil deployment-smoke agrega comprobaciones HTTP; postgres96-check agrega
|
||
una comprobación de arranque de solo lectura, que exige migraciones ya aplicadas.
|
||
Ambos conservan los IT normales y pueden combinarse con migration-tests-external.
|
||
|
||
## Esquema y credenciales de migración
|
||
|
||
Flyway aplica V1/V2 al esquema orchestrator. DB_MIGRATION_USERNAME y
|
||
DB_MIGRATION_PASSWORD permiten separar migrador de usuario de aplicación; si se
|
||
omiten, se reutilizan las credenciales DB_USERNAME/DB_PASSWORD. Para aplicar
|
||
mínimo privilegio seguir [roles y migraciones](../src/main/resources/db/migration/README.md).
|
||
|
||
El historial nuevo es orchestrator.flyway_schema_history. El arquetipo anterior
|
||
no incluía SQL de negocio. Si existe historial en public con migraciones reales,
|
||
detener la actualización y preparar su traslado explícito; no usar baseline ni
|
||
repair para ocultarlo. Esta implementación no despliega ni migra automáticamente
|
||
el servicio remoto: las migraciones se ejecutarán cuando se arranque el nuevo JAR.
|
||
|
||
## Administración interna T06
|
||
|
||
El JAR incluye el validador y servicios internos de flujos, sin nuevas rutas
|
||
administrativas. Ver [publicación y catálogo](FLOW_PUBLICATION.md) para el alcance,
|
||
roles, canonicalización y orden de bloqueos. T07 incorporará el wiring y acceso
|
||
REST con identidad verificada; T06 no configura contratos reales de proveedores.
|
||
|
||
El perfil migration-tests-external ejecuta tanto DatabaseMigrationIT como
|
||
FlowPublicationIT. Esta última crea y elimina únicamente su esquema t06_<UUID>
|
||
en orquestador_test, incluyendo un trigger de fallo de auditoría exclusivo de prueba.
|
||
La configuración de esquema normal del servicio sigue siendo orchestrator.
|
||
|
||
T07: antes de habilitar FLOW_ADMIN_ENABLED revisar SECURITY.md. Un runtime pgadmin
|
||
será rechazado; provisionar rol restringido y separar las credenciales Flyway.
|
||
ADMIN_BUSINESS_SCOPES vacío deniega administración. JWT_BUSINESS_SCOPE_CLAIM debe
|
||
coincidir con el claim firmado por Keycloak; el valor por defecto es business_scope.
|
||
|
||
T08: REQUEST_API_ENABLED=true habilita creación/consulta, independientemente de
|
||
FLOW_ADMIN_ENABLED. Se exige rol DB restringido también con administración apagada.
|
||
Provisionar y activar un tipo antes de crear; REQUESTS.md documenta respuestas,
|
||
reintentos y pruebas. Un replay POST trae revisión original; refrescar con GET para
|
||
obtener el estado/ETag actual antes de aceptar futuros eventos.
|
||
|
||
T09: REQUEST_API_ENABLED habilita también POST de eventos. Conservar Idempotency-Key,
|
||
cuerpo e If-Match originales al reintentar un envío sin respuesta. GET de solicitud
|
||
muestra revisión/ejecución activa. Hasta implementar T10, PENDING no se procesa y GET
|
||
de ejecución no está disponible. Ver EVENTS.md; no invocar endpoints de proveedores.
|
||
|
||
T10: aplicar V3 con usuario de migraciones antes de habilitar WORKER_ENABLED.
|
||
GET de ejecución se habilita con REQUEST_API_ENABLED. Revisar WORKER.md para
|
||
leases, checkpoints, apagado y recuperación. Dejar worker apagado en flujos con
|
||
integraciones hasta configurar adapters T11. Defaults 60 s lease / 15 s renovación;
|
||
los timeouts externos futuros deben ser menores y acotados. No hay retry HTTP T12 aún.
|
||
|
||
## Seguimiento T15
|
||
|
||
Consultar /api/v1/requests/{id}/history como propietario para enlazar correlationId
|
||
con executionId, ruleIds y reasonCodes. Usar nextCursor con los mismos filtros;
|
||
from inclusivo/to exclusivo requieren UTC Z. Consultar OBSERVABILITY.md y
|
||
examples/http/history-operations.http.
|
||
|
||
El operador autorizado consulta Actuator metrics. Vigilar la edad del pendiente,
|
||
leases expirados y RECONCILIATION_REQUIRED; no liberar ni reintentar ciegamente
|
||
escrituras inciertas. Si queue.sample.available=0, los gauges NaN son desconocidos,
|
||
no una cola vacía. No sumar estados DB de réplicas conectadas a la misma base.
|
||
|
||
Al detener, Compose concede 40 s; el worker drena por WORKER_SHUTDOWN_SECONDS (1–20),
|
||
renueva los trabajos vigentes y luego interrumpe. Un trabajo incompleto conserva
|
||
lease/checkpoints: recuperar según T12. Readiness depende de DB; liveness no.
|
||
No cambiar el timeout de HTTP a uno mayor que el lease ni presumir cancelación
|
||
externa al interrumpir. Retención/borrado de auditoría requiere política aprobada
|
||
con procedimiento privilegiado separado, sin borrado automático por runtime.
|