Firebird Docker v2

[fdcastel]

TL;DR: Test images available here.

---

This is a complete rewrite of the Firebird Docker build system.

• Addresses multiple security issues, bugs, and feature requests
• while modernizing the CI/CD pipeline; and
• adding fork publishing support.

Closes:

• Fix Use native ARM-based Linux runners for GitHub Actions #28 (native ARM-based Linux runners)
• Fix tag debian bookworm based images with tag x-bookworm #34 (bookworm tags)
• Fix Docker image for Firebird 6 in pre-release #35 (snapshot images)

Key Changes

Security Fixes

• SQL injection prevention in entrypoint.sh: Passwords with single quotes no longer break or inject SQL (escape_sql_string)
• Template engine replacement: Replaced ExpandString (arbitrary PowerShell code execution) with safe {{VAR}} string replacement
• No more .bashrc overwrite: Environment file written to /opt/firebird/.firebird_env instead of clobbering user's .bashrc

Bug Fixes

• Fixed chmod 644 → chmod 755 on data directory (was preventing file creation)
• Fixed libtommath symlink for multi-arch (was hardcoded to x86_64-linux-gnu)
• Fixed unquoted array expansion in process_sql
• Fixed init_db glob that would fail when no init scripts present
• Fixed Wait-Port/Test-Port using hardcoded values instead of parameters
• Removed redundant Start-Sleep before port polling

New Features

• Native ARM64 builds on ubuntu-24.04-arm runners (no QEMU)
• Deterministic tag algorithm with -{distro} suffix tags (e.g., 5-bookworm, 5.0.3-bookworm)
• Snapshot images from FirebirdSQL/snapshots pre-release builds, including Firebird 6 snapshots
• Single Dockerfile template replaces 4 per-distro templates
• Tini as PID 1 for proper signal handling and zombie reaping
• STOPSIGNAL SIGTERM for clean Firebird shutdown
• Fork-friendly CI: Forks build only latest version + default distro on amd64
• workflow_dispatch inputs for version and distro filtering
• Fork publishing to GHCR: Forks can publish images to ghcr.io in addition to Docker Hub
• Test-Published task: Validates images after publishing to public registries

Architecture

• assets.json restructured with config section (distro settings, blocked variants)
• Shared functions extracted to src/functions.ps1
• PSFirebird v1.0.0+ used for release discovery (Find-FirebirdRelease, Find-FirebirdSnapshotRelease)
• CI matrix: amd64 (ubuntu-latest) + arm64 (ubuntu-24.04-arm) with manifest creation
• Publish workflow split into per-arch build + manifest creation jobs

CI Workflows

Workflow	Trigger	Runners	Notes
ci.yaml	Push/PR (all branches)	amd64 + arm64 (official repo); amd64 only (forks)	Standard build & test
publish.yaml	Push to master / weekly	amd64 + arm64, then manifest creation	Official Docker Hub publication
publish-fork.yaml	Manual dispatch (forks)	amd64 + arm64, then manifest creation	Fork publication to Docker Hub & GHCR
snapshot.yaml	Daily / manual dispatch	amd64 + arm64	Pre-release images from FirebirdSQL/snapshots

Test Results

• Integration tests pass (core image functionality)
• Tag unit tests pass (Pester)
• Test-Published task validates published images from Docker Hub and GHCR
• New tests: SQL injection resistance, graceful SIGTERM shutdown, tini PID 1, _FILE variants, mutual exclusion, tag correctness

[fdcastel]

Pushed a new version. But now the CI times went from ...

to...

What if, when working on forks, after each push, we build and test only the latest release for each major Firebird version? For example, just four images:

• the latest 3.x,
• latest 4.x,
• latest 5.x, and
• the most recent snapshot.

For the official repository, keep the current behavior unchanged (i.e., always perform a full build).

[mrotteveel]

I did a test run with Jaybird (master) against ghcr.io/fdcastel/firebird:6-snapshot, and it seems to be working. I did have some test failures, but those were caused by tests assuming a default port (I mapped to another port) that I need to fix or exclude.

[mrotteveel]

I've also run against ghcr.io/fdcastel/firebird:latest, and that also works fine. I have a failing test with ghcr.io/fdcastel/firebird:5-snapshot, but based on the failure, I think that is a problem in the snapshot itself.

[fdcastel]

What if, when working on forks, after each push, we build and test only the latest release for each major Firebird version?

Working on it.

[fdcastel]

All done! Changed:

1. firebird-docker.build.ps1: Added [switch]$LatestPerMajor parameter. In FilteredAssets, when set, it groups versions by major and keeps only the first (latest) entry per group:

   $result = $result | Group-Object { ([version]$_.version).Major } | ForEach-Object { $_.Group[0] }

   This reduces 17 versions to 3 (5.0.3, 4.0.6, 3.0.13).

2. ci.yaml: Added a lightweight determine-scope job (pure bash, no modules needed) that sets latest-per-major=true when the repo is a fork and the trigger is not workflow_dispatch. That output is then passed to both Build and Test steps as $params['LatestPerMajor'] = $true.

3. DECISIONS.md — D-008 updated to document the policy: forks build latest-per-major; official repo and manual dispatch always build everything.

4. AGENTS.md — CI/CD description updated to match.

[fdcastel]

