Configurazione avanzata di Stargate Docker¶

Backup¶

Backup automatici¶

I backup giornalieri vengono eseguiti alle 2:00 AM tramite cron (impostati durante l'installazione)
I backup vengono archiviati in ./backups/ come file .tar.gz con timestamp
I vecchi backup (>7 giorni) vengono automaticamente eliminati

Cosa è incluso nei backup¶

Dump PostgreSQL completo (tutti i database con utenti e permessi)
Dump di database individuali (per ripristino parziale se necessario)
Chiavi Vault (vault-keys.json per lo scongelamento)
Configurazione cliente (customer-config.sh con chiave WireGuard)
CSR e certificati S/MIME (tutti i file .crt, .pem, .cer)
Manifesto del backup (manifest.json con metadati)

Backup manuale¶

./scripts/backup.sh

Crea un archivio compresso in ./backups/YYYYMMDD_HHMMSS.tar.gz.

Ripristino dal backup¶

Per ripristinare su una nuova macchina o dopo una pulizia. Copiare l'archivio di backup sulla nuova macchina ed eseguire:

./scripts/restore.sh backups/20260130_143022.tar.gz

Lo script di ripristino:

Arresta tutti i servizi in esecuzione
Estrae e valida il backup
Installa Docker se necessario
Ripristina la configurazione cliente
Avvia i servizi di infrastruttura (PostgreSQL, Vault, MinIO)
Ripristina il database
Scongela Vault con le chiavi di backup
Avvia i servizi applicativi

Backup e ripristino della sola configurazione¶

Per conservare solo customer-config.sh attraverso un purge e una reinstallazione, ad esempio per cambiare l'IP del server prima dell'onboarding (vedere Troubleshooting e diagnostica):

./scripts/backup.sh --config-only
./scripts/restore.sh --config-only /var/data/backups/20260130_143022_config-only.tar.gz

backup.sh --config-only salva customer-config.sh ed eventuali server NTP personalizzati (ntp.sources) in /var/data/backups/<timestamp>_config-only.tar.gz. Non richiede servizi in esecuzione, esclude .env, le chiavi Vault e i database, e non cancella backup precedenti.
restore.sh --config-only ripristina solo questi due file, da un archivio di sola configurazione o da un backup completo. Non chiede conferma, conserva un file esistente come customer-config.sh.bak.<timestamp> e mostra i passi successivi.
Un ripristino completo da un archivio di sola configurazione viene rifiutato.

L'archivio contiene le password generate e la chiave privata WireGuard: trattarlo come un segreto.

Ripristino parziale (database singolo)¶

Se è necessario ripristinare solo un database:

Estrarre il backup¶

tar -xzf backups/20260130_143022.tar.gz -C /tmp/

Ripristinare un database specifico¶

cat /tmp/20260130_143022/database/mxengine.sql | docker exec -i stargate-postgres psql -U postgres -d mxengine

Aggiornamento di Stargate¶

La modalità di aggiornamento dipende dal tipo di installazione:

Appliance VM (immagine bootc) - le immagini VM di HIN Gateway. L'intero sistema operativo, compresi Docker, gli script di deployment, docker-compose.yml e le versioni fissate delle immagini dei servizi, viene distribuito come un'unica immagine con versione. Si aggiorna passando a un'immagine più recente e riavviando.
Installazione Compose semplice - un git clone di questo repository su una macchina gestita autonomamente. Si aggiorna eseguendo il checkout di un tag di release più recente.

Appliance VM (bootc)¶

Sull'appliance, /usr/share/stargate-deployment fa parte dell'immagine del sistema operativo di sola lettura. Non esiste un checkout git da aggiornare o ripristinare, quindi non eseguire git né update.sh --release. Tutti i dati - configurazione, secret, posta e database - si trovano sul Data Disk in /var/data e non vengono modificati da un aggiornamento.

Aggiornamento dalla dashboard¶

Utilizzare la sezione System version della pagina Settings della dashboard - vedere Aggiornare HIN Gateway per la guida passo passo. Quando si avvia il download, l'ops-agent:

Crea un backup completo con backup.sh, denominato <versione attuale>-pre_update_to_<versione di destinazione>, in /var/data/backups/. Se il backup non riesce, l'aggiornamento viene annullato e non viene modificato nulla. L'unica eccezione è un backup la cui parte Vault è incompleta: l'aggiornamento prosegue e l'ops-agent registra l'avviso pre-update backup is missing Vault secrets; continuing.
Scarica e prepara l'immagine del sistema operativo di destinazione (bootc switch). Il sistema in esecuzione non viene ancora modificato.
Attiva la nuova versione al riavvio successivo - subito con Restart now, oppure al successivo riavvio della macchina con Later.

Aggiornamento da riga di comando¶

Accedere alla VM come hinadmin (ssh hinadmin@<indirizzo IP della VM>) e utilizzare i comandi rapidi forniti con l'immagine:

hingateway-tags              # list the published versions
hingateway-switch vX.Y.Z     # download and stage the target version
sudo systemctl reboot        # boot into it
hingateway-status            # confirm: Booted: vX.Y.Z, Rollback: <previous version>

Note

A differenza della dashboard, hingateway-switch non crea prima un backup. Eseguire sudo /usr/share/stargate-deployment/docker-compose/scripts/backup.sh --label <versione attuale>-pre_update_to_vX.Y.Z prima del passaggio, in modo che l'archivio abbia lo stesso nome di quello creato dalla dashboard. La versione attuale è quella che hingateway-status mostra come avviata.

Rollback¶

L'appliance conserva su disco due deployment del sistema operativo: quello in esecuzione e quello precedente. Per tornare a quello precedente, utilizzare il pulsante Roll back della dashboard (vedere Aggiornare HIN Gateway) oppure eseguire:

hingateway-rollback && sudo systemctl reboot

Il rollback non richiede alcun download. Per tornare a una versione precedente a quella immediatamente precedente, passare esplicitamente a tale versione con hingateway-switch <tag>.

Il rollback ripristina l'immagine del sistema operativo, non i dati

Un rollback sostituisce solo l'immagine del sistema operativo; i dati in /var/data restano come li ha lasciati la versione più recente. Se la versione più recente ha modificato uno schema di database (ad esempio l'aggiornamento di Keycloak nella 1.1.7), la versione precedente non può funzionare con esso. In tal caso eseguire il rollback dell'immagine del sistema operativo e poi ripristinare il backup creato prima dell'aggiornamento - l'archivio in /var/data/backups/ il cui nome termina con pre_update_to_<versione di destinazione>.tar.gz - con sudo /usr/share/stargate-deployment/docker-compose/scripts/restore.sh <archive>. Il backup notturno elimina gli archivi più vecchi di 7 giorni, compreso questo; copiarlo quindi fuori dalla VM se potrebbe servire in seguito. Fa eccezione l'aggiornamento da 0.6.x a 1.1.7: in quel caso l'unico modo per tornare indietro è lo snapshot della VM (vedere Aggiornare HIN Gateway).

