Despliegue con Docker¶

Drovio Server puede desplegarse en un contenedor Docker. Para ello ofrecemos dos imágenes distintas:

Todo en uno: destinada ante todo a la prueba y a la preproducción. Contiene las funcionalidades esenciales de Drovio Server. Todas las dependencias van embebidas y se configuran automáticamente al arrancar el contenedor.
Producción: reservada a los entornos de producción. Drovio Server se apoya en una base de datos gestionada por Docker o externa, y en el almacén de sesiones interno o en un almacén Redis gestionado por Docker o externo.

Imagen Docker	Todo en uno	Producción
Uso	Prueba y preproducción	Producción
Base	Debian 13 (Trixie) slim	Debian 13 (Trixie) slim
Base de datos PostgreSQL	Base PostgreSQL interna	Base PostgreSQL gestionada por Docker o externa, 14 y superior
Almacén de sesiones	Almacén interno	Almacén interno, o almacén Redis gestionado por Docker o externo
Se ejecuta como	`root`	`drovio`, uid 1000

Componentes gestionados por Docker o externos

El término gestionado por Docker designa un componente de Drovio Server pilotado por el plugin docker compose y que vive en la misma red Docker. Los componentes externos son, por el contrario, totalmente independientes: debe entonces facilitar sus datos de conexión mediante las variables de entorno correspondientes.

Ambas imágenes son multiarquitectura: linux/amd64 y linux/arm64 se sirven bajo el mismo nombre, y Docker elige la que corresponde a su máquina. No hay ninguna opción --platform que pasar, ni nombre de imagen propio de una arquitectura.

Requisitos previos¶

Docker Engine 20.10 o superior, para la compatibilidad con las imágenes multiarquitectura.
El plugin docker compose 2.20 o superior para la imagen de producción, que utiliza los perfiles y las dependencias opcionales.

Obtener las imágenes¶

Las imágenes se publican en nuestro registro privado. Solicite las credenciales de su organización a support@drovio.com: recibirá un nombre de usuario y un token, ambos propios de usted y revocables.

Imagen	Referencia
Todo en uno	`registry.gitlab.com/drovio/drovio-server-aio`
Producción	`registry.gitlab.com/drovio/drovio-server`

docker login registry.gitlab.com -u <username> -p <token>
docker pull registry.gitlab.com/drovio/drovio-server:3.6.9

Qué etiqueta utilizar¶

Etiqueta	Designa
`3.6.9`	esa versión exacta, y no se mueve nunca
`3.6`	el último parche de la serie 3.6
`latest`, `stable`	la última versión publicada

Fije una versión completa en producción. Las etiquetas móviles resultan prácticas para una prueba, pero hacen que un docker compose pull pueda traer una nueva versión menor sin que usted lo haya decidido.

Acceso de red saliente

Su cortafuegos debe autorizar registry.gitlab.com así como el dominio de almacenamiento de objetos desde el que se descargan las capas de imagen. Un docker login que funciona seguido de un docker pull que se atasca procede casi siempre de ahí.

Instalación sin conexión¶

Si sus servidores no tienen ningún acceso saliente, también entregamos cada versión en forma de archivo comprimido, uno por arquitectura. Solicítelo al soporte y cárguelo después en la máquina de destino:

docker load -i docker-drovio-server-amd64-3.6.9.tar.gz

La imagen así cargada lleva el mismo nombre y la misma etiqueta que la del registro: el resto de esta página se aplica igualmente.

Gestión de los datos persistentes¶

Conforme a los principios de Docker, los datos almacenados en un contenedor son efímeros y no sobreviven a su destrucción. Existen no obstante mecanismos para los datos persistentes, entre ellos los montajes enlazados, que proyectan un archivo o una carpeta del sistema anfitrión dentro del contenedor.

Nuestras imágenes Docker se apoyan en montajes enlazados para tres tipos de datos persistentes:

Datos	Ruta en el contenedor	Afecta a
Archivos de configuración	`/etc/drovio-server`	las dos imágenes
Archivos de registro	`/var/log/drovio-server`	las dos imágenes
Datos de la base de datos	`/opt/drovio-server/data`	la imagen todo en uno