Switched the multi-arch assembly to use docker buildx with push-by-digest=true

What changed:

• Each arch runner pushes its image by digest (no tag created in the registry)
• Digests are passed between GitHub Actions jobs as artifacts
• docker buildx imagetools create assembles the multi-arch manifest from raw SHA256 digests

Result: zero staging tags or staging repos in the registry. The only tags in firebirdsql/firebird are the final user-facing ones (latest, 5, 5.0.3-bookworm, etc.).

What changed

Replaced the tag-suffix staging approach (firebird:tag-amd64, firebird:tag-arm64) with Docker's recommended digest-based assembly. No staging tags or staging repos are created in the registry.

Before (tag-suffix staging)

amd64 runner                          arm64 runner
  Build                                 Build
  Test                                  Test
  Publish-Arch                          Publish-Arch
  → push firebird:5.0.3-bookworm-amd64   → push firebird:5.0.3-bookworm-arm64
                  ↘                       ↙
               Publish-Manifests
               → manifest create from staging tags

Problem: staging tags (firebird:tag-amd64, firebird:tag-arm64) pollute the official firebirdsql/firebird Docker Hub package with implementation artifacts visible to users.

After (digest-based, zero visible staging)

amd64 runner                          arm64 runner
  Build (buildx --load)                 Build (buildx --load)
  Test                                  Test
  Push-Digests                          Push-Digests
  → push by digest (no tag created)     → push by digest (no tag created)
  → save sha256 to artifact             → save sha256 to artifact
                  ↘                       ↙
               Download digest artifacts
               Publish-Manifests
               → imagetools create from sha256 digests
               → final tags published (only user-facing tags exist)

Result: only user-facing tags (5.0.3-bookworm, 5, latest, etc.) exist in the Docker Hub package. No staging artifacts.

Technical details

Push-Digests

• Uses docker buildx build --push with push-by-digest=true,name-canonical=true,push=true
• Pushes each image once per version+distro (not once per tag — all tags map to the same image)
• Captures digest from --metadata-file JSON output (containerimage.digest)
• Saves digest mapping to generated/digests-{arch}.json
• File is uploaded as a GitHub Actions artifact

Publish-Manifests

• Downloads digests-amd64.json and digests-arm64.json from artifacts
• For each tag: docker buildx imagetools create --tag firebird:tag firebird@sha256:amd64 firebird@sha256:arm64
• For amd64-only versions (FB3/FB4): creates single-arch manifest from amd64 digest only

Build

• Changed from docker build to docker buildx build --load
• With the default docker driver (CI), this is equivalent to docker build — no behavioral change
• With docker-container driver (publish workflows via setup-buildx-action), it builds in the container builder and exports to local daemon for testing

What's unchanged

• Publish-Direct (for single-arch fork publishing) — still pushes with final tags directly
• Build-Snapshot — still pushes snapshot tags directly
• Test tasks — unchanged, still test against local images
• CI workflow (ci.yaml) — doesn't publish, so unaffected

[fdcastel]

Just pushed some changes to ensure that the generated/ Dockerfiles and README.md are always committed to the repository after a successful publish, so that all Dockerfile links in the README are valid on GitHub.

Changes:

The update-repo job (added to both publish.yaml and publish-fork.yaml):

• Runs after build-and-push succeeds (and after create-manifests if present)
• Executes Invoke-Build Prepare — regenerates all Dockerfiles (no version filter), so every table row in README has a real file behind it
• Executes Invoke-Build Update-Readme — rewrites README.md with the correct registry prefix for the repo being published
• Commits generated/ + README.md back with [skip ci] to avoid an infinite CI loop
• Uses contents: write permission (already available on GITHUB_TOKEN)

Upstream compatibility:

• {{IMAGE_FULL_NAME}} falls back to firebirdsql/firebird when Update-Readme is called without -Registry (the default $imagePrefix is firebirdsql), so the upstream README continues to show the correct image name.
• The update-repo job in publish.yaml is guarded by if: ${{ github.repository == 'FirebirdSQL/firebird-docker' }} matching the existing pattern in that workflow.

The GitHub page at https://github.com/fdcastel/firebird-docker-fork/tree/feature/v2 now properly points each Dockerfile to its correct source file. This should (hopefully 😅) work too for the official repository once this PR is merged.

[fdcastel]

@asfernandes @mrotteveel I’m planning to merge this unless there are any remaining objections.

It will also align with the recently released versions.

[level420]

@fdcastel tested OK

ghcr.io/fdcastel/firebird:3-bullseye
ghcr.io/fdcastel/firebird:4-bullseye
ghcr.io/fdcastel/firebird:5-bullseye

without problems.

It would be great to also have

ghcr.io/fdcastel/firebird:3-trixie
ghcr.io/fdcastel/firebird:4-trixie
ghcr.io/fdcastel/firebird:5-trixie

Thank you for your work!

[fdcastel]

@level420 New images/tags available! Enjoy 😉

If everything is good, I intend to release them tomorrow.

[mrotteveel]

The new images (at least for 5.0) are using an outdated snapshot. For example, 5-latest contains LI-V5.0.4.1803, while the released version is 5.0.4.1812.

Never mind, PEBKAC issue, I still had it pointed to 5-snapshot and not to latest or 5.