Nessun rollback oltre la prima immagine con Data Disk

Il primo aggiornamento a un'immagine con supporto per il Data Disk è irreversibile. Un'immagine precedente senza supporto per il Data Disk non monta il disco: lo stack si avvia con una /var/data vuota, mentre i dati reali restano intatti sul disco non montato. Sembra una perdita totale di dati, ma non lo è - aggiornando di nuovo alla versione più recente il disco viene rimontato.

Cosa conserva un aggiornamento¶

/etc viene unito alla nuova immagine (le modifiche locali hanno la precedenza) e /var - compresi /home, i dati Docker e gli account utente - viene conservato. I pacchetti installati ad hoc con rpm-ostree install sopravvivono ai riavvii ma vengono rimossi al passaggio successivo; è permanente solo ciò che fa parte dell'immagine.

Installazione Compose semplice¶

Questa sezione si applica solo a un git clone di questo repository gestito autonomamente, non all'appliance VM. Eseguire tutti i comandi dalla directory docker-compose/ del proprio checkout. Gli script leggono e scrivono file in /var/data/vereign/ leggibili solo da root, quindi eseguirli come root o con sudo. Anche il checkout dovrebbe appartenere a root (clonarlo come root): quando gli script vengono eseguiti come root in un checkout di un altro utente, git si rifiuta di leggerlo e la versione del deployment viene mostrata come unknown. Se il checkout appartiene a un altro utente, consentirlo una volta con sudo git config --global --add safe.directory <path to the checkout> ed eseguire i comandi git seguenti come tale utente, senza sudo.

1. Creare un backup prima dell'aggiornamento¶

sudo ./scripts/backup.sh

Copiare l'archivio fuori dalla macchina se potrebbe servire in seguito: il backup notturno elimina gli archivi più vecchi di 7 giorni.

2. Eseguire il checkout della release di destinazione¶

Il repository è l'unica fonte di verità per i file tracciati. Aggiornare quindi eseguendo il checkout di un tag di release. Questo sostituisce i file tracciati (script, docker-compose.yml con le versioni fissate delle immagini, modelli di configurazione) con le versioni di tale release:

sudo git fetch --tags origin
sudo git tag --sort=-creatordate | head    # most recent releases
sudo git checkout -f vX.Y.Z

3. Verificare le nuove variabili di configurazione¶

Confrontare i nomi delle variabili del modello di configurazione della release con la configurazione esistente per vedere se sono state aggiunte nuove variabili. Vengono confrontati solo i nomi, quindi valori e credenziali non vengono mostrati; le righe che iniziano con > sono le nuove variabili:

sudo -v    # enter the sudo password before the comparison starts
diff <(sudo grep -oE '^[A-Za-z_][A-Za-z0-9_]*=' /var/data/vereign/customer-config.sh | sort) \
     <(grep -oE '^[A-Za-z_][A-Za-z0-9_]*=' customer-config-prod.example.sh | sort)

Farlo prima del passaggio successivo: update.sh aggiunge ogni variabile mancante a customer-config.sh con il valore predefinito del modello, quindi in seguito le nuove variabili non compaiono più come differenze. Impostare subito in customer-config.sh ogni nuova variabile che richiede un valore diverso da quello predefinito.

4. Applicare la release¶

sudo ./scripts/update.sh

update.sh rigenera .env da customer-config.sh, scarica le immagini fissate in docker-compose.yml e ricrea i servizi interessati. L'output viene aggiunto a /var/data/vereign/update.log, con l'esecuzione più recente alla fine.

5. Riavviare lo stack¶

sudo ./scripts/start.sh