La imagen de producción no incorpora ninguna base de datos. Solo necesita los dos primeros. La ubicación de sus datos depende de la base de datos a la que la apunte, ya se trate de la que docker compose arranca por usted o de su propio servidor.

El secreto JWT vive en la carpeta de configuración

En el primer arranque, el contenedor escribe en settings.conf un secreto JWT propio. Ese secreto firma las sesiones de los usuarios. Eliminar esa carpeta supone perder el secreto: cada usuario tendrá que volver a iniciar sesión.

Propietario de las carpetas, imagen de producción¶

La imagen de producción se ejecuta bajo el usuario sin privilegios drovio, uid y gid 1000. Las dos carpetas en las que escribe deben pertenecerle:

mkdir -p config logs
sudo chown -R 1000:1000 config logs

Sin ello el contenedor se niega a arrancar, e indica qué carpeta hay que corregir.

No haga nunca esto en la carpeta de la base de datos

data/postgresql pertenece al contenedor de base de datos, que se ejecuta bajo su propio usuario. Confiarla al uid 1000 impide que PostgreSQL arranque, con un error de permiso sobre sus propios archivos.

Actualización desde la 3.6.5 o anterior

Las versiones anteriores de esta imagen se ejecutaban bajo root. Las carpetas que crearon en su anfitrión pertenecen por tanto a root. Ejecute el comando chown anterior sobre sus carpetas config y logs existentes antes de arrancar la nueva imagen.

Nada se escribe fuera de esas dos rutas y de la carpeta de trabajo de Vert.x bajo /tmp. El contenedor puede además ejecutarse con un sistema de archivos raíz en solo lectura:

docker run --read-only --tmpfs /tmp ...

Desplegar la imagen todo en uno¶

Cree una carpeta drovio-server y sitúese dentro:

mkdir drovio-server
cd drovio-server

Cree un volumen para la base de datos embebida y lance después el contenedor:

docker volume create drovio-data

docker run --hostname drovio.example.com \
  -p 8090:8090 \
  -v "./config:/etc/drovio-server" \
  -v "./logs:/var/log/drovio-server" \
  -v "drovio-data:/opt/drovio-server/data" \
  --rm -it "registry.gitlab.com/drovio/drovio-server-aio:3.6.9"

Utilice un volumen para la base de datos, no un montaje enlazado

PostgreSQL comprueba que su carpeta de datos pertenece al usuario postgres. Ahora bien, Docker Desktop, tanto en macOS como en Windows, presenta todo lo que se encuentra en un montaje enlazado como perteneciente a root, haga lo que haga. El contenedor no puede arrancar así. Un volumen con nombre no tiene esa limitación, y es de todos modos la manera recomendada de conservar datos de base de datos. La configuración y los registros no se ven afectados y pueden seguir siendo montajes enlazados.

Opción	Descripción
`--hostname`	Fija un nombre de host concreto. Deberá comunicárnoslo después para que generemos sus licencias. Conserve siempre el mismo, ya que las licencias están ligadas a él.
`-p <anfitrión>:<contenedor>`	Publica el puerto del contenedor en el puerto del anfitrión. Aquí se utiliza el puerto `8090`, ya que Drovio Server no activa TLS y todo el tráfico HTTP pasa por ese puerto de forma predeterminada.
`-v "<anfitrión>:<contenedor>"`	Montajes enlazados para los datos persistentes descritos más arriba.
`--rm`	Elimina automáticamente el contenedor al detenerse.
`-it`	Asigna un pseudoterminal conectado a la entrada estándar del contenedor.

El nombre de host solo se escribe una vez

En su primer arranque, el servidor inscribe en su configuración su propia URL, construida a partir del nombre de host que usted le da. Después no se vuelve a calcular, y sus licencias están ligadas a ella. Un contenedor arrancado sin --hostname se negaría a funcionar.

Indique más bien APP_URL si la URL por la que sus usuarios acceden al servidor difiere del nombre de host del contenedor, detrás de un proxy inverso por ejemplo.

Desplegar la imagen de producción¶

La imagen de producción se despliega con el plugin docker compose, la herramienta que sirve para definir y lanzar aplicaciones Docker multicontenedor.

Recuperar los archivos de despliegue¶

Todo lo que necesita para desplegar se encuentra en la propia imagen. Extráigalo en el lugar donde quiera ejecutar el servidor, con las credenciales que le sirvieron para recuperarla:

