Questa guida è per l’amministratore che esegue HQbird 2027 in Docker. Un container è un’istanza Firebird con tutti i componenti di HQbird:

  • Firebird (la compilazione HQbird di una linea: 5.0, 4.0, 3.0 o 2.5);
  • agente HQbird (fbagent): backup, monitoraggio, lavori di manutenzione, aggiornamenti, la connessione a HQCenter;
  • HQ Monitor: la console web dell’istanza;
  • nodo di cluster (hqclusternode) e RCM (hqbirdrcm): li installa l’agente quando HQCenter aggiunge questa istanza a un cluster, oppure quando assegni al container un ruolo di cluster (sezione 7). Senza un ruolo e senza HQCenter, il container non esegue alcun componente di cluster.

Il container installa HQbird con lo stesso installatore offline di un server (guida all’installazione su Linux). L’agente aggiorna poi Firebird, HQ Monitor, i componenti del cluster e se stesso da HQCenter, come su un server. I dati, la configurazione, la licenza, i certificati di HQCenter e i programmi aggiornati sono sui volumi: restano quando ricrei il container o cambi l’immagine.

Versione attuale: 2027.2.33 (2026-11-16): Firebird 2.5.9, 3.0.15, 4.0.8 e 5.0.5, agente 3.4.0, HQ Monitor 1.57.0, RCM e nodo 2027.5.12.

Testato il 2026-11-16 su Ubuntu 22.04.5 (2 vCPU / 4 GB), Docker 29.10.0, Compose 5.7.1, immagine hqbird2027-fb40:2027.2.33 (prima prova: 2026-11-11, immagine 2027.2.27). Un’installazione passo per passo per Ubuntu 22.04: hqbird2027-docker-install-fb40.ru.md (russo), hqbird2027-docker-install-fb40.pt.md (portoghese).

Il ruolo di cluster (sezione 7.1) e lo switchover (sezione 7.3) sono stati testati il 2026-11-16 sulle immagini 5.0, 4.0, 3.0 e 2.5, con i due «host» come due indirizzi di una VM, e su due host Docker separati (due droplets, l’immagine 4.0 2027.2.33). Il 2026-11-17 il resto è stato testato su due host Docker con l’immagine 5.0 2027.2.33: un cluster fatto a mano in container 2027.2.32 e spostato sulla nuova immagine (entrambi i container healthy in 35 secondi), HQBIRD_RCM_ALLOW, le pagine Services della console RCM e il failover automatico. I router (HAProxy) non si avviano nelle immagini fino a 2027.2.33 (sezione 9); l’immagine successiva contiene la correzione.

1. Immagini

Immagine Firebird Porta predefinita
ghcr.io/ibsurgeon/hqbird2027-fb50:<version> 5.0 3050
ghcr.io/ibsurgeon/hqbird2027-fb40:<version> 4.0 3050
ghcr.io/ibsurgeon/hqbird2027-fb30:<version> 3.0 3050
ghcr.io/ibsurgeon/hqbird2027-fb25:<version> 2.5 3050