update.sh ricrea sempre Vault (e Dozzle, se abilitato), ma ricrea gli altri servizi solo se la loro definizione è cambiata. Un servizio il cui file di configurazione è cambiato nella release (ad esempio la configurazione di Caddy, APISIX o Loki) può quindi continuare a funzionare con il file precedente. start.sh ricrea tutti i container, così tutti applicano i nuovi file. Lo stack viene così riavviato una seconda volta; pianificare quindi l'aggiornamento in una finestra di manutenzione.

Note

customer-config.sh, .env e la directory secrets/ si trovano in /var/data/vereign/, completamente al di fuori del checkout del repository, quindi git checkout -f non li tocca mai - la configurazione e le credenziali vengono preservate. Effettuare sempre le personalizzazioni in customer-config.sh, mai modificando file tracciati come docker-compose.yml: il checkout successivo annulla qualsiasi modifica ai file tracciati. Ciò è intenzionale; mantenere ogni distribuzione identica al repository è ciò che consente agli aggiornamenti di essere applicati in modo affidabile e senza risoluzione manuale dei conflitti.

Per eseguire un rollback, effettuare il checkout del tag della release precedente ed eseguire di nuovo i passaggi 4 e 5. Se la release più recente ha modificato uno schema di database, non eseguire i passaggi 4 e 5: dopo il checkout del tag precedente, ripristinare invece il backup creato prima dell'aggiornamento con sudo ./scripts/restore.sh <archive> (vedere Ripristino dal backup). restore.sh arresta lo stack, ripristina i dati e avvia i servizi della release estratta.

update.sh rimuove già le immagini inutilizzate più vecchie di 24 ore. Per liberare subito spazio su disco, eseguire sudo docker image prune -af.

Non modificare le versioni manualmente¶

Warning

Le versioni delle immagini sono fissate in docker-compose.yml, non in customer-config.sh o .env - questi non contengono più valori *_VERSION. Non modificare manualmente un tag di immagine: le versioni vengono rilasciate e testate insieme come un insieme e sceglierne una manualmente produce una combinazione non testata. Sull'appliance VM il file è comunque di sola lettura. Passare sempre da una release all'altra come descritto sopra.

Configurazione¶

Il file .env viene generato da install.sh da customer-config.sh. Le impostazioni di dominio, certificato e WireGuard sono gestite in fase di esecuzione dal dashboard (/installation, /onboarding, /mail) — non sono conservate in .env. Per personalizzare le impostazioni di installazione, modificare customer-config.sh e rieseguire install.sh.

Sezioni chiave nel .env generato:

## PostgreSQL (auto-generato se vuoto in customer-config.sh)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<auto-generato>

## Vault (auto-populato dopo l'inizializzazione)
VAULT_TOKEN_<SERVICE>=<auto-generato, uno per servizio>

## Storage di oggetti S3 (SeaweedFS)
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=<auto-generato>

## Versioni delle applicazioni
SMIMEKEYS_VERSION=v0.0.5
POLICY_VERSION=v0.0.5
IRISAGENT_VERSION=v0.0.6-branch
MXENGINE_VERSION=v0.0.35
MTACONF_VERSION=dev

## Percorso posta in uscita
MXENGINE_PUBLIC_ADDRESS=http://localhost:8084
OUTBOUND_SEALER_MX_DOMAIN=hintest.ch

## WireGuard
WG_LOCAL_IP=203.0.113.50
WG_INTERFACE_PORT=19818
WG_TRANSPORT_MODE=tcp

Warning

Non modificare .env direttamente. Le modifiche verranno sovrascritte alla successiva esecuzione di install.sh. Per la configurazione in fase di esecuzione (domini, nome host, peer, S/MIME), utilizzare il dashboard.

URL dei servizi¶

Servizio	URL/Porta
Dashboard	https://localhost
smimekeys-client	http://localhost:8081
policy	http://localhost:8082
irisagent	http://localhost:8083
mxengine HTTP	http://localhost:8084
Stalwart SMTP	localhost:25
Gateway APISIX	http://localhost:9080
Keycloak	https://localhost:8180

Health Check¶

Tutti i servizi espongono un endpoint /liveness:

curl http://localhost:8081/liveness  # smimekeys-client
curl http://localhost:8082/liveness  # policy
curl http://localhost:8083/liveness  # irisagent
curl http://localhost:8084/liveness  # mxengine

Monitoraggio¶

Metriche Prometheus¶

Tutti i servizi applicativi espongono metriche Prometheus sulla porta 2112 (internamente), mappate a diverse porte host:

Servizio	Porta metriche	URL metriche
smimekeys-client	`2113`	http://localhost:2113/metrics
irisagent	`2114`	http://localhost:2114/metrics
policy	`2115`	http://localhost:2115/metrics
mxengine	`2116`	http://localhost:2116/metrics
node-exporter	`9100`	http://localhost:9100/metrics

Esempio di configurazione scrape Prometheus¶

scrape_configs:
  - job_name: 'stargate-smimekeys'
    static_configs:
      - targets: ['<host>:2113']
  - job_name: 'stargate-irisagent'
    static_configs:
      - targets: ['<host>:2114']
  - job_name: 'stargate-policy'
    static_configs:
      - targets: ['<host>:2115']
  - job_name: 'stargate-mxengine'
    static_configs:
      - targets: ['<host>:2116']
  - job_name: 'stargate-node'
    static_configs:
      - targets: ['<host>:9100']

