Distribuzione con Docker¶

Drovio Server può essere distribuito in un container Docker. A questo scopo forniamo due immagini distinte:

Tutto-in-uno: destinata soprattutto alle prove e alla preproduzione. Contiene le funzionalità essenziali di Drovio Server. Tutte le dipendenze sono incorporate e configurate automaticamente all'avvio del container.
Produzione: riservata agli ambienti di produzione. Drovio Server si appoggia a un database gestito da Docker o esterno, e all'archivio delle sessioni interno oppure a un archivio Redis gestito da Docker o esterno.

Immagine Docker	Tutto-in-uno	Produzione
Uso	Test e preproduzione	Produzione
Base	Debian 13 (Trixie) slim	Debian 13 (Trixie) slim
Database PostgreSQL	Database PostgreSQL interno	Database PostgreSQL gestito da Docker o esterno, 14 e successivi
Archivio delle sessioni	Archivio interno	Archivio interno, oppure archivio Redis gestito da Docker o esterno
Utente di esecuzione	`root`	`drovio`, uid 1000

Componenti gestiti da Docker o esterni

Il termine gestito da Docker indica un componente di Drovio Server pilotato dal plugin docker compose e collocato sulla stessa rete Docker. I componenti esterni sono al contrario del tutto indipendenti: dovete allora fornire le loro informazioni di connessione tramite le variabili d'ambiente corrispondenti.

Entrambe le immagini sono multiarchitettura: linux/amd64 e linux/arm64 sono pubblicate sotto lo stesso nome, e Docker sceglie quella corrispondente alla vostra macchina. Non c'è nessuna opzione --platform da passare, né alcun nome di immagine proprio di un'architettura.

Requisiti¶

Docker Engine 20.10 o successivo, per il supporto delle immagini multiarchitettura.
Il plugin docker compose 2.20 o successivo per l'immagine di produzione, che usa i profili e le dipendenze facoltative.

Ottenere le immagini¶

Le immagini sono pubblicate sul nostro registro privato. Chiedete le credenziali della vostra organizzazione a support@drovio.com: riceverete un nome utente e un token, entrambi personali e revocabili.

