Bu kılavuz, HQbird 2027’yi Docker’da çalıştıran yönetici içindir. Bir konteyner, tüm HQbird bileşenleriyle bir Firebird örneğidir:

  • Firebird (bir hattın HQbird derlemesi: 5.0, 4.0, 3.0 veya 2.5);
  • HQbird ajanı (fbagent): yedekler, izleme, bakım işleri, güncellemeler, HQCenter bağlantısı;
  • HQ Monitor: örneğin web konsolu;
  • küme düğümü (hqclusternode) ve RCM (hqbirdrcm): HQCenter bu örneği bir kümeye eklediğinde veya konteynere bir küme rolü verdiğinizde (bölüm 7) ajan bunları kurar. Rol yoksa ve HQCenter yoksa konteyner hiçbir küme bileşenini çalıştırmaz.

Konteyner, HQbird’i bir sunucuyla aynı çevrimdışı yükleyiciyle kurar (Linux kurulum kılavuzu). Ajan ardından Firebird’ü, HQ Monitor’ü, küme bileşenlerini ve kendisini HQCenter’dan günceller, sunucudaki gibi. Verileriniz, yapılandırma, lisans, HQCenter sertifikaları ve güncellenen programlar volume’lardadır: konteyneri yeniden oluşturduğunuzda veya imajı değiştirdiğinizde yerinde kalırlar.

Güncel sürüm: 2027.2.33 (2026-11-16): Firebird 2.5.9, 3.0.15, 4.0.8 ve 5.0.5, ajan 3.4.0, HQ Monitor 1.57.0, RCM ve düğüm 2027.5.12.

2026-11-16’da Ubuntu 22.04.5 (2 vCPU / 4 GB), Docker 29.10.0, Compose 5.7.1 üzerinde test edildi, imaj hqbird2027-fb40:2027.2.33 (ilk test: 2026-11-11, imaj 2027.2.27). Ubuntu 22.04 için adım adım kurulum: hqbird2027-docker-install-fb40.ru.md (Rusça), hqbird2027-docker-install-fb40.pt.md (Portekizce).

Küme rolü (bölüm 7.1) ve geçiş (bölüm 7.3), 2026-11-16’da 5.0, 4.0, 3.0 ve 2.5 imajlarında test edildi; iki “ana makine” bir sanal makinenin iki adresiydi ve ayrıca iki ayrı Docker ana makinesinde (iki droplet, 4.0 imajı 2027.2.33). 2026-11-17’de geri kalanı, 5.0 imajı 2027.2.33 ile iki Docker ana makinesinde test edildi: 2027.2.32 konteynerlerinde elle kurulan ve yeni imaja taşınan bir küme (iki konteyner de 35 saniyede healthy), HQBIRD_RCM_ALLOW, RCM konsolunun Services sayfaları ve otomatik yük devretme. 2027.2.33’e kadarki imajlarda router (HAProxy) başlamaz (bölüm 9); sonraki imajda düzeltme vardır.

1. İmajlar

İmaj Firebird Varsayılan 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