Controllo rapido delle metriche¶

## Controllare tutti gli endpoint delle metriche
curl -s http://localhost:2113/metrics | head -20  # smimekeys-client
curl -s http://localhost:2114/metrics | head -20  # irisagent
curl -s http://localhost:2115/metrics | head -20  # policy
curl -s http://localhost:2116/metrics | head -20  # mxengine
curl -s http://localhost:9100/metrics | head -20  # node-exporter

Raccolta log (Alloy → Loki)¶

Alloy raccoglie i log dai container delle applicazioni e li invia a Loki.

Container monitorati:

stargate-apisix
stargate-keycloak
stargate-dashboard
stargate-smimekeys-client
stargate-policy
stargate-policy-sync
stargate-irisagent
stargate-mxengine

Configurazione in .env:

## URL di push Loki
LOKI_URL=https://loki.example.com

## Etichetta nome host per i log (auto-impostata su DEPLOYMENT_NAME)
ALLOY_HOSTNAME=stargate-acme

Etichette aggiunte ai log:

environment=<DEPLOYMENT_NAME> - Identifica il deployment
host=<ALLOY_HOSTNAME> - Identifica l'host (come il nome del deployment)
container=<nome-container> - Nome del container
service=<nome-servizio> - Nome del servizio (es., smimekeys-client, policy)
level=<livello-log> - Estratto dai log JSON se disponibile

Interrogare i log in Grafana:

{environment="stargate-acme"} |= "error"
{environment="stargate-acme", service="mxengine"}
{environment="stargate-acme", level="error"}

Verificare che Alloy funzioni:

Controllare lo stato di Alloy e l'attività recenteSonda di salute (dall'interno del network Docker)

docker logs stargate-alloy

docker exec stargate-alloy wget -qO- http://localhost:12345/-/ready

Nota: L'IP pubblico della VM deve essere nella whitelist della configurazione di ingress di Loki.

Stalwart MTA + mtaconf¶

Stargate utilizza Stalwart come mail transfer agent e mtaconf come demone di configurazione. Il dashboard invia la configurazione di domini e relay all'API REST di mtaconf, che la invia a Stalwart tramite la CLI di gestione.

Architettura del flusso di posta¶

Server di posta esterno
         │
         ▼ (porta 25)
┌─────────────────────────────────────────────────────┐
│ stalwart (stargate-stalwart)                        │
│                                                     │
│  Porta 25 (listener smtp)                           │
│    │                                                │
│    ▼                                                │
│  content_filter → smtp:[mxengine]:1587              │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (porta 1587)
┌─────────────────────────────────────────────────────┐
│ MXEngine (stargate-mxengine)                        │
│                                                     │
│  Porta 1587 (ingresso SMTP)                         │
│    │                                                │
│    ▼                                                │
│  Firmare/crittografare/elaborare la posta           │
│    │                                                │
│    ▼                                                │
│  Consegnare a stalwart per il relay                 │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (porta 10026)
┌─────────────────────────────────────────────────────┐
│ stalwart (stargate-stalwart)                        │
│                                                     │
│  Porta 10026 (listener di reiniezione)              │
│    │                                                │
│    ▼                                                │
│  transport → relay al MX di destinazione            │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (porta 25)
Server di posta di destinazione (tramite ricerca MX)

Scansione antivirus: La posta in entrata viene scansionata da ClamAV (stargate-clamav), collegato a Stalwart come milter nella fase SMTP DATA sia sul listener pubblico (:25) che su quello di reiniezione (:10026). La posta infetta viene respinta a livello SMTP; se ClamAV non è raggiungibile, il messaggio viene rinviato piuttosto che consegnato non scansionato (fail-closed). Il database delle firme di ClamAV risiede nel volume clamav_data e viene mantenuto aggiornato da freshclam in background.

Configurazione del relay di posta¶

Tutta la configurazione di posta che varia per deployment (domini di posta, nome host, host di relay, mappe di relay per dominio, reti consentite) viene impostata tramite la pagina /mail del dashboard in fase di esecuzione. Il dashboard invia la configurazione tramite POST all'API REST di mtaconf, che la applica a Stalwart senza riavviare il container.

Non c'è configurazione per dominio in customer-config.sh o .env - gli operatori aggiungono o modificano i domini tramite l'interfaccia utente.

Routing della posta (Migrazione dal vecchio MGW)¶

Differenza chiave rispetto al vecchio HIN-MGW

Nel vecchio MGW, era necessario configurare manualmente un server di destinazione per dominio. In Stargate, il routing della posta è deciso da record MX DNS per impostazione predefinita - Stalwart risolve il MX di ogni dominio al momento della consegna. La pagina /mail del dashboard consente di sovrascrivere questo comportamento per dominio (es. per relayare attraverso il tenant M365 / Exchange) senza toccare il DNS.

Predefinito - automatico tramite DNS MX:

Per ciascuno dei propri domini, assicurarsi che ci sia un record MX nel DNS che punti al corrispondente server Exchange (o altro server di posta):

domain1.com    MX 10  exchange1.domain1.com
domain2.com    MX 10  exchange2.domain2.com
domain3.com    MX 10  exchange3.domain3.com

Funziona per qualsiasi numero di domini - ogni dominio può puntare a un server di posta diverso e Stalwart instraderà di conseguenza.