Le immagini sono nel GitHub Container Registry di IBSurgeon (https://github.com/orgs/IBSurgeon/packages). Sono pubbliche: non serve accedere. <version> è la versione di setup di HQbird, per esempio 2027.2.33. L’etichetta 2027.2 è l’immagine 2027.2.x più recente.

Command
docker pull ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.33

Le immagini sono firmate con cosign. La chiave pubblica hqbird-cosign.pub non è ancora pubblicata (2026-11-16). Le immagini 2027.2.33 sono firmate. Quando hai la chiave, controlla un’immagine prima di usarla:

Command
cosign verify --key hqbird-cosign.pub ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.33

2. Primo avvio

  1. Copia compose.yaml (da ops/docker/ della versione) in una cartella sull’host Docker.

  2. Metti la password SYSDBA in un file, leggibile solo da te:

    Command
    mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password
  3. In compose.yaml, imposta image:, hostname: e togli il # dalle righe secrets: che usi.

  4. Avvia il container:

    Command
    docker compose up -d
  5. Segui l’installazione (qualche minuto al primo avvio):

    Command
    docker compose logs -f

    Su 2 vCPU l’installazione richiede circa 20 secondi. È finita quando il log mostra [hqbird-boot] ready: firebird.service=active ... e docker compose ps mostra healthy.

Poi:

  • Firebird: <docker host>:3050.
  • HQ Monitor: http://<docker host>:23050/, utente admin. L’installatore crea la password; leggila con docker compose exec hqbird cat /opt/hqbird/conf/access.properties.
  • L’id dell’agente in HQCenter: il nome host + la data di installazione (YYMMDD) + -fbNN, per esempio hqbird-fb40-3051261111-fb40.

Conserva il nome host. L’identità di licenza dell’istanza è il machine-id sul volume state e l’id dell’agente. Un nuovo volume state è una nuova installazione.

3. Impostazioni

Le impostazioni si leggono solo al primo avvio (l’installazione).

Impostazione Che cosa fa
HQBIRD_FB_PORT Porta Firebird dentro il container (predefinito 3050). HQ Monitor usa 20000 + questa porta
HQBIRD_HQM_PORT un’altra porta di HQ Monitor
HQBIRD_AGENT_ID l’id dell’agente (predefinito: ricavato dal nome dell’host, dalla data e dalla porta)
HQBIRD_HQM_LOGIN + segreto hqmonitor_password l’utente di HQ Monitor
HQBIRD_TRIAL_EMAIL, HQBIRD_TRIAL_ZONE chiedere una licenza di prova (accetti l’informativa sulla privacy)
HQBIRD_DEBUG=1 installare i file di debug di Firebird
segreto sysdba_password la password SYSDBA di un nuovo Firebird
segreto license un file di licenza
segreto attach attach.json da HQCenter: collegare l’agente al tuo HQCenter
HQBIRD_CLUSTER_ROLE master o replica: un cluster senza HQCenter (sezione 7). Vuoto: nessun cluster
HQBIRD_CLUSTER_ADDRESS master, obbligatorio: l’indirizzo o il nome DNS dell’host Docker, come li raggiungono il replica e il browser. Un elenco separato da virgole; il primo entra nel RCM URL
HQBIRD_CLUSTER_ID master: l’id del cluster (predefinito: il nome dell’host)
segreto rcm_password master: la password dell’utente RCM rcmadmin (predefinito: una generata)
HQBIRD_RCM_ALLOW replica: solo questi RCM possono invitare il container (IP, CIDR, nome host; predefinito: qualunque). Scrivi l’indirizzo dell’host Docker del master: il replica vede quell’indirizzo. Su un solo host Docker il replica vede il gateway della sua rete Docker
HQBIRD_PAIRING_PORT, HQBIRD_NODE_PORT lo slot del cluster: porta di pairing 7450-7459 e porta del nodo = porta di pairing - 399 (predefinito 7450 e 7051)

4. Volumi

Volume Percorso Contenuto
opt /opt Firebird, l’agente, HQ Monitor, nodo di cluster, RCM
state /var/lib/hqbird-container units, sudoers, dati di HQ Monitor, log dell’agente, machine-id, stato del setup, gli account del sistema operativo creati durante l’esecuzione (l’utente di servizio RCM)
trust /usr/libexec/hqbird-fbagent il programma di avvio degli aggiornamenti dell’agente e la fiducia
rootwork /var/lib/hqbird-fbagent la cartella di lavoro del programma di avvio degli aggiornamenti
db /db database (metti qui i tuoi database)
backup /backup copie di backup

Non montare cartelle dell’host su opt, state, trust e rootwork. Puoi usare cartelle dell’host per db e backup; dalle all’uid 84 (l’utente firebird dell’immagine):

Command
chown 84:84 /srv/hqbird/db /srv/hqbird/backup

Fai il backup di tutti e sei i volumi insieme.

5. Lavoro quotidiano

Attività Comando
Stato dei servizi docker compose exec hqbird systemctl list-units --type=service
Riavviare Firebird docker compose exec hqbird systemctl restart firebird (Firebird 3.0: firebird-superserver)
isql docker compose exec hqbird /opt/firebird/bin/isql -user SYSDBA localhost/<port>:/db/my.fdb
Log docker compose logs --since 1h
Arresto (Firebird chiude i database) docker compose stop

Dentro il container, systemctl controlla i servizi HQbird. Non è systemd: supporta i comandi che i programmi HQbird usano (start, stop, restart, status, is-active, enable, disable, show, list-units, daemon-reload).

6. Aggiornamenti

Ci sono due modi per aggiornare. Entrambi conservano i dati.

  • Da HQCenter (come su un server): HQCenter aggiorna l’agente, HQ Monitor, Firebird, il nodo di cluster e RCM dentro il container.

  • Nuova immagine: cambia image: alla nuova versione, poi:

    Command
    docker compose pull && docker compose up -d

    All’avvio, il container esegue l’installatore della nuova immagine in modalità di aggiornamento. Se HQCenter ha già aggiornato l’agente a una versione più recente di quella dell’immagine, l’installatore non viene eseguito (senza scendere di versione); il log lo dice.

Un nuovo container (una nuova immagine, oppure docker compose down e up -d senza -v) conserva il cluster: il ruolo, l’id del cluster, RCM, i nodi e il collegamento all’altro host sono sui volumi. Le impostazioni del cluster nel file compose non vengono rilette. Le immagini fino a 2027.2.32 hanno due difetti qui: vedi la sezione 9.

7. Cluster

Ci sono due modi per fare un cluster. Non mescolarli in uno stesso container.

7.1. Senza HQCenter: due container con un ruolo

Un container è il master ed esegue il gestore del cluster (RCM) con la sua console. L’altro è un replica. Il ruolo è un’impostazione del primo avvio: HQBIRD_CLUSTER_ROLE. Senza di esso il container non esegue RCM, non esegue un nodo di cluster e non apre alcuna porta di pairing. Il ruolo richiede l’immagine 2027.2.33 o successiva.

Due host Docker. Dai ai due container nomi host diversi (HQBIRD_HOSTNAME in .env, oppure hostname:): con lo stesso nome host i due agenti hanno lo stesso id, e RCM rifiuta il replica (duplicate). Copia compose.master.yaml sull’host master e compose.replica.yaml sull’host replica, accanto a compose.yaml (ops/docker/ della versione).

  1. Sull’host master, metti l’indirizzo di quell’host Docker in .env, come lo raggiungono l’host replica e il browser (non localhost, non l’indirizzo del container):

    Command
    echo 'HQBIRD_CLUSTER_ADDRESS=203.0.113.10' >> .env
    docker compose -f compose.yaml -f compose.master.yaml up -d
  2. Sull’host replica:

    Command
    docker compose -f compose.yaml -f compose.replica.yaml up -d
  3. Leggi le righe di cluster di ogni container:

    Command
    docker compose logs | grep -E 'cluster:|CA hash|Password'

    Il master mostra l’indirizzo della console e il CA hash: [hqbird-boot] cluster: role=master id=... console=https://203.0.113.10:7444 login=rcmadmin. Il replica mostra la sua porta di pairing e l’impronta: [hqbird-boot] cluster: role=replica pairing port 7450: open until ..., fingerprint sha256:....

  4. Apri la console https://<master host>:7444. L’utente è rcmadmin. Senza il segreto rcm_password la password è in un file; RCM ne chiede una nuova al primo accesso:

    Command
    docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password'
  5. In Settings → Link hosts scrivi due righe: l’indirizzo che hai indicato in HQBIRD_CLUSTER_ADDRESS (il master) e l’indirizzo dell’host Docker del replica. Non scrivi una porta: RCM legge le porte di pairing 7450-7459. La porta di pairing risponde circa 30 secondi dopo che il container è healthy. La finestra Initialize propone la cartella /databases/replica/..., che è fuori dai volumi: cambiala. Quella finestra è alta circa 1000 px e non scorre: riduci lo zoom della pagina se non ne vedi i pulsanti. Testato nel browser il 2026-11-16. Confronta l’impronta del replica con quella del suo log. Lascia RCM URL vuoto. Poi continua con il passaggio 4 della guida al cluster su Linux (cartella dei database, registrazione, inizializzare il replica). Per la cartella dei database del replica, usa una cartella del volume db, per esempio /db/replica. Testato: una riga scritta sul master era sul replica in 30 secondi.

Per saltare le opzioni -f, metti COMPOSE_FILE=compose.yaml:compose.master.yaml (oppure ...replica.yaml) in .env.

Un host Docker. compose.cluster-one-host.yaml è un file completo con entrambi i container:

Command
docker compose -f compose.cluster-one-host.yaml up -d

I container si raggiungono per nome sulla rete del progetto, quindi le porte del cluster non sono pubblicate. In Link hosts scrivi hqbird-master e hqbird-replica. Il Firebird del master è sulla porta 3050, quello del replica sulla 3051; la console è https://<docker host>:7444.

Regole:

  • Il ruolo e le sue impostazioni si leggono solo al primo avvio. In seguito un HQBIRD_CLUSTER_ROLE diverso scrive un avviso nel log e non cambia nulla. Per cambiare il cluster in seguito, usa HQ Monitor (Clusters) oppure i comandi fbagent --cluster-init e fbagent --cluster-pairing dentro il container.
  • Un’impostazione errata (un ruolo sconosciuto, un master senza HQBIRD_CLUSTER_ADDRESS, un’impostazione dell’altro ruolo) ferma l’avvio prima che venga installato qualcosa. Il log dice che cosa scrivere ([hqbird-boot] error: ...); Docker avvia di nuovo il container e il log ripete la riga finché non correggi l’impostazione.
  • La finestra di pairing di un replica resta aperta 24 ore. Un riavvio di un container che non è ancora in nessun cluster la riapre. Per chiudere la porta di pairing verso le altre reti, usa HQBIRD_RCM_ALLOW o il firewall; dopo il collegamento puoi togliere la porta da ports:.
  • Per uno switchover (un servizio RCM), ogni host ha bisogno di un secondo nodo e della sua porta pubblicata: vedi la sezione 7.3.

7.2. Con HQCenter

HQCenter aggiunge l’istanza a un cluster come aggiunge un server. Non impostare HQBIRD_CLUSTER_ROLE. In HQCenter, indica l’indirizzo dell’host Docker come indirizzo del membro. In compose.yaml, pubblica le porte dei componenti del cluster:

Componente Porta Pubblicare quando
nodo di cluster il listen_port del nodo (per esempio 7051) l’istanza è un membro del cluster
RCM 7443 HQCenter fa di questo agente l’RCM
console operatore RCM 7444 come sopra; imposta operator_addr a 0.0.0.0:7444 nelle impostazioni di RCM

L’agente installa il nodo (e RCM) qualche minuto dopo che il cluster è salvato. Fino ad allora la porta del nodo non risponde. In HQCenter, imposta il listen_port del nodo sulla porta pubblicata. Un replica aspetta finché l’agente RCM non carica la CA del cluster.

Testato il 2026-11-16 senza un ruolo: gli agenti hanno installato i nodi e RCM, e tutti i membri erano di nuovo running dopo docker compose down e up -d.

7.3. Switchover tra i due container

Un servizio RCM sposta il ruolo master di un database da un host all’altro. Per un servizio, ogni host ha bisogno di due nodi: un nodo master e un nodo replica. Link hosts dà a ogni host un nodo, quindi aggiungi tu i secondi nodi. Testato il 2026-11-16 sulla coppia della sezione 7.1: lo switchover ha richiesto 25 secondi, il vecchio master è diventato un replica in sola lettura, e una riga scritta sul nuovo master c’era 15 secondi dopo.

I passaggi usano l’API operatore di RCM sulla porta della console. curl chiede la password di rcmadmin; -k salta il controllo del certificato proprio del cluster:

Command
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }
  1. Pubblica la porta del secondo nodo su entrambi gli host: porta del nodo + 10. In compose.master.yaml e compose.replica.yaml, togli il # dalla riga "7061:7061", poi esegui docker compose up -d con le stesse opzioni -f. Fallo prima del primo avvio quando puoi.

  2. Dai a ogni nodo l’indirizzo del suo host Docker. RCM dà questo indirizzo e la porta Firebird alle applicazioni; senza di esso ottengono l’indirizzo del container:

    Command
    api -X PUT $RCM/v1/nodes/<master node id>/config -d '{"advertise_addr":"203.0.113.10"}'
    api -X PUT $RCM/v1/nodes/<replica node id>/config -d '{"advertise_addr":"203.0.113.20"}'

    api $RCM/v1/nodes mostra gli id dei nodi (<host name>-master, <host name>-replica).

  3. Aggiungi i secondi nodi al documento del cluster: un nodo master sull’host replica e il suo nodo replica sull’host master, entrambi con listen_port 7061. Leggi il documento, aggiungi due membri e un link, e rimandalo con la sua revisione:

    Command
    api $RCM/v1/admin/clusters/<cluster id> > cluster.json    # note "revision"
    # add to "members":
    #   {"member_id":"<host B>-master","agent_id":"<agent id of host B>","role":"master","addresses":["203.0.113.20"],"listen_port":7061}
    #   {"member_id":"<host A>-replica","agent_id":"<agent id of host A>","role":"replica","addresses":["203.0.113.10"],"listen_port":7061}
    # add to "links": {"from":"<host B>-master","to":"<host A>-replica"}
    api -X POST $RCM/v1/admin/clusters/<cluster id>/validate --data-binary @cluster.json
    api -X PUT -H 'If-Match: <revision>' $RCM/v1/admin/clusters/<cluster id> --data-binary @cluster.json

    Gli agenti installano allora i due servizi di nodo (30 secondi nel test su due host; può richiedere alcuni minuti). docker compose exec hqbird systemctl list-units --type=service mostra allora due servizi hqclusternode in ogni container.

    Poi dai a entrambi i nodi replica una cartella di database sul volume db. Senza di essa, uno switchover di ritorno o un failover si ferma dopo il punto di non ritorno, e il servizio va a failed:

    Command
    for n in <host A>-replica <host B>-replica; do
      api -X POST $RCM/v1/nodes/$n/databases/root/prepare -d '{"root":"/db/replica"}'
      api -X PUT $RCM/v1/nodes/$n/config -d '{"databases":{"root":"/db/replica"}}'
    done
  4. Definisci il servizio. host è l’id dell’agente dell’host. Il percorso sul secondo host è il percorso del file del replica: <database folder of the replica>/<master member id>/<file>:

    Command
    cat > service.json <<'J'
    {"alias":"shop","router_port":3051,"members":[
     {"host":"<agent id of host A>","master_node":"<host A>-master","replica_node":"<host A>-replica","path":"/db/shop.fdb","priority":100},
     {"host":"<agent id of host B>","master_node":"<host B>-master","replica_node":"<host B>-replica","path":"/db/replica/<host A>-master/shop.fdb","priority":50}]}
    J
    api -X PUT "$RCM/v1/services/shop?check=1" --data-binary @service.json   # a check, nothing is stored
    api -X PUT $RCM/v1/services/shop --data-binary @service.json
  5. Controlla, poi commuta:

    Command
    api $RCM/v1/services/shop/master                       # the master now, the replicas, problems
    api -X POST $RCM/v1/services/shop/switchover/check -d '{}'
    api -X POST $RCM/v1/services/shop/switchover -d '{}'   # gives "operation_id"
    api $RCM/v1/operations/<operation id>