İmajlar, IBSurgeon kuruluşunun GitHub Container Registry kaydındadır (https://github.com/orgs/IBSurgeon/packages). Herkese açıktırlar: oturum açmanız gerekmez. <version>, HQbird kurulum sürümüdür, örneğin 2027.2.33. 2027.2 etiketi, en yeni 2027.2.x imajıdır.

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

İmajlar cosign ile imzalanır. Açık anahtar hqbird-cosign.pub henüz yayımlanmadı (2026-11-16). 2027.2.33 imajları imzalıdır. Anahtarınız olduğunda, imajı kullanmadan önce doğrulayın:

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

2. İlk başlatma

  1. compose.yaml dosyasını (sürümün ops/docker/ klasöründen) Docker ana makinesinde bir klasöre kopyalayın.

  2. SYSDBA parolasını, yalnızca sizin okuyabileceğiniz bir dosyaya koyun:

    Command
    mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password
  3. compose.yaml içinde image: ve hostname: değerlerini ayarlayın ve kullandığınız secrets: satırlarının başındaki # işaretini kaldırın.

  4. Konteyneri başlatın:

    Command
    docker compose up -d
  5. Kurulumu izleyin (ilk başlatmada birkaç dakika):

    Command
    docker compose logs -f

    2 vCPU üzerinde kurulum yaklaşık 20 saniye sürer. Günlük [hqbird-boot] ready: firebird.service=active ... gösterdiğinde ve docker compose ps healthy gösterdiğinde biter.

Sonra:

  • Firebird: <docker host>:3050.
  • HQ Monitor: http://<docker host>:23050/, oturum admin. Yükleyici parolayı üretir; şununla okuyun: docker compose exec hqbird cat /opt/hqbird/conf/access.properties.
  • HQCenter’daki ajan kimliği: ana makine adı + kurulum tarihi (YYMMDD) + -fbNN, örneğin hqbird-fb40-3051261111-fb40.

Ana makine adını koruyun. Örneğin lisans kimliği, state volume’undaki machine-id ve ajan kimliğidir. Yeni bir state volume’u yeni bir kurulumdur.

3. Ayarlar

Ayarlar yalnızca ilk başlatmada (kurulumda) okunur.

Ayar Ne yapar
HQBIRD_FB_PORT Konteynerin içindeki Firebird portu (varsayılan 3050). HQ Monitor, 20000 + bu portu kullanır
HQBIRD_HQM_PORT başka bir HQ Monitor portu
HQBIRD_AGENT_ID ajan kimliği (varsayılan: ana makine adından, tarihten ve porttan yapılır)
HQBIRD_HQM_LOGIN + gizli hqmonitor_password HQ Monitor oturum açma adı
HQBIRD_TRIAL_EMAIL, HQBIRD_TRIAL_ZONE bir deneme lisansı isteyin (gizlilik politikasını kabul edersiniz)
HQBIRD_DEBUG=1 Firebird hata ayıklama dosyalarını kurun
gizli sysdba_password yeni bir Firebird’ün SYSDBA parolası
gizli license bir lisans dosyası
gizli attach HQCenter’dan attach.json: ajanı HQCenter’ınıza bağlayın
HQBIRD_CLUSTER_ROLE master veya replica: HQCenter olmadan bir küme (bölüm 7). Boş: küme yok
HQBIRD_CLUSTER_ADDRESS master, zorunlu: Docker ana makinesinin adresi veya DNS adı, replica’nın ve tarayıcınızın ona ulaştığı biçimde. Virgülle bir liste; ilki RCM URL içine gider
HQBIRD_CLUSTER_ID master: küme kimliği (varsayılan: ana makine adı)
gizli rcm_password master: rcmadmin RCM oturumunun parolası (varsayılan: üretilmiş bir parola)
HQBIRD_RCM_ALLOW replica: konteyneri yalnızca bu RCM’ler davet edebilir (IP, CIDR, ana makine adı; varsayılan: herhangi biri). Master’ın Docker ana makinesinin adresini yazın: replica o adresi görür. Tek bir Docker ana makinesinde replica, kendi Docker ağının ağ geçidini görür
HQBIRD_PAIRING_PORT, HQBIRD_NODE_PORT küme yuvası: eşleştirme portu 7450-7459 ve düğüm portu = eşleştirme portu - 399 (varsayılan 7450 ve 7051)

4. Volume’lar

Volume Yol İçerik
opt /opt Firebird, ajan, HQ Monitor, küme düğümü, RCM
state /var/lib/hqbird-container unit’ler, sudoers, HQ Monitor verileri, ajan günlükleri, machine-id, kurulum durumu, çalışma sırasında oluşturulan işletim sistemi hesapları (RCM hizmet kullanıcısı)
trust /usr/libexec/hqbird-fbagent ajanın güncelleme başlatıcısı ve güven deposu
rootwork /var/lib/hqbird-fbagent güncelleme başlatıcısının çalışma klasörü
db /db veritabanları (veritabanlarınızı buraya koyun)
backup /backup yedekler

opt, state, trust ve rootwork üzerine ana makine klasörleri bağlamayın. db ve backup için ana makine klasörleri kullanabilirsiniz; bunları uid 84’e verin (imajın firebird kullanıcısı):

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

Altı volume’u birlikte yedekleyin.

5. Günlük iş

Görev Komut
Hizmetlerin durumu docker compose exec hqbird systemctl list-units --type=service
Firebird’ü yeniden başlat 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
Günlükler docker compose logs --since 1h
Durdur (Firebird veritabanlarını kapatır) docker compose stop

Konteynerin içinde systemctl, HQbird hizmetlerini yönetir. Bu systemd değildir: HQbird programlarının kullandığı komutları destekler (start, stop, restart, status, is-active, enable, disable, show, list-units, daemon-reload).

6. Güncellemeler

Güncellemenin iki yolu vardır. İkisi de verilerinizi korur.

  • HQCenter’dan (sunucudaki gibi): HQCenter, konteynerin içindeki ajanı, HQ Monitor’ü, Firebird’ü, küme düğümünü ve RCM’yi günceller.

  • Yeni imaj: image: değerini yeni sürüme çevirin, ardından:

    Command
    docker compose pull && docker compose up -d

    Başlangıçta konteyner, yeni imajın yükleyicisini güncelleme kipinde çalıştırır. HQCenter ajanı imajdakinden daha yeni bir sürüme güncellediyse yükleyici çalıştırılmaz (sürüm düşürülmez); günlük bunu yazar.

Yeni bir konteyner (yeni bir imaj veya -v olmadan docker compose down ve up -d) kümeyi korur: rol, küme kimliği, RCM, düğümler ve diğer ana makineye bağlantı volume’lardadır. Compose dosyasındaki küme ayarları yeniden okunmaz. 2027.2.32’ye kadar olan imajların burada iki kusuru vardır: bölüm 9’a bakın.

7. Küme

Küme kurmanın iki yolu vardır. Aynı konteynerde ikisini birden kullanmayın.

7.1. HQCenter olmadan: rollü iki konteyner

Bir konteyner master olur ve küme yöneticisini (RCM) konsoluyla çalıştırır. Diğeri bir replica olur. Rol, ilk başlatmanın bir ayarıdır: HQBIRD_CLUSTER_ROLE. O ayar yoksa konteyner RCM çalıştırmaz, küme düğümü çalıştırmaz ve eşleştirme portu açmaz. Rol, 2027.2.33 veya daha yeni bir imaj ister.

İki Docker ana makinesi. İki konteynere farklı ana makine adları verin (.env içinde HQBIRD_HOSTNAME veya hostname:): aynı ana makine adında iki ajanın kimliği aynı olur ve RCM replica’yı reddeder (duplicate). compose.master.yaml dosyasını master ana makineye, compose.replica.yaml dosyasını replica ana makineye, compose.yaml yanına kopyalayın (sürümün ops/docker/ klasörü).

  1. Master ana makinede, o Docker ana makinesinin adresini .env içine, replica ana makinesinin ve tarayıcınızın ona ulaştığı biçimde koyun (localhost değil, konteynerin adresi değil):

    Command
    echo 'HQBIRD_CLUSTER_ADDRESS=203.0.113.10' >> .env
    docker compose -f compose.yaml -f compose.master.yaml up -d
  2. Replica ana makinede:

    Command
    docker compose -f compose.yaml -f compose.replica.yaml up -d
  3. Her konteynerin küme satırlarını okuyun:

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

    Master, konsol adresini ve CA hash değerini gösterir: [hqbird-boot] cluster: role=master id=... console=https://203.0.113.10:7444 login=rcmadmin. Replica, eşleştirme portunu ve parmak izini gösterir: [hqbird-boot] cluster: role=replica pairing port 7450: open until ..., fingerprint sha256:....

  4. https://<master host>:7444 konsolunu açın. Oturum rcmadmin olur. rcm_password gizli değeri yoksa parola bir dosyadadır; RCM ilk oturumda yeni bir parola ister:

    Command
    docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password'
  5. Settings → Link hosts içine iki satır yazın: HQBIRD_CLUSTER_ADDRESS içinde verdiğiniz adres (master) ve replica’nın Docker ana makinesinin adresi. Port yazmazsınız: RCM, 7450-7459 eşleştirme portlarını okur. Eşleştirme portu, konteyner healthy olduktan yaklaşık 30 saniye sonra yanıt verir. Initialize penceresi /databases/replica/... klasörünü önerir; bu klasör volume’ların dışındadır: değiştirin. Bu pencere yaklaşık 1000 px yüksekliktedir ve kaydırılmaz: düğmelerini görmüyorsanız sayfayı uzaklaştırın. Tarayıcıda 2026-11-16’da test edildi. Replica’nın parmak izini günlüğündekiyle karşılaştırın. RCM URL alanını boş bırakın. Ardından Linux küme kılavuzu belgesinin 4. adımıyla devam edin (veritabanı klasörü, kayıt, replica’yı ilklendirme). Replica’nın veritabanı klasörü için db volume’unda bir klasör kullanın, örneğin /db/replica. Test edildi: master’a yazılan bir satır 30 saniye içinde replica’daydı.

-f seçeneklerini atlamak için COMPOSE_FILE=compose.yaml:compose.master.yaml (veya ...replica.yaml) değerini .env içine koyun.

Tek Docker ana makinesi. compose.cluster-one-host.yaml, her iki konteyneri içeren tam bir dosyadır:

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

Konteynerler proje ağında birbirine adla ulaşır, bu yüzden küme portları yayımlanmaz. Link hosts içine hqbird-master ve hqbird-replica yazın. Master’ın Firebird’ü 3050 portundadır, replica’nınki 3051 portundadır; konsol https://<docker host>:7444 adresindedir.

Kurallar:

  • Rol ve ayarları yalnızca ilk başlatmada okunur. Daha sonra farklı bir HQBIRD_CLUSTER_ROLE günlüğe bir uyarı yazar ve hiçbir şeyi değiştirmez. Kümeyi daha sonra değiştirmek için HQ Monitor (Clusters) sayfasını veya konteynerin içindeki fbagent --cluster-init ve fbagent --cluster-pairing komutlarını kullanın.
  • Yanlış bir ayar (bilinmeyen bir rol, HQBIRD_CLUSTER_ADDRESS olmayan bir master, diğer role ait bir ayar) herhangi bir şey kurulmadan başlatmayı durdurur. Günlük ne yazılacağını söyler ([hqbird-boot] error: ...); Docker konteyneri yeniden başlatır ve siz ayarı düzeltene kadar günlük satırı yineler.
  • Bir replica’nın eşleştirme penceresi 24 saat açıktır. Henüz hiçbir kümede olmayan bir konteynerin yeniden başlatılması pencereyi yeniden açar. Eşleştirme portunu diğer ağlara kapatmak için HQBIRD_RCM_ALLOW veya güvenlik duvarınızı kullanın; bağlantıdan sonra portu ports: listesinden çıkarabilirsiniz.
  • Bir geçiş (bir RCM hizmeti) için her ana makineye ikinci bir düğüm ve onun yayımlanmış portu gerekir: bölüm 7.3’e bakın.

7.2. HQCenter ile

HQCenter, örneği bir sunucuyu eklediği gibi bir kümeye ekler. HQBIRD_CLUSTER_ROLE ayarlamayın. HQCenter’da üye adresi olarak Docker ana makinesinin adresini verin. compose.yaml içinde küme bileşenlerinin portlarını yayımlayın:

Bileşen Port Ne zaman yayımlanır
küme düğümü düğümün listen_port değeri (örneğin 7051) örnek bir küme üyesidir
RCM 7443 HQCenter bu ajanı RCM yapar
RCM operatör konsolu 7444 yukarıdaki gibi; RCM ayarlarında operator_addr değerini 0.0.0.0:7444 yapın

Ajan, küme kaydedildikten birkaç dakika sonra düğümü (ve RCM’yi) kurar. O zamana kadar düğüm portu yanıt vermez. HQCenter’da düğümün listen_port değerini yayımlanan porta ayarlayın. Replica, RCM ajanı küme CA’sını yükleyene kadar bekler.

2026-11-16’da rolsüz test edildi: ajanlar düğümleri ve RCM’yi kurdu ve docker compose down ile up -d sonrasında tüm üyeler yeniden running oldu.

7.3. İki konteyner arasında geçiş

Bir RCM hizmeti, bir veritabanının master rolünü bir ana makineden diğerine taşır. Bir hizmet için her ana makineye iki düğüm gerekir: bir master düğümü ve bir replica düğümü. Link hosts her ana makineye bir düğüm verir, bu yüzden ikinci düğümleri siz eklersiniz. Bölüm 7.1’deki çift üzerinde 2026-11-16’da test edildi: geçiş 25 saniye sürdü, eski master salt okunur bir replica oldu ve yeni master’a yazılan bir satır 15 saniye sonra oradaydı.

Adımlar, konsol portundaki RCM operatör API’sini kullanır. curl, rcmadmin parolasını sorar; -k, kümenin kendi sertifikasının denetimini atlar:

Command
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }
  1. İkinci düğüm portunu yayımlayın, her iki ana makinede: düğüm portu + 10. compose.master.yaml ve compose.replica.yaml içinde "7061:7061" satırının başındaki # işaretini kaldırın, ardından aynı -f seçenekleriyle docker compose up -d çalıştırın. Yapabiliyorsanız bunu ilk başlatmadan önce yapın.

  2. Her düğüme kendi Docker ana makinesinin adresini verin. RCM bu adresi ve Firebird portunu uygulamalara verir; o adres olmadan konteynerin adresini alırlar:

    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, düğüm kimliklerini gösterir (<host name>-master, <host name>-replica).

  3. İkinci düğümleri ekleyin, küme belgesine: replica ana makinede bir master düğümü ve master ana makinede onun replica düğümü, ikisi de listen_port 7061 ile. Belgeyi okuyun, iki üye ve bir bağlantı ekleyin ve revizyonuyla geri gönderin:

    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

    Ajanlar ardından iki düğüm hizmetini kurar (iki ana makinedeki testte 30 saniye; birkaç dakika sürebilir). docker compose exec hqbird systemctl list-units --type=service ardından her konteynerde iki hqclusternode hizmeti gösterir.

    Ardından her iki replica düğümüne db volume’unda bir veritabanı klasörü verin. O klasör olmadan geri geçiş veya bir yük devretme, geri dönüşü olmayan noktadan sonra durur ve hizmet failed olur:

    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. Hizmeti tanımlayın. host, ana makinenin ajan kimliğidir. İkinci ana makinedeki yol, replica dosyasının yoludur: <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. Kontrol edin, sonra geçirin:

    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>