Se Stargate è l'unico record MX per un dominio, Stalwart lo filtrerà e non avrà alcuna destinazione di consegna. Aggiungere un secondo record MX che punti al server di posta con una priorità più alta (= numero inferiore) in modo che Stalwart lo utilizzi come destinazione di consegna:

example.com    MX 10  exchange.example.com      ← destinazione di consegna (server di posta)
example.com    MX 20  stargate.example.com      ← gateway in entrata (Stargate)

Alternativa - relay esplicito per dominio (basato sul mittente):

Per il relay di ritorno attraverso M365 / Exchange Online, configurare le destinazioni di relay per dominio tramite la pagina /mail del dashboard. La posta dai mittenti non nella mappa ricade sulla ricerca MX.

Porte¶

Porta	Scopo
`25`	Listener SMTP principale (connessioni esterne)
`10026`	Porta di reiniezione (mxengine → stalwart, solo interno)
`1587`	Ingresso SMTP MXEngine (stalwart → mxengine, solo interno)
`8080`	API di gestione Stalwart + API REST mtaconf (solo interno)

Si utilizza Exchange?

Vedere Exchange-integration per la configurazione completa dei connettori e delle regole di trasporto Exchange Online / On-Premises.

Verifica¶

Controllare lo stato di Stalwart

docker exec stargate-stalwart stalwart-cli -u http://localhost:8080 server list-listeners

Controllare i log

docker logs stargate-stalwart

Testare la connessione alla porta 25

telnet localhost 25

Testare la porta interna 10026 (dal container mxengine)

docker exec stargate-mxengine nc -zv stalwart 10026

Aggiornamento dell'immagine mtaconf¶

Come ogni servizio, la versione dell'immagine mtaconf fa parte di una release e si aggiorna tramite la dashboard - non modificando il suo tag manualmente. Selezionare la release desiderata nella pagina di aggiornamento della dashboard per applicarla.

Risoluzione dei problemi di Stargate¶

Posta non elaborata da mxengine:

Verificare che content_filter sia configurato: controllare che i log mtaconf mostrino il push riuscito
Verificare che mxengine sia raggiungibile: docker exec stargate-stalwart nc -zv mxengine 1587

Posta bloccata dopo l'elaborazione di mxengine:

Verificare la configurazione in uscita di mxengine: OUTBOUND_SMTP_HOST=stalwart, OUTBOUND_SMTP_PORT=10026
Verificare che il listener sulla porta 10026 sia attivo in Stalwart
Verificare che le reti di relay consentite includano la rete Docker (172.x.x.x/16)

Errori di greylisting (450 4.7.1):

È normale! Il server di destinazione sta rifiutando temporaneamente la posta
Stalwart riprova automaticamente dopo un ritardo configurabile
Controllare la coda tramite l'API di gestione

Microsoft blocca l'IP (S3140):

L'IP del server ha una cattiva reputazione presso Microsoft
Richiedere la rimozione dalla lista su: https://sender.office.com
Potrebbero essere necessarie 24-48 ore per avere effetto

Fallimenti di ricerca DNS:

Utilizzare la pagina /mail del dashboard per impostare un host di relay esplicito o una mappa di relay per dominio (salta la scoperta basata su MX)

Connessione rifiutata sulla porta 25:

Assicurarsi che la porta 25 non sia bloccata dal firewall
Verificare se un altro servizio sta utilizzando la porta 25: ss -tlnp | grep :25

WireGuard (Comunicazione Agente-Agente)¶

IRISAgent utilizza WireGuard per stabilire tunnel crittografati sicuri tra istanze Stargate per la consegna di messaggi sigillati.

Come funziona¶

Ogni istanza Stargate utilizza l'IP pubblico statico reale del proprio server come indirizzo del tunnel WireGuard. Questo garantisce l'unicità tra tutti i deployment senza coordinazione manuale.

block
columns 5
  block:Stargate["Il tuo Stargate (203.0.113.50)"]:2
    columns 1
    A
    space
    A --> B
    A["IRISAgent (203.0.113.50:19818)"]
    B["Consegna messaggio sigillato tramite tunnel WG"]
  end

  blockArrowId1<["Tunnel WG (TCP)"]>(x):1

  block:mxengine["HIN Test (5.102.144.182)"]:2
    columns 1
    C
    space
    C --> D
    C["IRISAgent (5.102.144.182:19818)"]
    D["Ricevi messaggio sigillato"]
  end

Configurazione WireGuard¶

Impostazioni WireGuard in customer-config.sh:

## ==============================================================================
## IP del server — utilizzato come indirizzo del tunnel WireGuard e URL di callback MXEngine
## ==============================================================================
SERVER_STATIC_IP="203.0.113.50"       # L'IP pubblico statico reale del server

## ==============================================================================
## Impostazioni locali WireGuard (in genere lasciate ai valori predefiniti)
## ==============================================================================
WG_PRIVATE_KEY=""                     # Auto-generato da IRISAgent, poi salvato nella configurazione
WG_INTERFACE_PORT="19818"             # Porta WireGuard predefinita
WG_TRANSPORT_MODE="tcp"               # "tcp" (predefinito) o "udp"

Info

WG_LOCAL_IP è auto-derivato da SERVER_STATIC_IP. Non è necessario impostarlo separatamente.

