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

Quale tag usare¶

Tag	Indica
`3.6.6`	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.6.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.

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

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

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