Dopo lo switchover, .../services/shop/master dà l’indirizzo dell’altro host Docker e la sua porta Firebird. Le applicazioni devono connettersi a quell’indirizzo. Uno switchover ha bisogno di un replica che sia IN_SYNC: lo è, dopo la prima scrittura sul master (35 secondi nel test).

Router e failover automatico. Un router (HAProxy) dà alle applicazioni un indirizzo che segue il master. Nelle immagini fino a 2027.2.33 il router non si avvia (sezione 9); l’immagine successiva contiene la correzione. Il failover automatico ha bisogno di un router come testimone. Testato il 2026-11-17 in laboratorio, su 2027.2.33 con una soluzione di ripiego e su un’immagine di test con la correzione:

  • Un router è un membro del cluster con il ruolo router. L’agente installa il pacchetto haproxy dal repository Debian, anche in ogni nuovo container: il container ha bisogno di accesso al repository. Pubblica la porta del router (3051 nell’esempio).

  • Con un router solo sull’host RCM, RCM ha spostato il master da solo 84 secondi dopo che il container dell’altro host si è fermato; l’operazione ha richiesto 10 secondi. Quando quell’host è tornato, rejoin lo ha reso di nuovo il replica.

  • Con un router su ogni host il failover automatico non parte: più della metà dei router deve riferire, e uno dei due è sull’host perso.

  • L’RCM gira nel container master. Quando quell’host si perde, si perde anche l’RCM, e niente sposta il master da solo.