Geçişten sonra .../services/shop/master, diğer Docker ana makinesinin adresini ve onun Firebird portunu verir. Uygulamalar o adrese bağlanmalıdır. Bir geçiş, IN_SYNC olan bir replica ister: master üzerindeki ilk yazmadan sonra öyledir (testte 35 saniye).

Router’lar ve otomatik yük devretme. Bir router (HAProxy), uygulamalara master’ı izleyen tek bir adres verir. 2027.2.33’e kadarki imajlarda router başlamaz (bölüm 9); sonraki imajda düzeltme vardır. Otomatik yük devretme, tanık olarak bir router ister. 2026-11-17’de laboratuvarda test edildi, geçici bir çözümle 2027.2.33 üzerinde ve düzeltmeyi içeren bir deneme imajında:

  • Bir router, router rolüne sahip bir küme üyesidir. Ajan, haproxy paketini Debian deposundan kurar, her yeni konteynerde de: konteynerin depoya erişmesi gerekir. Router portunu yayımlayın (örnekte 3051).

  • Router yalnızca RCM ana makinesindeyken, diğer ana makinenin konteyneri durduktan 84 saniye sonra RCM master’ı kendiliğinden taşıdı; işlem 10 saniye sürdü. O ana makine geri geldiğinde rejoin onu yeniden replica yaptı.

  • Her ana makinede bir router varken otomatik yük devretme başlamaz: router’ların yarısından fazlası rapor vermelidir ve ikisinden biri kaybolan ana makinededir.

  • RCM, master konteynerinde çalışır. O ana makine kaybolduğunda RCM de kaybolur ve master’ı kendiliğinden taşıyan bir şey kalmaz.

