Instalar con Docker Compose#

La instalación de referencia de Empowerment Center 8: un servidor con Docker que ejecuta la BD propia, el backend y el frontal, todo descrito en deploy/compose.yaml. Es la misma instalación con que se prueba cada versión.

Antes de empezar#

Docker 24 o posterior con Docker Compose v2 (docker compose version).
La carpeta deploy/ de la distribución de ECenter, con compose.yaml, ecenter.env.example y db-init/.
Las imágenes ecenter/backend:8.0.0 y ecenter/frontend:8.0.0, o las fuentes para construirlas.
openssl para generar la clave de los secretos.

Los comandos de esta página se escriben desde la carpeta que contiene deploy/. Si trabaja dentro de deploy/, quite -f deploy/compose.yaml de cada uno.

Qué arranca#

Servicio	Imagen	Qué hace	Memoria por defecto
`db`	`postgis/postgis:18-3.6-alpine`	La BD propia. Sus datos van en el volumen `db-data`. No se publica.	1 GB
`backend`	`ecenter/backend:8.0.0`	El servidor de ECenter. Arranca cuando la BD responde. No se publica.	4 GB
`frontend`	`ecenter/frontend:8.0.0`	La aplicación web y el proxy hacia el backend. Es lo único que se publica, en el puerto `ECENTER_HTTP_PORT` (8080).	256 MB
`chromium`	`chromedp/headless-shell`	El navegador sin interfaz. Solo con el perfil `render`.	2 GB
`valhalla`	`ghcr.io/valhalla/valhalla-scripted:3.9.0`	El motor de rutas. Solo con el perfil `routing`. Su grafo va en el volumen `routing-data`.	6 GB

Todos se reinician solos si se caen (restart: unless-stopped) y sus registros rotan (véase Registros y limpieza).

1. Preparar las imágenes#

Si las imágenes vienen de un registro, indíquelo en el fichero de configuración del paso 2:

ECENTER_BACKEND_IMAGE=registro.example.org/ecenter/backend:8.0.0
ECENTER_FRONTEND_IMAGE=registro.example.org/ecenter/frontend:8.0.0

Si las construye desde las fuentes, hágalo después del paso 2 (Compose necesita el fichero .env para leer compose.yaml):

docker compose -f deploy/compose.yaml build

También se pueden construir una a una, desde la raíz del repositorio:

docker build -t ecenter/backend:8.0.0 backend
docker build --build-context manuales=manuales -t ecenter/frontend:8.0.0 frontend

La imagen del frontal lleva los manuales en /ayuda/ y los construye con ella: el directorio manuales/ es un segundo contexto de construcción, manuales, que deploy/compose.yaml da con additional_contexts y docker build, con --build-context. Véase Los manuales en /ayuda/.

2. Preparar la configuración#

Copie el ejemplo y protéjalo:

cp deploy/ecenter.env.example deploy/.env
chmod 600 deploy/.env

Genere la clave de los secretos:
```
openssl rand -base64 32
```

Abra deploy/.env y rellene al menos estas variables:

Variable	Qué poner
`ECENTER_DB_PASSWORD`	Una contraseña larga para la BD propia. La usan el contenedor de la BD y el backend.
`ECENTER_SECRETS_KEY`	La clave que acaba de generar.
`ECENTER_PUBLIC_URL`	La dirección con que entrarán los usuarios, sin barra final: `https://ecenter.example.org`.
`ECENTER_ADMIN_LOGIN`	El login del primer administrador.
`ECENTER_ADMIN_PASSWORD`	Su contraseña: al menos 10 caracteres.
`TZ`	La zona horaria de la instalación: `Europe/Madrid`.

Si ya tiene los datos del correo, descomente y rellene las variables SPRING_MAIL_* (véase Correo y avisos). Si no, déjelas comentadas: una variable vacía cuenta como definida, y SPRING_MAIL_HOST= sin valor no es lo mismo que no ponerla.
Si delante del frontal va a haber otro proxy que termina TLS, ponga ECENTER_BEHIND_PROXY=on (véase El proxy inverso y TLS).

Atención

Guarde ECENTER_SECRETS_KEY fuera del servidor, con la misma protección que las copias de la BD. Cifra las contraseñas de las conexiones a las BD de los clientes y la clave con que ECenter firma sus propios tokens. Si se pierde, hay que volver a escribir la contraseña de cada conexión. Nunca suba deploy/.env a un repositorio.

Lo que no cabe en una variable (los proveedores de identidad, el mapa base, los enlaces de la pantalla de entrada) va en un fichero application.yml propio. Véase Configuración.

3. Arrancar#

docker compose -f deploy/compose.yaml up -d

La primera vez:

El contenedor db crea la base de datos ecenter, el usuario ecenter como su dueño (sin ser superusuario y con la contraseña de ECENTER_DB_PASSWORD) y las extensiones postgis y pg_trgm. El superusuario de la imagen (postgres) se queda sin contraseña: solo entra desde dentro del contenedor.
Cuando la BD responde, arranca el backend, que crea el esquema de ECenter (uno o dos minutos) y, como la BD no tiene usuarios, el primer administrador.
Arranca el frontal.

Siga el arranque con:

docker compose -f deploy/compose.yaml ps
docker compose -f deploy/compose.yaml logs -f backend

Los servicios están listos cuando ps los enseña como healthy. En el registro del backend verá, entre otras, estas líneas:

Creado el administrador inicial '…'.
Instalación <identificador>: No hay ninguna licencia instalada…. Ese identificador es el que pedirá Action Ware para emitir la licencia.

Nota

El script de db-init/ solo se ejecuta con el volumen db-data vacío. Si cambia ECENTER_DB_PASSWORD después del primer arranque, la BD conserva la contraseña de antes y el backend no podrá entrar. Para cambiarla, hágalo también en la BD: docker compose -f deploy/compose.yaml exec db psql -U postgres -c "ALTER ROLE ecenter PASSWORD 'nueva-clave'".

4. Comprobar la salud#

Servicio	Cómo lo comprueba Compose
`db`	`pg_isready` cada 5 s.
`backend`	`GET /api/about` cada 10 s, que es público y no necesita sesión ni licencia. Le da 60 s de margen al arrancar.
`frontend`	Lee su `index.html` cada 10 s.

Desde fuera, una petición a la dirección pública comprueba el camino entero (frontal y backend):

curl -s https://ecenter.example.org/api/about

La respuesta trae el producto y la versión (8.0.0).

Para un orquestador hay además las sondas /actuator/health/liveness y /actuator/health/readiness del backend. No van por el frontal: se piden directamente al backend o, si activa el puerto de gestión, a ese puerto. Que una BD de cliente no responda no saca al backend del balanceador: es una alerta de la consola, no un fallo de salud.

5. Entrar#

Abra ECENTER_PUBLIC_URL en el navegador.
Entre con el login y la contraseña del primer administrador.
Como no hay licencia, la aplicación le lleva a Administración › Licencia, con el identificador de la instalación. Siga La licencia.
Con la licencia instalada, continúe con Primer arranque y puesta en marcha.

Variables que pone `compose.yaml`#

deploy/compose.yaml da al backend y al frontal lo que los une entre sí. No hace falta tocarlas mientras use esa instalación:

Variable	Valor	Para qué
`ECENTER_DB_URL`, `ECENTER_DB_USER`	`jdbc:postgresql://db:5432/ecenter`, `ecenter`	El backend llega a la BD propia.
`ECENTER_INSTANCE_NAME`	`ecenter-1`	El nombre de la instancia en las alertas y las ejecuciones. Es fijo porque el nombre del contenedor cambia cada vez que se vuelve a crear.
`SERVER_FORWARD_HEADERS_STRATEGY`	`framework`	El backend lee de las cabeceras `X-Forwarded-*` del frontal el esquema, el nombre y la dirección originales.
`ECENTER_EMBEDDING_INDEX_LOCATION`	`http://frontend:8080/index.html`	La página que el backend sirve a la incrustación.
`ECENTER_RENDER_BROWSER_URL`, `ECENTER_RENDER_FRONTEND_URL`	`http://chromium:9222`, `http://frontend:8080`	Dónde están el navegador sin interfaz y el frontal por la red interna.
`ECENTER_MAPS_ROUTING_URL`	`http://valhalla:8002`	Dónde está el motor de rutas.
`ECENTER_BACKEND_URL` (frontal)	`http://backend:8080`	Dónde está el backend.

El backend recibe además todas las variables que defina en deploy/.env. Al pararlo, Compose le da 45 s para terminar ordenadamente las peticiones y los trabajos en curso.

Otro orquestador#

Con Kubernetes u otro orquestador se usan las mismas imágenes. Traslade de deploy/compose.yaml:

las variables de la tabla anterior, con los nombres de sus servicios;
un límite de memoria para cada contenedor: la JVM del backend toma el 75 % del suyo, y sin límite tomaría el 75 % del nodo;
el resolutor DNS del frontal (ECENTER_RESOLVER, que por defecto es el de Docker, 127.0.0.11): el del clúster;
para el navegador sin interfaz, un volumen en memoria montado en /dev/shm (un emptyDir con medium: Memory);
y las sondas: liveness y readiness del backend, en su puerto o en el de gestión.

Problemas frecuentes#

Síntoma	Causa	Qué hacer
`Falta ECENTER_DB_PASSWORD en .env` al arrancar.	El fichero `.env` no está junto a `compose.yaml` o no define la variable.	Cree `deploy/.env` (paso 2).
El backend se reinicia y su registro dice que falta la clave de cifrado de secretos.	`ECENTER_SECRETS_KEY` vacía o que no son 32 bytes en Base64.	Genérela con `openssl rand -base64 32`.
El backend dice que faltan `ECENTER_DB_URL`, `ECENTER_DB_USER` o `ECENTER_DB_PASSWORD`.	Arranca fuera de `compose.yaml` sin ellas.	Defínalas (véase Variables de entorno).
`No hay usuarios y no se ha configurado ecenter.security.bootstrap-admin: nadie podrá iniciar sesión…`	Faltan `ECENTER_ADMIN_LOGIN` o `ECENTER_ADMIN_PASSWORD` en el primer arranque.	Añádalas y vuelva a crear el backend: `docker compose -f deploy/compose.yaml up -d backend`.
El backend no termina de arrancar y su registro dice «La contraseña debe tener al menos 10 caracteres».	La de `ECENTER_ADMIN_PASSWORD` es más corta (o pasa de 72 bytes).	Corríjala y vuelva a crear el backend.
La migración se para con un mensaje sobre `pg_trgm` o `GRANT CREATE ON DATABASE`.	Una BD propia preparada a mano sin la extensión ni el permiso.	Cree la extensión como superusuario o dé el permiso (véase Requisitos).