id=$(docker create registry.gitlab.com/drovio/drovio-server:3.6.9)
docker cp "$id:/opt/drovio-server/bundle/." ./drovio-server
docker rm "$id"
cd drovio-server

Obtiene tres archivos, todos ajustados a la versión que acaba de recuperar:

Archivo	Qué es
`docker-compose.yml`	el despliegue, con o sin base de datos y almacén de sesiones gestionados
`env.example`	los ajustes que debe rellenar
`drovio-server.sql`	el esquema de la base de datos, utilizado en su creación y en las actualizaciones

Su línea image: designa ya la versión exacta de la que lo extrajo.

Ajustes¶

Copie env.example como .env y rellénelo. Dos valores son obligatorios:

DROVIO_HOSTNAME=drovio.example.com
DB_PASSWORD=<generate one>

Genere las contraseñas en lugar de reutilizar alguna, por ejemplo con openssl rand -base64 24. DROVIO_HOSTNAME sigue la misma regla que --hostname más arriba: solo se inscribe en la URL del servidor en el primer arranque.

Componentes gestionados por Docker o externos¶

La elección entre una base de datos y un almacén de sesiones gestionados aquí o facilitados por usted se hace en el arranque, mediante los perfiles. El mismo docker-compose.yml cubre los tres casos:

Comando	Qué lanza
`docker compose --profile bundled-db up`	PostgreSQL gestionado por `docker compose`, almacén de sesiones interno
`docker compose --profile bundled-db --profile redis up`	lo mismo, con un almacén de sesiones Redis gestionado por `docker compose`
`docker compose up`	base de datos externa, rellene `DB_HOST` y las variables asociadas en `.env`

Con el perfil redis, descomente también SS_TYPE, SS_REDIS_CONNECTION_STRINGS, SS_REDIS_MASTER_NAME y SS_REDIS_PASSWORD en su .env.

Componentes gestionados por Docker: pilotados por el plugin docker compose. Todos los contenedores siguen el mismo ciclo de vida y comparten la misma red Docker.
Componentes externos: no se declaran en el archivo docker-compose. Sus datos de conexión deben transmitirse mediante las variables de entorno previstas a tal efecto. En el primer arranque, el archivo de configuración de Drovio Server no existe y se crea con valores predeterminados. Esas variables sirven entonces para sustituir algunos de ellos, lo que permite un primer arranque correcto.

Comprobar que el servidor responde¶

Ambas imágenes exponen un punto de control de estado y declaran un HEALTHCHECK de Docker que se sirve de él. docker ps muestra el contenedor como healthy en cuanto el servidor responde.

curl -f http://drovio.example.com:8090/healthcheck

Variables de entorno¶

Variable de entorno	Campo de configuración
`APP_URL`	`.http.url`
`SS_TYPE`	`.http.session_store.type`
`SS_REDIS_CONNECTION_STRINGS`	`.http.session_store.redis.connections`
`SS_REDIS_MASTER_NAME`	`.http.session_store.redis.master`
`SS_REDIS_PASSWORD`	`.http.session_store.redis.password`
`DB_HOST`	`.database.host`
`DB_PORT`	`.database.port`
`DB_NAME`	`.database.database`
`DB_USER`	`.database.user`
`DB_PASSWORD`	`.database.password`
`DB_MAIN_POOL_SIZE`	`.database.pool_options.main.max_size`
`DB_LICENSING_POOL_SIZE`	`.database.pool_options.licensing.max_size`
`DB_MAIN_IDLE_TIMEOUT`	`.database.pool_options.main.idle_timeout`
`DB_LICENSING_IDLE_TIMEOUT`	`.database.pool_options.licensing.idle_timeout`
`DB_MAIN_CONNECT_TIMEOUT`	`.database.pool_options.main.connect_timeout`
`DB_LICENSING_CONNECT_TIMEOUT`	`.database.pool_options.licensing.connect_timeout`
`DB_POOL_SIZE` (deprecated)	`.database.pool_options.main.max_size`
`DB_NV_POOL_SIZE` (deprecated)	`.database.pool_options.licensing.max_size`
`DB_IDLE_TIMEOUT` (deprecated)	`.database.pool_options.main.idle_timeout`