Configurazione della connessione peer¶

I dettagli del peer WireGuard (chiave pubblica, endpoint, IP consentiti, ecc.) sono configurati in fase di esecuzione tramite la pagina /installation del dashboard. Non c'è più un blocco WG_PEER_* in customer-config.sh — il peer viene configurato dopo che lo stack è attivo.

Per la configurazione iniziale con l'ambiente HIN Test:

Avviare lo stack con ./scripts/install.sh.
Aprire il dashboard, seguire /installation per avviare l'handshake nonce / HIN.
Aprire i log IRISAgent (docker compose logs irisagent) e copiare la riga wireguard public key:. Inviarla insieme a DEPLOYMENT_NAME e SERVER_STATIC_IP a Vereign (kalin.canov@vereign.com) in modo che possano registrare il peer sul lato CA.
Dopo la conferma della registrazione da parte di Vereign, completare /onboarding nel dashboard per emettere il certificato S/MIME.

Per qualsiasi peer aggiuntivo (peer-to-peer tra due Stargate), scambiare chiavi pubbliche + endpoint con l'altra parte e aggiungere la connessione tramite l'API IRISAgent:

curl --location 'localhost:8083/v1/connections' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "allowedIps": "<IP del nuovo peer>/32",
  "description": "<breve descrizione>",
  "endpoint": "<IP del nuovo peer>:19818",
  "externalId": [
    "<dominio del nuovo peer>"
  ],
  "name": "<Nome del nuovo peer>",
  "presharedKey": "",
  "publicKey": "<chiave pubblica del nuovo peer>",
  "status": "completed",
  "transport": "tcp",
  "wireguardIp": "<IP del nuovo peer>",
  "wireguardPort": 10080
}'

Verifica WireGuard¶

Controllare l'interfaccia WireGuard di IRISAgent

docker exec stargate-irisagent wg show

Controllare la connessione nel database

docker exec stargate-postgres psql -U postgres -d irisagent \
  -c "SELECT connection_id, name, endpoint, wireguard_ip, transport, status FROM connections;"

Controllare gli ID esterni della connessione (utilizzati per il routing)

docker exec stargate-postgres psql -U postgres -d irisagent \
  -c "SELECT connection_id, external_id FROM connection_external_ids;"