8. Portlar, güvenlik duvarı, ikinci örnek

Her portu konteynerin dışında ve içinde aynı numarayla yayımlayın (3051:3051, 3051:3050 değil). Ajan ve küme, konteynerin içinde gördükleri portu bildirir.

Port Ne Gerektiği durum
HQBIRD_FB_PORT (3050) Firebird her zaman
20000 + Firebird portu (23050) HQ Monitor her zaman
düğüm listen_port (7051) küme düğümü küme üyesi
düğüm portu + 10 (7061) ana makinenin ikinci düğümü geçişli bir hizmet (bölüm 7.3)
7443, 7444 RCM, RCM operatör konsolu bu ajan RCM’dir (ana makine başına bir)
eşleştirme portu (7450) ajanın eşleştirme portu rollü bir replica, bağlanana kadar

Ajan, HQCenter’a kendisi bağlanır (giden); gelen bir porta ihtiyacı yoktur.

Docker, portları ufw’nin ötesinde yayımlar. Test edildi: ufw yalnızca 22 portuna izin verirken Firebird ve HQ Monitor portları İnternet’ten açıktı. Dış bir güvenlik duvarı kullanın, tek bir ana makine adresinde yayımlayın ("10.0.0.5:23050:23050") veya DOCKER-USER iptables zincirine kurallar ekleyin.