Las variables de entorno se imponen siempre

Estas variables sobrescriben sistemáticamente los valores del archivo de configuración de Drovio Server en el arranque. Si modifica en los archivos de configuración un valor asociado a una de ellas, debe también retirar esa variable del archivo docker-compose o actualizar su valor antes de reiniciar Drovio Server.

Actualizar¶

Recupere la versión deseada y recree después los contenedores. Su configuración, sus registros y su base de datos viven en los montajes enlazados y no se ven afectados.

docker compose pull
docker compose --profile bundled-db up -d

Actualizar el esquema de la base de datos¶

Una nueva versión puede añadir tablas o columnas. Las dos imágenes no tratan este punto de la misma manera.

Imagen	Qué aplica los cambios de esquema
Todo en uno	el propio contenedor, en cada arranque. Nada que hacer.
Producción	usted, antes de arrancar la nueva imagen.

La imagen de producción nunca toca su esquema. drovio-server.sql solo se ejecuta en la creación de la base de datos, por el contenedor de base de datos de docker compose en su primer arranque, o por usted en su propio servidor. Después no se vuelve a ejecutar.

En una actualización de versión de la imagen de producción:

Extraiga drovio-server.sql de la imagen a la que actualiza, igual que para una primera instalación. El script entregado en una imagen es siempre el que esa imagen espera.
```
id=$(docker create registry.gitlab.com/drovio/drovio-server:3.6.9)
docker cp "$id:/opt/drovio-server/bundle/drovio-server.sql" .
docker rm "$id"
```

Aplíquelo a su base de datos, con los contenedores de Drovio Server detenidos.

psql -h my-database.example.com -U drovio -d drovio -f drovio-server.sql

Arranque la nueva imagen.

El script está escrito para volver a ejecutarse: crea lo que falta y deja el resto en su sitio, de modo que aplicarlo a una base de datos ya actualizada no cambia nada.

Haga antes una copia de seguridad

Haga una copia de seguridad de la base de datos antes de aplicar un script de esquema, sea cual sea la diferencia de versión. Es el único paso de este procedimiento que no tiene marcha atrás.

Todo en uno y versiones mayores de PostgreSQL

La imagen todo en uno no actualiza su clúster de base de datos in situ. Si una nueva versión incorpora una versión mayor de PostgreSQL más reciente, el contenedor se detiene en el arranque con un mensaje explicativo. Exporte sus datos desde la imagen anterior con pg_dumpall y restáurelos después en un volumen nuevo con la nueva.

Migrar desde la imagen production-ready v3.6.5 o anterior¶

Los despliegues production-ready anteriores a la 3.6.6 solo podían cargarse desde un archivo y se ejecutaban como root. Actualizarlos y llevarlos al registro se hace una sola vez, pero el orden que se indica a continuación importa.

Haga una copia de seguridad de su base de datos. El último paso de este procedimiento es el único que no se puede deshacer.
Cambie los permisos de los dos directorios en los que escribe el servidor, y solo de esos. Fueron creados por un contenedor que se ejecutaba como root, y la nueva imagen se ejecuta con uid 1000.
```
sudo chown -R 1000:1000 config logs
```
No la carpeta entera

No ejecute este comando sobre todo su directorio de despliegue. data/postgresql pertenece al contenedor de base de datos, que se ejecuta con su propio usuario, y pasarlo al uid 1000 impide que PostgreSQL arranque.
Apunte al registro. Sustituya la línea image: de su docker-compose.yml, o empiece de nuevo desde el paquete incluido en la nueva imagen. El sufijo de arquitectura desaparece: un despliegue arm64 que usaba drovio/drovio-server-arm64 debe usar ahora drovio/drovio-server.
```
image: 'registry.gitlab.com/drovio/drovio-server:3.6.9'
```
Conserve la contraseña de su base de datos. Si utiliza el docker-compose.yml incluido y su archivo .env, DB_PASSWORD debe contener la contraseña que su base de datos ya usa, la que figura en su archivo compose actual. Una contraseña recién generada dejaría al servidor sin poder conectarse.
Arranque la nueva imagen y compruebe que se levanta antes de seguir adelante.
Aplique el script de esquema si además cambia de versión, tal como se describe más arriba.

Nada más se reescribe