Testare la connettività WireGuard (controllare lo stato del tunnel dall'host)

docker logs stargate-irisagent 2>&1 | grep -i "handshake\|peer.*added\|started listening"

Controllare i log IRISAgent per l'attività del tunnel

docker logs stargate-irisagent | grep -i wireguard

Risoluzione dei problemi WireGuard¶

Nessuna interfaccia WireGuard:

Controllare i log IRISAgent: docker logs stargate-irisagent
Verificare che WG_LOCAL_IP sia impostato in .env (auto-derivato da SERVER_STATIC_IP — dovrebbe essere l'IP pubblico statico di questo server)

Peer non raggiungibile:

Verificare che l'endpoint remoto sia accessibile: nc -zv <host_endpoint> <porta_endpoint>
Controllare che il firewall consenta la porta TCP+UDP 19818
Verificare che le chiavi pubbliche corrispondano su entrambe le estremità
Se TCP ha problemi, provare a impostare WG_TRANSPORT_MODE="udp" in customer-config.sh

Connessione non presente nel database:

Rieseguire la pagina /installation del dashboard per ristabilire la connessione peer
Controllare i log irisagent: docker logs stargate-irisagent

Sincronizzazione delle policy¶

Il servizio policy-sync sincronizza automaticamente le policy OPA/Rego da un repository Git al database PostgreSQL.

Come funziona Policy Sync¶

block
columns 8
  A:2 space B:2 space C:2
  A["Repository Git

      policies/
        alpha/
        outbound/
        ..."]
    A-->B
    B["policy-sync:

      - Clone/Pull repo
      - Parse .rego files
      - Upsert to database
      - Runs every 1h"]
    B-->C
    C["PostgreSQL

      - policy database
      - policies table"]

Configurazione di Policy Sync¶

Impostazioni in customer-config.sh:

## Repository Git contenente le policy (preconfigurato con le policy HIN Stargate)
POLICY_SYNC_REPO_URL="https://github.com/Health-Info-Net-AG/Stargate-policies.git"

## Opzionale: Autenticazione per repo privati
POLICY_SYNC_REPO_USER=""
POLICY_SYNC_REPO_PASS=""

## Opzionale: Branch specifico (predefinito: main)
POLICY_SYNC_REPO_BRANCH=""

## Opzionale: Sottocartella nel repo contenente le policy
POLICY_SYNC_REPO_FOLDER=""

## Intervallo di sincronizzazione (predefinito: 1h)
POLICY_SYNC_INTERVAL="1h"

Verifica di Policy Sync¶

Controllare lo stato di policy-syncVisualizzare le policy sincronizzateVisualizzare il contenuto di una policy specifica

docker logs stargate-policy-sync

docker exec stargate-postgres psql -U postgres -d policy \
  -c "SELECT name, policy_group, filename, to_timestamp(updated_at) as updated FROM policies ORDER BY name;"

docker exec stargate-postgres psql -U postgres -d policy \
  -c "SELECT rego FROM policies WHERE name='deliveryStrategy' AND policy_group='alpha';"

Attivazione manuale¶

Per forzare una sincronizzazione immediata:

docker restart stargate-policy-sync

Vault¶

Montaggi Vault¶

La porta API/UI di Vault (8200) non è pubblicata sull'host; accedere a Vault tramite la CLI all'interno del container (vedere Operazioni manuali Vault di seguito).

I seguenti motori di segreti KV-v2 vengono creati:

secret-smimekeys-client
secret-policy
secret-irisagent
secret-mxengine
secret-mtaconf

Operazioni manuali Vault¶

Ogni servizio ha un proprio token in /var/data/vereign/secrets/service-tokens.env, limitato al montaggio di quel servizio. I comandi amministrativi, come l'elenco dei montaggi, richiedono il token root di vault-keys.json nella stessa directory. Gli esempi leggono il token dal file, quindi non compare né nella riga di comando né nella cronologia della shell.

Controllare lo statoElencare i montaggiScrivere un segreto

docker exec stargate-vault vault status

VAULT_TOKEN=$(jq -r .root_token /var/data/vereign/secrets/vault-keys.json) \
  docker exec -e VAULT_TOKEN stargate-vault vault secrets list

VAULT_TOKEN=$(sed -n 's/^VAULT_TOKEN_SMIMEKEYS_CLIENT="\(.*\)"$/\1/p' /var/data/vereign/secrets/service-tokens.env) \
  docker exec -e VAULT_TOKEN stargate-vault vault kv put secret-smimekeys-client/test key=valore

Database¶

Database PostgreSQL creati:

smimekeys_client
policy
irisagent
mxengine

Connettersi a PostgreSQL¶

docker exec -it stargate-postgres psql -U postgres

O connettersi esternamente

psql -h localhost -U postgres -d smimekeys_client

Policy (Rego)¶

MXEngine utilizza policy OPA/Rego memorizzate in PostgreSQL per determinare la strategia di consegna della posta.

Raccomandato: Utilizzare policy-sync per sincronizzare automaticamente le policy da un repository Git. Vedere la sezione Policy Sync.

Visualizzare la policy corrente¶

Elencare tutte le policyVisualizzare il contenuto della policy

docker exec stargate-postgres psql -U postgres -d policy \
  -c "SELECT id, name, policy_group, filename, to_timestamp(updated_at) as updated FROM policies;"

docker exec stargate-postgres psql -U postgres -d policy \
  -c "SELECT rego FROM policies WHERE name='deliveryStrategy';"

Posizione delle policy¶

Configurazione MXEngine: POLICY_OUTBOUND: "outbound/delivery"
Database: database policy, tabella policies
Gestito da: servizio policy-sync (sincronizza dal repository Git)

Log¶

Tutti i serviziServizio specifico

docker compose logs -f

docker compose logs -f <servizio>

Es.:

docker compose logs -f smimekeys-client
docker compose logs -f vault

Risoluzione dei problemi¶

Emissione certificato fallita / Tunnel WireGuard non stabilito¶

Questo è il problema più comune dopo l'installazione iniziale. Il certificato S/MIME non può essere emesso perché il tunnel WireGuard verso la CA HIN non è stabilito.

Sintomi:

La pagina /onboarding del dashboard segnala un fallimento di invio del CSR
I log smimekeys-client mostrano: issue certificate error: certcatunnel: error sending request: irisagent: ... context deadline exceeded

Cause profonde (controllare in ordine):

Peer non registrato sulla CA HIN - La chiave pubblica WireGuard deve essere registrata sul lato HIN. Fornire a HIN:

# Ottenere la chiave pubblica WireGuard
docker compose logs irisagent | grep "public key"

Insieme a DEPLOYMENT_NAME, SERVER_STATIC_IP e WG_INTERFACE_PORT (se modificato da 19818).

Firewall che blocca la porta 19818 - Assicurarsi che 19818/TCP sia aperto sia in entrata che in uscita sul server Stargate.
Nome host errato - Se il nome host di Stalwart è ancora impostato sul valore predefinito del modello (mail.example.com), aggiornarlo tramite la pagina /mail del dashboard.

Dopo la risoluzione del problema:

Riaprire la pagina /onboarding del dashboard per rigenerare il CSR e inviarlo nuovamente attraverso il tunnel ora attivo.

Vedere Passo 5: Registrazione del peer WireGuard per il processo completo.

Vault è congelato dopo il riavvio¶

Eseguire lo script di avvio che gestisce lo scongelamento:

./scripts/start.sh

Impossibile scaricare le immagini¶

Accedere al registry:

docker login hub.docker.com

Il servizio non si avvia¶

Controllare i log:

docker compose logs <nome-servizio>

Reimpostare tutto¶

Warning

Questi comandi CANCELLANO TUTTI I DATI - usare con cautela!

È possibile ripristinare i dati solo se si eseguono operazioni di backup prima e si salva il backup in un luogo sicuro.

./scripts/purge.sh
./scripts/install.sh

Struttura dei file¶

stargate/
├── backups/                      # Backup completi (gitignorato)
│   └── *.tar.gz
├── config
│   ├── apisix
│   │   ├── apisix.yaml.template
│   │   ├── config.yaml
│   │   └── generated
│   │       └── apisix.yaml
│   ├── keycloak
│   │   ├── generated
│   │   └── realm-stargate.json
│   ├── nats
│   │   └── nats.conf
│   ├── nginx
│   │   ├── dashboard.conf
│   │   └── keycloak.conf
│   ├── alloy
│   │   └── config.alloy          # Configurazione invio log Alloy
│   └── vault
│       └── vault.hcl             # Configurazione Vault
├── customer-config-prod.example.sh     # Modello di configurazione (copiare in customer-config.sh)
├── customer-config.sh            # Impostazioni specifiche del cliente (copiate dal modello)
├── docker-compose.yml            # File compose principale
├── .env                          # Variabili d'ambiente (generate da install.sh)
├── init
│   └── postgres
│       └── 01-create-databases.sql
├── scripts
│   ├── backup.sh                 # Backup completo (DB, Vault, config, certificati)
│   ├── gather-app-versions.sh    # Raccoglie le versioni delle app per le metriche node-exporter
│   ├── health-check.sh           # Health check completo di tutti i servizi
│   ├── init-keycloak.sh
│   ├── init-vault.sh             # Inizializzazione Vault (utilizzato dal container vault-init)
│   ├── install.sh                # Prima installazione (Docker, Vault). La configurazione di dominio/certificato/peer avviene successivamente nel dashboard.
│   ├── purge.sh                  # Elimina tutti i dati (distruttivo!)
│   ├── restore.sh                # Ripristina da archivio di backup
│   ├── send-logs-to-support.sh   # Incolla i log online e ottieni un link da fornire al supporto
│   ├── start.sh                  # Avvia i servizi + scongela Vault
│   ├── stop.sh                   # Arresta i container (preserva i dati)
│   └── update.sh
└── secrets/                      # Creato al primo avvio (gitignorato)
    ├── vault-keys.json           # Chiavi di scongelamento Vault (FARE BACKUP!)
    └── signing-key.csr           # Richiesta di firma certificato S/MIME

Controlli rapidi di salute e log¶

Eseguire il health check completo

Health check rapidoOutput dettagliato

./scripts/health-check.sh

./scripts/health-check.sh -v

Con output dettagliato (mostra dettagli WireGuard, risposte liveness).

Questo controlla:

Tutti gli stati dei container (in esecuzione, healthy)
Endpoint Liveness (smimekeys-client, policy, irisagent, mxengine)
Stato di scongelamento di Vault
Connettività PostgreSQL e tutti i 4 database
Salute di MinIO
Stato del tunnel WireGuard e handshake dei peer
Stalwart MTA (in esecuzione, porta 25, porta 10026)
Endpoint delle metriche Prometheus
Utilizzo del disco e della memoria

Per l'ispezione manuale dei log:

Controllare i log (ultime 10 righe)

docker logs stargate-smimekeys-client --tail 10
docker logs stargate-policy --tail 10
docker logs stargate-irisagent --tail 10
docker logs stargate-mxengine --tail 10

Seguire i log in tempo reale

docker logs -f stargate-mxengine

Controllare tutti gli stati dei container

docker ps -a --format 'table {{.Names}}\t{{.Status}}'

Seguire tutti i log dei container in tempo reale

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --timestamps -f {} 2>&1 | sed "s/^/[{}] /"'

Fornire log al supporto¶

È possibile fornire log al nostro supporto tramite pastebin.hin-infra.ch e il comando CLI:

Caricare i log di tutti i container:

TuttiPer l'ultima ora (1h)Ultime 500 righe di log

Utilizzare il nostro script:

./scripts/send-logs-to-support.sh --all

O eseguire manualmente:

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --timestamps {} 2>&1 | sed "s/^/[{}] /"' | curl https://pastebin.hin-infra.ch/ --data-binary @-

Tip

Questa operazione può raggiungere i nostri limiti di upload - 20 Mb.

Utilizzare il nostro script:

./scripts/send-logs-to-support.sh --since 1h

O eseguire manualmente:

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --since 1h --timestamps {} 2>&1 | sed "s/^/[{}] /"' | curl https://pastebin.hin-infra.ch/ --data-binary @-

Questo è il valore predefinito

--tail 500 è il valore predefinito del nostro script, ma è comunque possibile fornirlo.

Utilizzare il nostro script:

./scripts/send-logs-to-support.sh --tail 500

O eseguire manualmente:

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --tail 500 --timestamps {} 2>&1 | sed "s/^/[{}] /"' | curl https://pastebin.hin-infra.ch/ --data-binary @-

Caricare i log di container specifici:

TuttiPer l'ultima ora (1h)Ultime 500 righe di log

docker logs <NOME_CONTAINER> 2>&1 | curl https://pastebin.hin-infra.ch/ --data-binary @-

Tip

Questa operazione può raggiungere i nostri limiti di upload - 20 Mb. Se ciò accade, provare a ridurre la quantità di log impostando un limite di tempo o un numero di righe.

docker logs --since 1h <NOME_CONTAINER> 2>&1 | curl https://pastebin.hin-infra.ch/ --data-binary @-

docker logs --tail 500 <NOME_CONTAINER> 2>&1 | curl https://pastebin.hin-infra.ch/ --data-binary @-

Dopo di che, si riceverà un link unico nel formato https://pastebin.hin-infra.ch/<20 simboli> da fornire al supporto / ticket.

Warning

La scadenza è impostata a 30 giorni. Se alcune parti dei log o i log stessi devono essere conservati per un periodo più lungo, assicurarsi di conservarne una copia.