# 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. Crear base y usuario en PostgreSQL 17. 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 |
| 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; actualmente no existen migraciones SQL de negocio. La base debe existir antes del arranque. La separación de roles de migración/ejecución queda pendiente de T03/T07.

## Ejecución desde el IDE

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

- 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.