La URL de su servidor y las licencias vinculadas a ella se leen de la configuración que ya tiene. Las reglas sobre --hostname solo se aplican a un primer arranque. Un despliegue existente no se ve afectado por ellas.

Mientras no haya ejecutado el paso 6, volver atrás consiste en restablecer la línea image: anterior, siempre que haya conservado el archivo que cargó originalmente.

Migrar desde una instalación Windows o por paquete Linux¶

Si ha instalado Drovio Server en Windows o mediante el paquete Linux correspondiente a su distribución, y desea pasar a nuestra imagen Docker de producción, solo hay dos elementos que transferir: la base de datos y el directorio de configuración. Nada más hay que recrear, la migración es sencilla.

Tres cosas que conviene saber antes de empezar

La URL de su servidor debe conservarse. Sus licencias están ligadas a esa URL, y por tanto a ese nombre de host.

Su secreto JWT también debe conservarse, de lo contrario las sesiones de los usuarios conectados quedarían invalidadas.

Las variables de .env se aplican en cada arranque, no solo en el primero. Así es como apunta su configuración existente a una nueva base de datos sin editarla a mano.

Haga una copia de seguridad de la base de datos y de todo el directorio de configuración. La restauración del paso 7 es el único paso de este procedimiento que no puede deshacerse.

Detenga el servicio.

LinuxWindows

systemctl stop drovio-server

sc stop drovio-server

Exporte la base de datos. El host, el nombre y el usuario figuran en la sección database de su settings.conf.
```
pg_dump -h localhost -U drovio -d drovio -Fc -f drovio.dump
```
Obtenga los archivos de despliegue como para una primera instalación, y copie después env.example a .env.
Traiga su configuración. Copie settings.conf y admin.properties al directorio config, junto a docker-compose.yml, así como cualquier archivo al que apunten: almacén de claves TLS, almacén SAML, autoridad de certificación LDAP.

LinuxWindows

Las rutas contenidas en settings.conf ya coinciden con lo que espera el contenedor, siendo ambas /etc/drovio-server. Nada que reescribir.

Cada ruta absoluta contenida en settings.conf debe reescribirse, de C:\ProgramData\Drovio\Drovio Server\... a /etc/drovio-server/.... Según lo que utilice, esto puede afectar a http.keystore, users.auth.saml.keystore, users.auth.saml.sp_metadata_path, users.auth.saml.idp_metadata_path y users.auth.ldap.ca_certificate_path.
Entregue los dos directorios al usuario del contenedor, es decir al uid 1000.
```
mkdir -p logs
sudo chown -R 1000:1000 config logs
```
Restaure su exportación, y complete después .env.
Base de datos gestionada por composeSu propia base de datos
Arranque la base de datos sola y déjela inicializarse. Restaure después su exportación. El contenedor crea un esquema vacío en su primer arranque: la restauración debe por tanto sustituirlo y no añadirse a él.
docker compose --profile bundled-db up -d database pg_restore -h localhost -U drovio -d drovio --clean --if-exists drovio.dump
En .env, dé a DB_PASSWORD la contraseña con la que se acaba de crear la base de datos.
Restaure en el servidor que piensa conservar, y apunte después la configuración hacia él en .env:
DB_HOST=my-database.example.com DB_NAME=drovio DB_USER=drovio DB_PASSWORD=<la contraseña existente>
Indique DROVIO_HOSTNAME en .env con el nombre por el que sus usuarios ya acceden al servidor. Compose lo exige, aunque no vaya a reescribir su URL.

Deje APP_URL vacío

A diferencia de DROVIO_HOSTNAME, APP_URL se escribe en la configuración en cada arranque. Darle un valor distinto de la URL actual de su servidor rompería las licencias ligadas a ella.
Aplique el script de esquema si además cambia de versión, tal como se describe más arriba. Una migración a igual versión no requiere nada aquí.

Arranque el servidor y compruebe que puede acceder a él:

docker compose --profile bundled-db up -d
curl -f http://drovio.example.com:8090/healthcheck

Deje la instalación antigua en su sitio, detenida, hasta que quede satisfecho. Volver atrás consiste entonces en arrancar de nuevo su servicio, siempre que no haya dejado que el nuevo despliegue escriba en la misma base de datos.