HQbird 2027 in Docker: administrator guide
This guide is for the administrator who runs HQbird 2027 in Docker. One container is one Firebird instance with all HQbird components:
- Firebird (the HQbird build of one line: 5.0, 4.0, 3.0 or 2.5);
- HQbird agent (
fbagent): backups, monitoring, maintenance jobs, updates, the connection to HQCenter; - HQ Monitor: the web console of the instance;
- cluster node (
hqclusternode) and RCM (hqbirdrcm): installed by the agent when HQCenter adds this instance to a cluster, or when you give the container a cluster role (section 7). Without a role and without HQCenter, the container runs no cluster component.
The container installs HQbird with the same offline installer as a server (Linux setup guide). The agent then updates Firebird, HQ Monitor, the cluster components and itself from HQCenter, as on a server. Your data, configuration, license, HQCenter certificates and the updated programs are on volumes: they stay when you create the container again or change the image.
Current release: 2027.2.33 (2026-11-16): Firebird 2.5.9, 3.0.15, 4.0.8 and 5.0.5, agent 3.4.0, HQ Monitor 1.57.0, RCM and node 2027.5.12.
Tested 2026-11-16 on Ubuntu 22.04.5 (2 vCPU / 4 GB), Docker 29.10.0,
Compose 5.7.1, image hqbird2027-fb40:2027.2.33 (first test: 2026-11-11,
image 2027.2.27). A step-by-step install
for Ubuntu 22.04: hqbird2027-docker-install-fb40.ru.md
(Russian), hqbird2027-docker-install-fb40.pt.md
(Portuguese).
The cluster role (section 7.1) and the switchover (section 7.3) were tested
2026-11-16 on the 5.0, 4.0, 3.0 and 2.5 images, with the two “hosts” as two
addresses of one VM, and on two separate Docker hosts (two droplets, the
4.0 image 2027.2.33). On 2026-11-17 the rest was tested on two Docker hosts
with the 5.0 image 2027.2.33: a cluster made by hand in 2027.2.32
containers and moved to the new image (both containers healthy in 35
seconds), HQBIRD_RCM_ALLOW, the Services pages of the RCM console and
the automatic failover. Routers (HAProxy) do not start in the images up to
2027.2.33 (section 9); the next image has the fix.
1. Images
| Image | Firebird | Default port |
|---|---|---|
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 |
The images are in the GitHub Container Registry of IBSurgeon
(https://github.com/orgs/IBSurgeon/packages). They are public: you do
not need to log in. <version> is the HQbird setup version, for example
2027.2.33. The tag 2027.2 is the newest 2027.2.x image.
docker pull ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.33The images are signed with cosign. The public key hqbird-cosign.pub is
not published yet (2026-11-16). The 2027.2.33 images are signed. When you have the key, check an image
before you use it:
cosign verify --key hqbird-cosign.pub ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.332. First start
-
Copy
compose.yaml(fromops/docker/of the release) to a folder on the Docker host. -
Put the SYSDBA password in a file, readable only by you:
mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password -
In
compose.yaml, setimage:,hostname:, and remove the#from thesecrets:lines you use. -
Start the container:
docker compose up -d -
Watch the installation (some minutes on the first start):
docker compose logs -fOn 2 vCPU the installation takes about 20 seconds. It is done when the log shows
[hqbird-boot] ready: firebird.service=active ...anddocker compose psshowshealthy.
Then:
- Firebird:
<docker host>:3050. - HQ Monitor:
http://<docker host>:23050/, loginadmin. The installer makes the password; read it withdocker compose exec hqbird cat /opt/hqbird/conf/access.properties. - The agent id in HQCenter: the hostname + the install date (YYMMDD) +
-fbNN, for examplehqbird-fb40-3051261111-fb40.
Keep the hostname. The license identity of the instance is the
machine-id on the state volume and the agent id. A new state volume is
a new installation.
3. Settings
The settings are read on the first start only (the installation).
| Setting | What it does |
|---|---|
HQBIRD_FB_PORT |
Firebird port inside the container (default 3050). HQ Monitor uses 20000 + this port |
HQBIRD_HQM_PORT |
another HQ Monitor port |
HQBIRD_AGENT_ID |
the agent id (default: made from the host name, the date and the port) |
HQBIRD_HQM_LOGIN + secret hqmonitor_password |
the HQ Monitor login |
HQBIRD_TRIAL_EMAIL, HQBIRD_TRIAL_ZONE |
ask for a trial license (you accept the privacy policy) |
HQBIRD_DEBUG=1 |
install the Firebird debug files |
secret sysdba_password |
the SYSDBA password of a new Firebird |
secret license |
a license file |
secret attach |
attach.json from HQCenter: connect the agent to your HQCenter |
HQBIRD_CLUSTER_ROLE |
master or replica: a cluster without HQCenter (section 7). Empty: no cluster |
HQBIRD_CLUSTER_ADDRESS |
master, required: the address or DNS name of the Docker host, as the replica and your browser reach it. A list with commas; the first one goes into the RCM URL |
HQBIRD_CLUSTER_ID |
master: the cluster id (default: the host name) |
secret rcm_password |
master: the password of the RCM login rcmadmin (default: a generated one) |
HQBIRD_RCM_ALLOW |
replica: only these RCMs may invite the container (IP, CIDR, host name; default: any). Write the address of the master’s Docker host: the replica sees that address. On one Docker host the replica sees the gateway of its Docker network |
HQBIRD_PAIRING_PORT, HQBIRD_NODE_PORT |
the cluster slot: pairing port 7450-7459 and node port = pairing port - 399 (default 7450 and 7051) |
4. Volumes
| Volume | Path | Contents |
|---|---|---|
opt |
/opt |
Firebird, the agent, HQ Monitor, cluster node, RCM |
state |
/var/lib/hqbird-container |
units, sudoers, HQ Monitor data, agent logs, machine-id, setup state, the OS accounts made at run time (the RCM service user) |
trust |
/usr/libexec/hqbird-fbagent |
the agent’s update launcher and trust |
rootwork |
/var/lib/hqbird-fbagent |
the update launcher’s work folder |
db |
/db |
databases (put your databases here) |
backup |
/backup |
backups |
Do not mount host folders on opt, state, trust and rootwork. You can
use host folders for db and backup; give them to uid 84 (the firebird
user of the image):
chown 84:84 /srv/hqbird/db /srv/hqbird/backupBack up all six volumes together.
5. Daily work
| Task | Command |
|---|---|
| Status of the services | docker compose exec hqbird systemctl list-units --type=service |
| Restart 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 |
| Logs | docker compose logs --since 1h |
| Stop (Firebird closes the databases) | docker compose stop |
Inside the container, systemctl controls the HQbird services. It is not
systemd: it supports the commands the HQbird programs use (start, stop,
restart, status, is-active, enable, disable, show,
list-units, daemon-reload).
6. Updates
There are two ways to update. Both keep your data.
-
From HQCenter (as on a server): HQCenter updates the agent, HQ Monitor, Firebird, the cluster node and RCM inside the container.
-
New image: change
image:to the new version, then:docker compose pull && docker compose up -dOn the start, the container runs the installer of the new image in update mode. If HQCenter already updated the agent to a newer version than the image has, the installer is not run (no downgrade); the log says so.
A new container (a new image, or docker compose down and up -d without
-v) keeps the cluster: the role, the cluster id, RCM, the nodes and the
link to the other host are on the volumes. The cluster settings in the
compose file are not read again. Images up to 2027.2.32 have two defects
here: see section 9.
7. Cluster
There are two ways to make a cluster. Do not mix them in one container.
7.1. Without HQCenter: two containers with a role
One container is the master and runs the cluster manager (RCM) with its
console. The other is a replica. The role is a setting of the first
start: HQBIRD_CLUSTER_ROLE. Without it the container runs no RCM, no
cluster node and opens no pairing port. The role needs the image 2027.2.33 or
newer.
Two Docker hosts. Give the two containers different host names
(HQBIRD_HOSTNAME in .env, or hostname:): with the same host name
the two agents have the same id, and RCM refuses the replica
(duplicate). Copy compose.master.yaml to the master host and
compose.replica.yaml to the replica host, beside compose.yaml
(ops/docker/ of the release).
-
On the master host, put the address of that Docker host in
.env, as the replica host and your browser reach it (notlocalhost, not the address of the container):echo 'HQBIRD_CLUSTER_ADDRESS=203.0.113.10' >> .env docker compose -f compose.yaml -f compose.master.yaml up -d -
On the replica host:
docker compose -f compose.yaml -f compose.replica.yaml up -d -
Read the cluster lines of each container:
docker compose logs | grep -E 'cluster:|CA hash|Password'The master shows the console address and the
CA hash:[hqbird-boot] cluster: role=master id=... console=https://203.0.113.10:7444 login=rcmadmin. The replica shows its pairing port and fingerprint:[hqbird-boot] cluster: role=replica pairing port 7450: open until ..., fingerprint sha256:.... -
Open the console
https://<master host>:7444. The login isrcmadmin. Without the secretrcm_passwordthe password is in a file; RCM asks for a new one at the first login:docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password' -
In Settings → Link hosts write two lines: the address you gave in
HQBIRD_CLUSTER_ADDRESS(the master) and the address of the replica’s Docker host. You do not write a port: RCM reads the pairing ports 7450-7459. The pairing port answers about 30 seconds after the container ishealthy. The Initialize window proposes the folder/databases/replica/..., which is outside the volumes: change it. That window is about 1000 px high and does not scroll: zoom the page out if you do not see its buttons. Tested in the browser 2026-11-16. Compare the fingerprint of the replica with the one in its log. Leave RCM URL empty. Then continue with step 4 of Linux cluster guide (database folder, enroll, initialize the replica). For the database folder of the replica, use a folder on thedbvolume, for example/db/replica. Tested: a row written on the master was on the replica in 30 seconds.
To skip the -f options, put
COMPOSE_FILE=compose.yaml:compose.master.yaml (or ...replica.yaml) in
.env.
One Docker host. compose.cluster-one-host.yaml is a complete file
with both containers:
docker compose -f compose.cluster-one-host.yaml up -dThe containers reach each other by name on the network of the project, so
the cluster ports are not published. In Link hosts write
hqbird-master and hqbird-replica. The master’s Firebird is on port
3050, the replica’s on 3051; the console is https://<docker host>:7444.
Rules:
- The role and its settings are read at the first start only. Later a
different
HQBIRD_CLUSTER_ROLEgives a warning in the log and changes nothing. To change the cluster later, use HQ Monitor (Clusters) or thefbagent --cluster-initandfbagent --cluster-pairingcommands inside the container. - A wrong setting (an unknown role, a master without
HQBIRD_CLUSTER_ADDRESS, a setting of the other role) stops the start before anything is installed. The log says what to write ([hqbird-boot] error: ...); Docker starts the container again and the log repeats the line until you correct the setting. - The pairing window of a replica is open for 24 hours. A restart of a
container that is in no cluster yet opens it again. To close the
pairing port to other networks, use
HQBIRD_RCM_ALLOWor your firewall; after the link you can take the port out ofports:. - For a switchover (an RCM service), each host needs a second node and its published port: see section 7.3.
7.2. With HQCenter
HQCenter adds the instance to a cluster as it adds a server. Do not set
HQBIRD_CLUSTER_ROLE. In HQCenter, give the address of the Docker host
as the member address. In compose.yaml, publish the ports of the cluster
components:
| Component | Port | Publish when |
|---|---|---|
| cluster node | the node’s listen_port (for example 7051) |
the instance is a cluster member |
| RCM | 7443 | HQCenter makes this agent the RCM |
| RCM operator console | 7444 | as above; set operator_addr to 0.0.0.0:7444 in the RCM settings |
The agent installs the node (and RCM) some minutes after the cluster is
saved. Until then the node port does not answer.
In HQCenter, set the node’s listen_port to the published port. A replica waits until the RCM agent uploads the cluster CA.
Tested 2026-11-16 without a role: the agents installed the nodes and RCM,
and all members were running again after docker compose down and
up -d.
7.3. Switchover between the two containers
An RCM service moves the master role of a database from one host to the other. For a service, each host needs two nodes: a master node and a replica node. Link hosts gives each host one node, so you add the second nodes yourself. Tested 2026-11-16 on the pair of section 7.1: the switchover took 25 seconds, the old master became a read-only replica, and a row written on the new master was on it 15 seconds later.
The steps use the RCM operator API on the console port. curl asks for
the password of rcmadmin; -k skips the check of the cluster’s own
certificate:
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }-
Publish the second node port on both hosts: node port + 10. In
compose.master.yamlandcompose.replica.yaml, remove the#from the line"7061:7061", then rundocker compose up -dwith the same-foptions. Do this before the first start when you can. -
Give each node the address of its Docker host. RCM gives this address and the Firebird port to the applications; without it they get the address of the container:
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/nodesshows the node ids (<host name>-master,<host name>-replica). -
Add the second nodes to the cluster document: a master node on the replica host and its replica node on the master host, both with
listen_port7061. Read the document, add two members and one link, and send it back with its revision: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.jsonThe agents then install the two node services (30 seconds in the test on two hosts; it can take some minutes).
docker compose exec hqbird systemctl list-units --type=servicethen shows twohqclusternodeservices in each container.Then give both replica nodes a database folder on the
dbvolume. Without it, a switchover back or a failover stops after the point of no return, and the service goes tofailed: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 -
Define the service.
hostis the agent id of the host. The path on the second host is the path of the replica file:<database folder of the replica>/<master member id>/<file>: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 -
Check, then switch:
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>
After the switchover, .../services/shop/master gives the address of the
other Docker host and its Firebird port. The applications must connect to
that address. A switchover needs a replica that is IN_SYNC: it is, after
the first write on the master (35 seconds in the test).
Routers and automatic failover. A router (HAProxy) gives the applications one address that follows the master. In the images up to 2027.2.33 the router does not start (section 9); the next image has the fix. The automatic failover needs a router as a witness. Tested 2026-11-17 in the lab, on 2027.2.33 with a workaround and on a test image with the fix:
-
A router is a cluster member with the role
router. The agent installs thehaproxypackage from the Debian repository, also in each new container: the container needs access to the repository. Publish the router port (3051 in the example). -
With a router on the RCM host only, RCM moved the master by itself 84 seconds after the container of the other host stopped; the operation took 10 seconds. When that host came back,
rejoinmade it the replica again. -
With a router on each host the automatic failover does not start: more than half of the routers must report, and one of the two is on the lost host.
-
The RCM runs in the master container. When that host is lost, the RCM is lost too, and nothing moves the master by itself.
8. Ports, firewall, second instance
Publish each port with the same number outside and inside the container
(3051:3051, not 3051:3050). The agent and the cluster report the port
they see inside the container.
| Port | What | Needed |
|---|---|---|
HQBIRD_FB_PORT (3050) |
Firebird | always |
| 20000 + Firebird port (23050) | HQ Monitor | always |
node listen_port (7051) |
cluster node | cluster member |
| node port + 10 (7061) | the second node of the host | a service with a switchover (section 7.3) |
| 7443, 7444 | RCM, RCM operator console | this agent is the RCM (one per host) |
| pairing port (7450) | the agent’s pairing port | a replica with a role, until it is linked |
The agent connects to HQCenter itself (outbound); it needs no inbound port.
Docker publishes ports past ufw. Tested: with ufw allowing only port 22,
the Firebird and HQ Monitor ports were open from the internet. Use an
external firewall, publish on one host address ("10.0.0.5:23050:23050"),
or add rules to the iptables chain DOCKER-USER.
A second instance on one host needs its own folder, project name:,
hostname, HQBIRD_FB_PORT and ports. The project name makes the volume
names (<name>_opt, …): with the same name, the second start takes the
volumes and the container of the first.
| Instance 1 | Instance 2 | |
|---|---|---|
name:, hostname: |
hqbird-fb40-3051 |
hqbird-fb40-3052 |
HQBIRD_FB_PORT |
3051 | 3052 |
ports: |
3051, 23051, 7052 | 3052, 23052, 7053 |
Rules for N instances on one external IP:
- Firebird
3050 + N, HQ Monitor20000 +the Firebird port, cluster node7051 + N(set the samelisten_portin HQCenter). Skip 3050, 23050 and 7051 when the host already runs a Firebird or HQbird outside Docker. - Only one instance per host can be the RCM (7443, 7444).
- With a cluster role (section 7.1), each instance of a host needs its own
slot:
HQBIRD_PAIRING_PORT=7451andHQBIRD_NODE_PORT=7052for the second one,7452and7053for the third. - One instance uses about 200-250 MB of memory without load. Tested: three FB 4.0 instances on 2 vCPU / 4 GB, one with load.
- Other Firebird lines on the same host follow the same rules with their
own image (
hqbird2027-fb50, …) and names (hqbird-fb50-3054).
Add an instance (here the third: 3053, 23053, 7054) from the first one’s
compose.yaml. Replacing 3051 also changes name:, hostname:,
HQBIRD_FB_PORT and the HQ Monitor port:
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. Known issues
- After you connect the agent to HQCenter with
fbagent --enrollby hand, runfbagent --refresh-apply-launcheras root, or the agent’s self-update fails with “no goafts CA is pinned”. - In scripts, run
docker compose execwith-Tand</dev/null. Without them it reads standard input and takes the rest of a script that you send withssh ... bash -s. - Before the agent is connected to HQCenter, its log shows the warnings
goafts mTLS settings are incompleteandbootstrap CA not found. This is normal. - The container gives
/opt/hqbirdto root after each installation (the agent’s self-update needs it). The agent writes a warning that it cannot update/opt/hqbird/version.json; you can ignore it. - Images up to 2027.2.32: folders open for writing. In these images
/etc,/usrand/usr/libhave the mode 0777, and some files of the container are writable by all accounts. Any account in the container can change what root starts. The agent also refuses such a folder (root trust directory: /usr is writable by group or others): the installer in update mode then fails in a new container, and the container starts again and again. Use the image 2027.2.33 or newer. Do not give shell access in the container of an older image to users you do not trust. - Images up to 2027.2.32: RCM made by hand does not start in a new
container. When you make RCM with
fbagent --cluster-initinside the container, the agent makes the OS accounthqbirdrcm. A new container does not have it (User=hqbirdrcm: invalid userid, the container isunhealthy). Newer images keep the accounts on thestatevolume. A cluster made by HQCenter is not affected. - Images up to 2027.2.33: a router (HAProxy) does not start. For a
cluster member with the role
routerthe agent installs thehaproxypackage and the router service, buthaproxy.servicefails. The stand-in for systemd in the image does not put the values of$CONFIG,$PIDFILEand$EXTRAOPTSinto the command line and reads no drop-in file, and nothing makes the folder/run/haproxy. The next image has the fix. Until then, give the applications the address from.../services/<alias>/masterand do not add aroutermember. - Image 2027.2.33: a new container does not start after a router was
added. The log has
chown: invalid user: 'haproxy', and Docker starts the container again and again. To start it, remove the fileusr/lib/tmpfiles.d/haproxy.confon thestatevolume. The next image has the fix.
10. Build the images
For the release team. On a Windows host with the release files in
dist\releases, log in to GHCR with a token that has write:packages,
then build, push and sign:
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.keyA new package (the first push of a line) is private. In the package settings of the IBSurgeon organization, set its visibility to public.
-ContextOnly stages the build folder only
(dist\hqbird2027-docker\fbNN-<version>) and prints the docker build
command to run on a Linux Docker host.
The build stops when a folder or a file of the image under /etc or /usr
is writable by all accounts (the build folder comes from Windows, where the
modes are lost). The tests of the container scripts, the cluster settings
and the compose files: go test ./ops/docker/.