Immagine	Riferimento
Tutto-in-uno	`registry.gitlab.com/drovio/drovio-server-aio`
Produzione	`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

Quale tag usare¶

Tag	Indica
`3.6.9`	quella versione esatta, e non si sposta mai
`3.6`	l'ultima correzione della serie 3.6
`latest`, `stable`	l'ultima versione pubblicata

Fissate una versione completa in produzione. I tag mobili sono comodi per una prova, ma fanno sì che un docker compose pull possa portare una nuova versione minore senza che l'abbiate deciso.

Accesso di rete in uscita

Il vostro firewall deve autorizzare registry.gitlab.com e anche il dominio di archiviazione a oggetti da cui vengono scaricati i livelli dell'immagine. Un docker login che riesce, seguito da un docker pull che si blocca, dipende quasi sempre da qui.

Installazione offline¶

Se i vostri server non hanno alcun accesso in uscita, distribuiamo ogni versione anche sotto forma di archivio, uno per architettura. Chiedetelo al supporto, quindi caricatelo sulla macchina di destinazione:

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

L'immagine così caricata porta lo stesso nome e lo stesso tag di quella del registro: il resto di questa pagina si applica quindi tale e quale.

Gestione dei dati persistenti¶

Secondo i principi di Docker, i dati memorizzati in un container sono effimeri e non sopravvivono alla sua distruzione. Esistono tuttavia meccanismi per i dati persistenti, tra cui i bind mount, che proiettano un file o una cartella del sistema host all'interno del container.

Le nostre immagini Docker si appoggiano ai bind mount per tre tipi di dati persistenti:

Dati	Percorso nel container	Riguarda
File di configurazione	`/etc/drovio-server`	entrambe le immagini
File di log	`/var/log/drovio-server`	entrambe le immagini
Dati del database	`/opt/drovio-server/data`	l'immagine tutto-in-uno

L'immagine di produzione non incorpora alcun database. Ha bisogno solo dei primi due. La collocazione dei suoi dati dipende dal database verso cui la puntate, si tratti di quello che docker compose avvia per voi o del vostro server.

Il segreto JWT vive nella cartella di configurazione

Al primo avvio il container scrive in settings.conf un segreto JWT proprio. Questo segreto firma le sessioni degli utenti. Rimuovere quella cartella significa perdere il segreto: ogni utente dovrà riconnettersi.

Proprietario delle cartelle, immagine di produzione¶

L'immagine di produzione gira sotto l'utente non privilegiato drovio, uid e gid 1000. Le due cartelle in cui scrive devono appartenergli:

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

Altrimenti il container rifiuta di avviarsi, indicando quale cartella correggere.

Non fatelo mai sulla cartella del database

data/postgresql appartiene al container del database, che gira sotto il proprio utente. Affidarla all'uid 1000 impedisce a PostgreSQL di avviarsi, con un errore di permessi sui suoi stessi file.

Aggiornamento dalla 3.6.5 o precedenti

Le versioni precedenti di questa immagine giravano sotto root. Le cartelle che hanno creato sul vostro host appartengono quindi a root. Lanciate il comando chown qui sopra sulle vostre cartelle config e logs esistenti prima di avviare la nuova immagine.

Nulla viene scritto al di fuori di questi due percorsi e della cartella di lavoro di Vert.x sotto /tmp. Il container può del resto girare con un file system radice in sola lettura:

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

Distribuire l'immagine tutto-in-uno¶

Create una cartella drovio-server e posizionatevi al suo interno:

mkdir drovio-server
cd drovio-server

Create un volume per il database incorporato, quindi avviate il container:

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"

Usate un volume per il database, non un bind mount

PostgreSQL verifica che la sua cartella di dati appartenga all'utente postgres. Ora, Docker Desktop, sia su macOS sia su Windows, presenta tutto ciò che si trova in un bind mount come appartenente a root, qualunque cosa facciate. Il container non può avviarsi così. Un volume con nome non ha questo limite, ed è comunque il modo consigliato di conservare i dati di un database. La configurazione e i log non sono interessati e possono restare in bind mount.

Opzione	Descrizione
`--hostname`	Fissa un nome host preciso. Dovrete poi comunicarcelo perché possiamo generare le vostre licenze. Conservate sempre lo stesso, dato che le licenze vi sono legate.
`-p <host>:<container>`	Pubblica la porta del container sulla porta dell'host. Qui è usata la porta `8090`, poiché Drovio Server non attiva TLS e tutto il traffico HTTP passa da questa porta in modo predefinito.
`-v "<host>:<container>"`	Bind mount per i dati persistenti descritti sopra.
`--rm`	Elimina automaticamente il container al suo arresto.
`-it`	Alloca uno pseudo-terminale collegato all'ingresso standard del container.

Il nome host viene scritto una sola volta

Al primissimo avvio il server iscrive nella propria configurazione il suo URL, costruito a partire dal nome host che gli date. Non viene ricalcolato in seguito, e le vostre licenze vi sono legate. Un container avviato senza --hostname rifiuterebbe di funzionare.

Impostate piuttosto APP_URL se l'URL con cui i vostri utenti raggiungono il server differisce dal nome host del container, dietro un proxy inverso per esempio.

Distribuire l'immagine di produzione¶

L'immagine di produzione si distribuisce con il plugin docker compose, lo strumento che serve a definire e ad avviare applicazioni Docker multi-container.

Recuperare i file di distribuzione¶

Tutto ciò di cui avete bisogno per distribuire si trova nell'immagine stessa. Estraetelo nel punto in cui volete far girare il server, con le credenziali che vi sono servite per 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

Ottenete tre file, tutti allineati alla versione che avete appena recuperato:

File	Che cos'è
`docker-compose.yml`	la distribuzione, con o senza database e archivio delle sessioni gestiti
`env.example`	le impostazioni che dovete compilare
`drovio-server.sql`	lo schema del database, usato alla sua creazione e durante gli aggiornamenti

La sua riga image: indica già la versione esatta da cui l'avete estratto.

Impostazioni¶

Copiate env.example in .env e compilatelo. Due valori sono obbligatori:

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

Generate le password invece di riutilizzarne una, per esempio con openssl rand -base64 24. DROVIO_HOSTNAME segue la stessa regola di --hostname qui sopra: viene iscritto nell'URL del server solo al primo avvio.

Componenti gestiti da Docker o esterni¶

La scelta tra un database e un archivio delle sessioni gestiti qui oppure forniti da voi si fa all'avvio, tramite i profili. Lo stesso docker-compose.yml copre i tre casi:

Comando	Che cosa avvia
`docker compose --profile bundled-db up`	PostgreSQL gestito da `docker compose`, archivio delle sessioni interno
`docker compose --profile bundled-db --profile redis up`	lo stesso, con un archivio delle sessioni Redis gestito da `docker compose`
`docker compose up`	database esterno, compilate `DB_HOST` e le variabili associate in `.env`

Con il profilo redis, decommentate anche SS_TYPE, SS_REDIS_CONNECTION_STRINGS, SS_REDIS_MASTER_NAME e SS_REDIS_PASSWORD nel vostro .env.

Componenti gestiti da Docker: pilotati dal plugin docker compose. Tutti i container seguono lo stesso ciclo di vita e condividono la stessa rete Docker.
Componenti esterni: non sono dichiarati nel file docker-compose. Le loro informazioni di connessione devono essere trasmesse tramite le variabili d'ambiente previste a tale scopo. Al primo avvio, il file di configurazione di Drovio Server non esiste e viene creato con valori predefiniti. Queste variabili servono allora a sostituirne alcuni, il che permette un primo avvio riuscito.

Verificare che il server risponda¶

Entrambe le immagini espongono un endpoint di controllo dello stato e dichiarano un HEALTHCHECK Docker che se ne serve. docker ps mostra il container come healthy non appena il server risponde.

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

Variabili d'ambiente¶

Variabile d'ambiente	Campo di configurazione
`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`

Le variabili d'ambiente hanno sempre la precedenza

Queste variabili sovrascrivono sistematicamente i valori del file di configurazione di Drovio Server all'avvio. Se modificate nei file di configurazione un valore associato a una di esse, dovete anche togliere quella variabile dal file docker-compose oppure aggiornarne il valore prima di riavviare Drovio Server.

Aggiornare¶

Recuperate la versione desiderata, quindi ricreate i container. La vostra configurazione, i vostri log e il vostro database vivono nei bind mount e non vengono toccati.

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

Aggiornare lo schema del database¶

Una nuova versione può aggiungere tabelle o colonne. Le due immagini non trattano questo punto allo stesso modo.

Immagine	Che cosa applica le modifiche di schema
Tutto-in-uno	il container stesso, a ogni avvio. Niente da fare.
Produzione	voi, prima di avviare la nuova immagine.

L'immagine di produzione non tocca mai il vostro schema. drovio-server.sql viene eseguito solo alla creazione del database, dal container di database di docker compose al suo primissimo avvio, oppure da voi sul vostro server. Non viene rieseguito in seguito.

Durante un aggiornamento dell'immagine di produzione:

Estraete drovio-server.sql dall'immagine verso cui state aggiornando, come per una prima installazione. Lo script distribuito in un'immagine è sempre quello che quell'immagine si aspetta.
```
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"
```

Applicatelo al vostro database, con i container Drovio Server arrestati.

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

Avviate la nuova immagine.

Lo script è scritto per essere rieseguito: crea ciò che manca e lascia il resto al suo posto, cosicché applicarlo a un database già aggiornato non cambia nulla.

Prima fate un backup

Fate un backup del database prima di applicare uno script di schema, qualunque sia il divario di versione. È l'unico passaggio di questa procedura che non si può recuperare.

Tutto-in-uno e versioni maggiori di PostgreSQL

L'immagine tutto-in-uno non aggiorna il proprio cluster di database sul posto. Se una nuova versione incorpora una versione maggiore di PostgreSQL più recente, il container si arresta all'avvio con un messaggio esplicativo. Esportate i vostri dati dall'immagine precedente con pg_dumpall, poi ripristinateli in un volume nuovo con la nuova immagine.

Migrare dall'immagine production-ready v3.6.5 o precedente¶

I deployment production-ready antecedenti alla 3.6.6 potevano essere caricati solo da un archivio e giravano come root. Aggiornarli e spostarli sul registry si fa una volta sola, ma l'ordine indicato qui sotto conta.

Fate un backup del vostro database. L'ultimo passo di questa procedura è l'unico che non si può annullare.
Cambiate i permessi delle due directory in cui il server scrive, e solo di quelle. Sono state create da un container che girava come root, mentre la nuova immagine gira con uid 1000.
```
sudo chown -R 1000:1000 config logs
```
Non l'intera cartella

Non eseguite questo comando sull'intera directory di deployment. data/postgresql appartiene al container del database, che gira con un proprio utente, e assegnarla all'uid 1000 impedisce a PostgreSQL di avviarsi.
Puntate al registry. Sostituite la riga image: del vostro docker-compose.yml, oppure ripartite dal pacchetto contenuto nella nuova immagine. Il suffisso di architettura sparisce: un deployment arm64 che usava drovio/drovio-server-arm64 deve ora usare drovio/drovio-server.
```
image: 'registry.gitlab.com/drovio/drovio-server:3.6.9'
```
Conservate la password del vostro database. Se usate il docker-compose.yml incluso e il suo file .env, DB_PASSWORD deve contenere la password che il vostro database già usa, quella scritta nel vostro file compose attuale. Una password appena generata lascerebbe il server incapace di connettersi.
Avviate la nuova immagine e verificate che si alzi prima di proseguire.
Applicate lo script dello schema se state anche cambiando versione, come descritto più sopra.

Nient'altro viene riscritto

L'URL del vostro server e le licenze legate a esso vengono lette dalla configurazione che avete già. Le regole su --hostname valgono solo per un primo avvio. Un deployment esistente non ne è interessato.

Finché non avete eseguito il passo 6, tornare indietro consiste nel ripristinare la vecchia riga image:, a patto di aver conservato l'archivio caricato in origine.

Migrare da un'installazione Windows o da pacchetto Linux¶

Se avete installato Drovio Server su Windows oppure tramite il pacchetto Linux corrispondente alla vostra distribuzione, e volete passare alla nostra immagine Docker di produzione, ci sono solo due elementi da trasferire: il database e la cartella di configurazione. Nient'altro va ricreato, la migrazione è semplice.

Tre cose da sapere prima di cominciare

L'URL del vostro server deve sopravvivere. Le vostre licenze sono legate a quell'URL, e quindi a quel nome host.

Anche il vostro segreto JWT deve sopravvivere, altrimenti le sessioni degli utenti connessi verrebbero invalidate.

Le variabili di .env vengono applicate a ogni avvio, non solo al primo. È così che puntate la vostra configurazione esistente verso un nuovo database senza modificarla a mano.

Salvate il database e l'intera cartella di configurazione. Il ripristino del passo 7 è l'unico passo di questa procedura che non si può annullare.

Arrestate il servizio.

LinuxWindows

systemctl stop drovio-server

sc stop drovio-server

Esportate il database. L'host, il nome e l'utente si trovano nella sezione database del vostro settings.conf.
```
pg_dump -h localhost -U drovio -d drovio -Fc -f drovio.dump
```
Recuperate i file di distribuzione come per una prima installazione, poi copiate env.example in .env.
Portate con voi la configurazione. Copiate settings.conf e admin.properties nella cartella config, accanto a docker-compose.yml, insieme a ogni file a cui rimandano: keystore TLS, keystore SAML, autorità di certificazione LDAP.

LinuxWindows

I percorsi contenuti in settings.conf corrispondono già a quanto si aspetta il container, essendo entrambi /etc/drovio-server. Niente da riscrivere.

Ogni percorso assoluto contenuto in settings.conf va riscritto, da C:\ProgramData\Drovio\Drovio Server\... a /etc/drovio-server/.... A seconda di ciò che usate, questo può riguardare http.keystore, users.auth.saml.keystore, users.auth.saml.sp_metadata_path, users.auth.saml.idp_metadata_path e users.auth.ldap.ca_certificate_path.
Affidate le due cartelle all'utente del container, cioè all'uid 1000.
```
mkdir -p logs
sudo chown -R 1000:1000 config logs
```
Ripristinate il vostro export, poi completate .env.
Database gestito da composeIl vostro database
Avviate il database da solo e lasciatelo inizializzare. Ripristinate poi il vostro export. Il container crea uno schema vuoto al primo avvio: il ripristino deve quindi sostituirlo e non aggiungersi ad esso.
docker compose --profile bundled-db up -d database pg_restore -h localhost -U drovio -d drovio --clean --if-exists drovio.dump
In .env, date a DB_PASSWORD la password con cui il database è appena stato creato.
Ripristinate sul server che intendete conservare, poi puntate la configurazione verso di esso in .env:
DB_HOST=my-database.example.com DB_NAME=drovio DB_USER=drovio DB_PASSWORD=<la password esistente>
Indicate DROVIO_HOSTNAME in .env con il nome con cui i vostri utenti raggiungono già il server. Compose lo richiede, anche se non riscriverà il vostro URL.

Lasciate APP_URL vuoto

A differenza di DROVIO_HOSTNAME, APP_URL viene scritto nella configurazione a ogni avvio. Dargli un valore diverso dall'URL attuale del vostro server comprometterebbe le licenze che vi sono legate.
Applicate lo script dello schema se state anche cambiando versione, come descritto più sopra. Una migrazione a parità di versione non richiede nulla qui.

Avviate il server e verificate di riuscire a raggiungerlo:

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

Lasciate la vecchia installazione al suo posto, arrestata, finché non siete soddisfatti. Tornare indietro consiste allora nel riavviare il suo servizio, a patto di non aver lasciato che la nuova distribuzione scrivesse nello stesso database.