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.

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

The 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:

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

2. First start

  1. Copy compose.yaml (from ops/docker/ of the release) to a folder on the Docker host.

  2. Put the SYSDBA password in a file, readable only by you:

    Command
    mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password
  3. In compose.yaml, set image:, hostname:, and remove the # from the secrets: lines you use.

  4. Start the container:

    Command
    docker compose up -d
  5. Watch the installation (some minutes on the first start):

    Command
    docker compose logs -f

    On 2 vCPU the installation takes about 20 seconds. It is done when the log shows [hqbird-boot] ready: firebird.service=active ... and docker compose ps shows healthy.

Then:

  • Firebird: <docker host>:3050.
  • HQ Monitor: http://<docker host>:23050/, login admin. The installer makes the password; read it with docker compose exec hqbird cat /opt/hqbird/conf/access.properties.
  • The agent id in HQCenter: the hostname + the install date (YYMMDD) + -fbNN, for example hqbird-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):

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

Back 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:

    Command
    docker compose pull && docker compose up -d

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

  1. On the master host, put the address of that Docker host in .env, as the replica host and your browser reach it (not localhost, not the address of the container):

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

    Command
    docker compose -f compose.yaml -f compose.replica.yaml up -d
  3. Read the cluster lines of each container:

    Command
    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:....

  4. Open the console https://<master host>:7444. The login is rcmadmin. Without the secret rcm_password the password is in a file; RCM asks for a new one at the first login:

    Command
    docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password'
  5. 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 is healthy. 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 the db volume, 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:

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

The 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_ROLE gives a warning in the log and changes nothing. To change the cluster later, use HQ Monitor (Clusters) or the fbagent --cluster-init and fbagent --cluster-pairing commands 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_ALLOW or your firewall; after the link you can take the port out of ports:.
  • 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:

Command
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }
  1. Publish the second node port on both hosts: node port + 10. In compose.master.yaml and compose.replica.yaml, remove the # from the line "7061:7061", then run docker compose up -d with the same -f options. Do this before the first start when you can.

  2. 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:

    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 shows the node ids (<host name>-master, <host name>-replica).

  3. 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_port 7061. Read the document, add two members and one link, and send it back with its revision:

    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

    The 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=service then shows two hqclusternode services in each container.

    Then give both replica nodes a database folder on the db volume. Without it, a switchover back or a failover stops after the point of no return, and the service goes to 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. Define the service. host is 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>:

    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. Check, then switch:

    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>

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 the haproxy package 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, rejoin made 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 Monitor 20000 + the Firebird port, cluster node 7051 + N (set the same listen_port in 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=7451 and HQBIRD_NODE_PORT=7052 for the second one, 7452 and 7053 for 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:

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. Known issues

  • After you connect the agent to HQCenter with fbagent --enroll by hand, run fbagent --refresh-apply-launcher as root, or the agent’s self-update fails with “no goafts CA is pinned”.
  • In scripts, run docker compose exec with -T and </dev/null. Without them it reads standard input and takes the rest of a script that you send with ssh ... bash -s.
  • Before the agent is connected to HQCenter, its log shows the warnings goafts mTLS settings are incomplete and bootstrap CA not found. This is normal.
  • The container gives /opt/hqbird to 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, /usr and /usr/lib have 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-init inside the container, the agent makes the OS account hqbirdrcm. A new container does not have it (User=hqbirdrcm: invalid userid, the container is unhealthy). Newer images keep the accounts on the state volume. 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 router the agent installs the haproxy package and the router service, but haproxy.service fails. The stand-in for systemd in the image does not put the values of $CONFIG, $PIDFILE and $EXTRAOPTS into 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>/master and do not add a router member.
  • 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 file usr/lib/tmpfiles.d/haproxy.conf on the state volume. 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:

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

A 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/.