8. Porte, firewall, seconda istanza

Pubblica ogni porta con lo stesso numero fuori e dentro il container (3051:3051, non 3051:3050). L’agente e il cluster riportano la porta che vedono dentro il container.

Porta Cosa Necessario
HQBIRD_FB_PORT (3050) Firebird sempre
20000 + porta Firebird (23050) HQ Monitor sempre
listen_port del nodo (7051) nodo di cluster membro del cluster
porta del nodo + 10 (7061) il secondo nodo dell’host un servizio con switchover (sezione 7.3)
7443, 7444 RCM, console operatore RCM questo agente è l’RCM (uno per host)
porta di pairing (7450) la porta di pairing dell’agente un replica con un ruolo, finché non è collegato

L’agente si collega a HQCenter da solo (in uscita); non gli serve una porta in ingresso.

Docker pubblica le porte oltre ufw. Testato: con ufw che consentiva solo la porta 22, le porte di Firebird e di HQ Monitor erano aperte da internet. Usa un firewall esterno, pubblica su un indirizzo dell’host ("10.0.0.5:23050:23050"), o aggiungi regole alla catena iptables DOCKER-USER.

Una seconda istanza su un host ha bisogno della propria cartella, del name: del progetto, hostname, HQBIRD_FB_PORT e delle porte. Il nome del progetto forma i nomi dei volumi (<name>_opt, …): con lo stesso nome, il secondo avvio prende i volumi e il container del primo.