Bir ana makinedeki ikinci örnek kendi klasörünü, proje name: değerini, hostname değerini, HQBIRD_FB_PORT değerini ve portları ister. Proje adı volume adlarını oluşturur (<name>_opt, …): aynı adla ikinci başlatma, birincinin volume’larını ve konteynerini alır.

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

Tek bir dış IP üzerinde N örnek için kurallar:

  • Firebird 3050 + N, HQ Monitor 20000 + Firebird portu, küme düğümü 7051 + N (HQCenter’da aynı listen_port değerini ayarlayın). Ana makine Docker dışında bir Firebird veya HQbird çalıştırıyorsa 3050, 23050 ve 7051’i atlayın.
  • Ana makine başına yalnızca bir örnek RCM olabilir (7443, 7444).
  • Bir küme rolüyle (bölüm 7.1) bir ana makinenin her örneği kendi yuvasını ister: ikincisi için HQBIRD_PAIRING_PORT=7451 ve HQBIRD_NODE_PORT=7052, üçüncüsü için 7452 ve 7053.
  • Bir örnek, yüksüzken yaklaşık 200-250 MB bellek kullanır. Test edildi: 2 vCPU / 4 GB üzerinde üç FB 4.0 örneği, biri yüklü.
  • Aynı ana makinedeki diğer Firebird hatları aynı kuralları kendi imajlarıyla (hqbird2027-fb50, …) ve adlarıyla (hqbird-fb50-3054) izler.