Istanza 1 Istanza 2
name:, hostname: hqbird-fb40-3051 hqbird-fb40-3052
HQBIRD_FB_PORT 3051 3052
ports: 3051, 23051, 7052 3052, 23052, 7053

Regole per N istanze su un IP esterno:

  • Firebird 3050 + N, HQ Monitor 20000 + la porta Firebird, nodo di cluster 7051 + N (imposta lo stesso listen_port in HQCenter). Salta 3050, 23050 e 7051 quando l’host esegue già un Firebird o HQbird fuori da Docker.
  • Solo un’istanza per host può essere l’RCM (7443, 7444).
  • Con un ruolo di cluster (sezione 7.1), ogni istanza di un host ha bisogno del proprio slot: HQBIRD_PAIRING_PORT=7451 e HQBIRD_NODE_PORT=7052 per la seconda, 7452 e 7053 per la terza.
  • Un’istanza usa circa 200-250 MB di memoria senza carico. Testato: tre istanze FB 4.0 su 2 vCPU / 4 GB, una con carico.
  • Le altre linee Firebird sullo stesso host seguono le stesse regole con la propria immagine (hqbird2027-fb50, …) e i nomi (hqbird-fb50-3054).

Aggiungi un’istanza (qui la terza: 3053, 23053, 7054) dal compose.yaml della prima. Sostituire 3051 cambia anche name:, hostname:, HQBIRD_FB_PORT e la porta di HQ Monitor:

Command
sudo ss -ltnp | grep -E ':(3053|23053|7054)\b'     # must print nothing
sudo mkdir -p /srv/hqbird-fb40-3053/secrets
cd /srv/hqbird-fb40-3053
sudo sh -c 'openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password'
sudo sed -e 's/3051/3053/g' -e 's/7052/7054/g' /srv/hqbird-fb40-3051/compose.yaml | sudo tee compose.yaml >/dev/null
sudo docker compose config | grep -E '^name:|hostname:|HQBIRD_FB_PORT|published:'
sudo docker compose up -d
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

9. Problemi noti

  • Dopo aver collegato l’agente a HQCenter con fbagent --enroll a mano, esegui fbagent --refresh-apply-launcher come root, oppure l’autoaggiornamento dell’agente fallisce con “no goafts CA is pinned”.
  • Negli script, esegui docker compose exec con -T e </dev/null. Senza di essi legge lo standard input e prende il resto di uno script che invii con ssh ... bash -s.
  • Prima che l’agente sia collegato a HQCenter, il suo log mostra gli avvisi goafts mTLS settings are incomplete e bootstrap CA not found. Questo è normale.
  • Il container assegna /opt/hqbird a root dopo ogni installazione (l’autoaggiornamento dell’agente ne ha bisogno). L’agente scrive un avviso: non può aggiornare /opt/hqbird/version.json; puoi ignorarlo.
  • Immagini fino a 2027.2.32: cartelle aperte in scrittura. In queste immagini /etc, /usr e /usr/lib hanno il modo 0777, e alcuni file del container sono scrivibili da tutti gli account. Qualsiasi account nel container può cambiare ciò che root avvia. L’agente rifiuta anche una cartella del genere (root trust directory: /usr is writable by group or others): l’installatore in modalità di aggiornamento fallisce allora in un nuovo container, e il container si avvia di continuo. Usa l’immagine 2027.2.33 o successiva. Non dare accesso shell nel container di un’immagine più vecchia a utenti di cui non ti fidi.
  • Immagini fino a 2027.2.32: un RCM creato a mano non si avvia in un nuovo container. Quando crei RCM con fbagent --cluster-init dentro il container, l’agente crea l’account del sistema operativo hqbirdrcm. Un nuovo container non lo ha (User=hqbirdrcm: invalid userid, il container è unhealthy). Le immagini più recenti conservano gli account sul volume state. Un cluster creato da HQCenter non è interessato.
  • Immagini fino a 2027.2.33: un router (HAProxy) non si avvia. Per un membro del cluster con il ruolo router l’agente installa il pacchetto haproxy e il servizio del router, ma haproxy.service fallisce. Il sostituto di systemd nell’immagine non mette i valori di $CONFIG, $PIDFILE e $EXTRAOPTS nella riga di comando e non legge alcun file drop-in, e niente crea la cartella /run/haproxy. L’immagine successiva contiene la correzione. Fino ad allora, dai alle applicazioni l’indirizzo da .../services/<alias>/master e non aggiungere un membro router.
  • Immagine 2027.2.33: un nuovo container non si avvia dopo che è stato aggiunto un router. Il log contiene chown: invalid user: 'haproxy', e Docker avvia il container di continuo. Per avviarlo, rimuovi il file usr/lib/tmpfiles.d/haproxy.conf sul volume state. L’immagine successiva contiene la correzione.

10. Costruire le immagini

Per il team della versione. Su un host Windows con i file della versione in dist\releases, accedi a GHCR con un token che ha write:packages, poi costruisci, invia e firma:

Command
Get-Content token.txt | docker login ghcr.io -u <GitHub user> --password-stdin
.\ops\docker\Build-HqbirdImage.ps1 -Line 50 -SetupVersion 2027.2.33 -Registry ghcr.io/ibsurgeon -Tag 2027.2 -Push -CosignKey cosign.key

Un pacchetto nuovo (il primo invio di una linea) è privato. Nelle impostazioni del pacchetto dell’organizzazione IBSurgeon, imposta la visibilità su pubblica.

-ContextOnly prepara solo la cartella di costruzione (dist\hqbird2027-docker\fbNN-<version>) e stampa il comando docker build da eseguire su un host Docker Linux.

La costruzione si ferma quando una cartella o un file dell’immagine sotto /etc o /usr è scrivibile da tutti gli account (la cartella di costruzione arriva da Windows, dove i modi si perdono). I test degli script del container, delle impostazioni del cluster e dei file compose: go test ./ops/docker/.