Bir örnek ekleyin (burada üçüncüsü: 3053, 23053, 7054), birincinin compose.yaml dosyasından. 3051 değiştirilince name:, hostname:, HQBIRD_FB_PORT ve HQ Monitor portu da değişir:

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. Bilinen sorunlar

  • Ajanı elle fbagent --enroll ile HQCenter’a bağladıktan sonra fbagent --refresh-apply-launcher komutunu root olarak çalıştırın, yoksa ajanın kendi kendini güncellemesi “no goafts CA is pinned” ile başarısız olur.
  • Betiklerde docker compose exec komutunu -T ve </dev/null ile çalıştırın. Onlar olmadan standart girdiyi okur ve ssh ... bash -s ile gönderdiğiniz bir betiğin kalanını alır.
  • Ajan HQCenter’a bağlanmadan önce günlüğü goafts mTLS settings are incomplete ve bootstrap CA not found uyarılarını gösterir. Bu normaldir.
  • Konteyner, her kurulumdan sonra /opt/hqbird dizinini root’a verir (ajanın kendi kendini güncellemesi bunu ister). Ajan, /opt/hqbird/version.json dosyasını güncelleyemediğine dair bir uyarı yazar; yok sayabilirsiniz.
  • 2027.2.32’ye kadarki imajlar: yazmaya açık klasörler. Bu imajlarda /etc, /usr ve /usr/lib kipi 0777’dir ve konteynerin bazı dosyalarını tüm hesaplar yazabilir. Konteynerdeki herhangi bir hesap, root’un başlattığını değiştirebilir. Ajan böyle bir klasörü de reddeder (root trust directory: /usr is writable by group or others): güncelleme kipindeki yükleyici yeni bir konteynerde başarısız olur ve konteyner yeniden yeniden başlar. 2027.2.33 veya daha yeni bir imaj kullanın. Eski bir imajın konteynerinde güvenmediğiniz kullanıcılara kabuk erişimi vermeyin.
  • 2027.2.32’ye kadarki imajlar: elle kurulan RCM yeni bir konteynerde başlamaz. Konteynerin içinde fbagent --cluster-init ile RCM kurduğunuzda ajan, hqbirdrcm işletim sistemi hesabını oluşturur. Yeni bir konteynerde bu hesap yoktur (User=hqbirdrcm: invalid userid, konteyner unhealthy olur). Daha yeni imajlar hesapları state volume’unda tutar. HQCenter’ın kurduğu bir küme bundan etkilenmez.
  • 2027.2.33’e kadarki imajlar: bir router (HAProxy) başlamaz. router rolüne sahip bir küme üyesi için ajan haproxy paketini ve router hizmetini kurar, ama haproxy.service başarısız olur. İmajdaki systemd vekili $CONFIG, $PIDFILE ve $EXTRAOPTS değerlerini komut satırına koymaz, drop-in dosyasını okumaz ve /run/haproxy klasörünü oluşturan bir şey yoktur. Sonraki imajda düzeltme vardır. O zamana kadar uygulamalara .../services/<alias>/master adresini verin ve bir router üyesi eklemeyin.
  • İmaj 2027.2.33: bir router eklendikten sonra yeni bir konteyner başlamaz. Günlükte chown: invalid user: 'haproxy' vardır ve Docker konteyneri yeniden yeniden başlatır. Başlatmak için state volume’undaki usr/lib/tmpfiles.d/haproxy.conf dosyasını kaldırın. Sonraki imajda düzeltme vardır.

10. İmajları derleme

Sürüm ekibi içindir. Sürüm dosyaları dist\releases içinde olan bir Windows ana makinesinde, write:packages izni olan bir belirteçle GHCR’de oturum açın, ardından derleyin, gönderin ve imzalayın:

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

Yeni bir paket (bir hattın ilk gönderimi) özeldir. IBSurgeon kuruluşunun paket ayarlarında görünürlüğünü herkese açık yapın.

-ContextOnly yalnızca derleme klasörünü hazırlar (dist\hqbird2027-docker\fbNN-<version>) ve bir Linux Docker ana makinesinde çalıştırılacak docker build komutunu yazar.

İmajın /etc veya /usr altındaki bir klasörü ya da dosyası tüm hesaplar tarafından yazılabiliyorsa derleme durur (derleme klasörü Windows’tan gelir, kipler orada kaybolur). Konteyner betiklerinin, küme ayarlarının ve compose dosyalarının testleri: go test ./ops/docker/.