Build multiarch (x86_64 + aarch64) hived image for mainnet & mirrornet

Add multi-arch production image support. The amd64 image is compiled natively;
the aarch64 image is CROSS-compiled (never emulated) using the buildroot toolchain
and preinstalled aarch64 RocksDB baked into ci-base-image (hive/common-ci-configuration!377).

Dockerfile:
- build stage pinned to --platform=$BUILDPLATFORM so the heavy C++ compile always runs
  natively; for $TARGETARCH=arm64 it cross-compiles via $CROSS_ROOT/Toolchain.cmake with the
  preinstalled aarch64 vendor RocksDB. Cross-build specifics: unset the x64 OPENSSL_* env so
  find_package(OpenSSL) hits the sysroot; provide a static qemu-aarch64 (CMAKE emulator) so
  the assertion-id generators run; export the cross CC/CXX/AR/LD so fc's autotools secp256k1
  cross-compiles; force-static readline/ncurses so hived needs only glibc at runtime.
- instance stage parameterised by INSTANCE_BASE_IMAGE and built --platform=$TARGETPLATFORM.
  Default keeps the pre-published minimal-runtime image (x64 fast path); multiarch builds set
  INSTANCE_BASE_IMAGE=minimal-runtime to build the runtime inline per-arch from ubuntu:24.04.
- TEMPORARY: CI_BASE_IMAGE pinned to the cci!377 image; repoint after that MR merges.

build_instance.sh: HIVE_BUILD_PLATFORMS triggers a multi-arch manifest build (--platform,
--push, inline runtime base); single-arch --load path unchanged.

.gitlab-ci.yaml: gated prepare_hived_image_multiarch (mainnet) and mirrornet_node_build_multiarch
jobs, restricted via rules to develop / master / protected tags / manual BUILD_MULTIARCH=true,
so feature/MR pipelines stay x86_64-only. The single-arch jobs keep running every pipeline.

Depends on hive/common-ci-configuration!377.

Validated locally against the cci!377 image: aarch64 build stage builds 620/620 using the
preinstalled RocksDB, and the assembled aarch64 mainnet image runs hived/cli_wallet (glibc-only
runtime deps).

Author: Bartek Wrona

.gitlab-ci.yaml

@@ -247,6 +247,69 @@ mirrornet_node_build:
         docker push ${IMAGE_NAME_PREFIX}${CI_COMMIT_TAG}
       fi
 
+# --- Multiarch (x86_64 + aarch64) production images ---------------------------------------
+# Build a multi-arch manifest: amd64 compiled natively + arm64 CROSS-compiled (never emulated)
+# using the toolchain + preinstalled aarch64 RocksDB baked into ci-base-image. The arm64 runtime
+# layer is built inline from the multiarch ubuntu:24.04 base (emulated apt only). A manifest
+# cannot be loaded into the local daemon, so it is pushed.
+#
+# Gated to develop, master, protected tags, or a manual BUILD_MULTIARCH=true trigger, so feature/MR
+# pipelines stay x86_64-only and fast. The single-arch prepare_hived_image / mirrornet_node_build
+# jobs above keep running every pipeline (they also export x86_64 binaries for the replay/test jobs).
+.prepare_hived_image_multiarch:
+  extends: .docker_image_builder_job
+  stage: build
+  needs:
+    - job: detect_changes
+      optional: true
+  variables:
+    # IMAGE_PATH: "" for mainnet, "/mirrornet" for mirrornet (set per job)
+    IMAGE_PATH: ""
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "develop"'
+    - if: '$CI_COMMIT_BRANCH == "master"'
+    - if: '$CI_COMMIT_TAG && $CI_COMMIT_REF_PROTECTED == "true"'
+    - if: '$BUILD_MULTIARCH == "true"'
+      when: manual
+    - when: never
+  tags:
+    - bigjob
+  script:
+    - |
+      set -euo pipefail
+      echo "$HIVED_CI_IMGBUILDER_PASSWORD" | docker login -u "$HIVED_CI_IMGBUILDER_USER" registry.gitlab.syncad.com --password-stdin
+      # Register qemu/binfmt for the (cheap, emulated) arm64 runtime stage. The cross-compiled
+      # build stage runs natively on the amd64 builder and is NOT emulated.
+      docker run --rm --privileged tonistiigi/binfmt --install arm64,amd64 || true
+      # A docker-container buildx builder (required to produce & push a manifest list) is already
+      # created and selected by the .docker_image_builder_job before_script as "docker-container-builder",
+      # wired to the dind endpoint + registry BUILDKIT_CONFIG_ARG. Reuse it rather than creating a second
+      # builder here (a bare "docker buildx create --driver docker-container" lacks that endpoint/config
+      # and fails). build_instance.sh's buildx build runs on this active builder.
+      # Build + push the multi-arch manifest (tagged with the commit short SHA).
+      "$CI_PROJECT_DIR/scripts/ci-helpers/build_instance.sh" \
+        "$CI_COMMIT_SHORT_SHA" "$CI_PROJECT_DIR" registry.gitlab.syncad.com/hive/hive \
+        --network-type="$HIVE_NETWORK_TYPE" \
+        --platforms="linux/amd64,linux/arm64"
+      # Apply published tags onto the pushed multi-arch manifest (no pull needed).
+      SRC="registry.gitlab.syncad.com/hive/hive${IMAGE_PATH}:${CI_COMMIT_SHORT_SHA}"
+      apply_tag() { docker buildx imagetools create -t "registry.gitlab.syncad.com/hive/hive${IMAGE_PATH}:$1" "$SRC"; }
+      [[ "$CI_COMMIT_BRANCH" == "develop" ]] && apply_tag latest || true
+      [[ "$CI_COMMIT_BRANCH" == "master" ]] && apply_tag stable || true
+      if [[ -n "${CI_COMMIT_TAG:-}" && "$CI_COMMIT_REF_PROTECTED" == "true" ]]; then apply_tag "$CI_COMMIT_TAG"; fi
+
+prepare_hived_image_multiarch:
+  extends: .prepare_hived_image_multiarch
+  variables:
+    HIVE_NETWORK_TYPE: mainnet
+    IMAGE_PATH: ""
+
+mirrornet_node_build_multiarch:
+  extends: .prepare_hived_image_multiarch
+  variables:
+    HIVE_NETWORK_TYPE: mirrornet
+    IMAGE_PATH: "/mirrornet"
+
 extended_block_log_creation:
   extends: .extended_block_log_creation
   stage: build

CMakeLists.txt

@@ -30,11 +30,17 @@ set( INSTALLER_APP_ID "68ad7005-8eee-49c9-95ce-9eed97e5b347" )
 set(CMAKE_EXPORT_COMPILE_COMMANDS "ON")
 set(CMAKE_VERBOSE_MAKEFILE "ON")
 
-# Compiler caching support (sccache preferred, ccache fallback)
+# Compiler caching support (sccache preferred, ccache fallback).
+# Disabled when cross-compiling: wrapping the buildroot aarch64 cross-gcc with sccache mishandles
+# the -MF dependency-file output (the in-tree equihash/blake2b C compile fails with
+# "opening dependency file ...o.d: No such file or directory"). The gated cross build runs
+# infrequently, so losing the cache there is acceptable. Native (x86_64) builds are unaffected.
 find_program(SCCACHE_PROGRAM sccache)
 find_program(CCACHE_PROGRAM ccache)
 
-if(SCCACHE_PROGRAM)
+if(CMAKE_CROSSCOMPILING)
+  message(STATUS "Cross-compiling: compiler caching (sccache/ccache) disabled")
+elseif(SCCACHE_PROGRAM)
   message(STATUS "Found sccache: ${SCCACHE_PROGRAM}")
   set(CMAKE_C_COMPILER_LAUNCHER "${SCCACHE_PROGRAM}")
   set(CMAKE_CXX_COMPILER_LAUNCHER "${SCCACHE_PROGRAM}")

Dockerfile

@@ -6,10 +6,16 @@ ARG CI_REGISTRY_IMAGE=registry.gitlab.syncad.com/hive/hive/
 ARG CI_IMAGE_TAG=ubuntu24.04-py3.14-1
 ARG BUILD_IMAGE_TAG
 ARG IMAGE_TAG_PREFIX
-# CI base image for build stage - must be at top level for FROM to see it
-# Using commit hash instead of tag to pin to a specific docker image for build repeatability.
-# Tags can be moved/overwritten, but commit hashes are immutable. May switch to tags in future.
-ARG CI_BASE_IMAGE=registry.gitlab.syncad.com/hive/common-ci-configuration/ci-base-image:fddc56669a22b53e6d75a6d697ee8a0f42a7ce52
+# CI base image for build stage - must be at top level for FROM to see it.
+# Pinned to the published ci-base-image version tag that ships the aarch64 cross toolchain +
+# preinstalled aarch64 RocksDB (hive/common-ci-configuration!377).
+ARG CI_BASE_IMAGE=registry.gitlab.syncad.com/hive/common-ci-configuration/ci-base-image:pypa_2_28-pg18-arm-1
+
+# Runtime base for the final `instance` image. Default: the pre-published, commit-tagged
+# minimal-runtime image (x86_64 fast path). Multiarch builds pass
+# INSTANCE_BASE_IMAGE=minimal-runtime to build the runtime inline per-arch from the
+# multiarch ubuntu:24.04 base, so no separately-published multiarch minimal-runtime is needed.
+ARG INSTANCE_BASE_IMAGE=${CI_REGISTRY_IMAGE}minimal-runtime:${CI_IMAGE_TAG}
 
 FROM phusion/baseimage:noble-1.0.1 AS runtime
 
@@ -51,8 +57,15 @@ USER hived
 WORKDIR /home/hived
 
 # Build stage uses centralized ci-base-image from common-ci-configuration
-# This image includes: build toolchain, sccache, Pythons 3.8 - 3.14, glibc 2.28, Docker CLI, hived user
-FROM ${CI_BASE_IMAGE} AS build
+# This image includes: build toolchain, sccache, Pythons 3.8 - 3.14, glibc 2.28, Docker CLI, hived user.
+# Pinned to the native build platform ($BUILDPLATFORM) so the heavy C++ compile is NEVER emulated;
+# aarch64 targets are cross-compiled (not emulated) using the toolchain baked into ci-base-image.
+FROM --platform=${BUILDPLATFORM} ${CI_BASE_IMAGE} AS build
+
+# Target architecture (set automatically by BuildKit: amd64 | arm64). amd64 builds
+# natively; arm64 cross-compiles via $CROSS_ROOT/Toolchain.cmake (+ preinstalled aarch64 vendor libs).
+ARG TARGETARCH
+ENV TARGETARCH=${TARGETARCH}
 
 ARG BUILD_HIVE_TESTNET=OFF
 ENV BUILD_HIVE_TESTNET=${BUILD_HIVE_TESTNET}
@@ -89,10 +102,20 @@ RUN <<-EOF
   sudo mkdir -p "${INSTALLATION_DIR}"
   sudo chown hived:users "${INSTALLATION_DIR}"
 
+  # For aarch64 targets, cross-compile using the toolchain + preinstalled aarch64 vendor libs
+  # (RocksDB) baked into ci-base-image. The whole cross environment is set up by build.sh's
+  # --cross-root (it picks up the preinstalled RocksDB from $HIVE_AARCH64_VENDOR_DIR). amd64 builds
+  # natively (no extra args).
+  CROSS_ARGS=()
+  if [ "${TARGETARCH}" = "arm64" ]; then
+    CROSS_ARGS+=( --cross-root="${CROSS_ROOT}" )
+  fi
+
   ./source/${HIVE_SUBDIR}/scripts/build.sh --source-dir="./source/${HIVE_SUBDIR}" --binary-dir="./build" \
   --cmake-arg="-DBUILD_HIVE_TESTNET=${BUILD_HIVE_TESTNET}" \
   --cmake-arg="-DHIVE_CONVERTER_BUILD=${HIVE_CONVERTER_BUILD}" \
   --cmake-arg="-DHIVE_LINT=${HIVE_LINT}" \
+  "${CROSS_ARGS[@]}" \
   --flat-binary-directory="${INSTALLATION_DIR}" \
   --clean-after-build
 
@@ -105,7 +128,7 @@ RUN <<-EOF
   sudo chown -R hived:users "${INSTALLATION_DIR}/"*
 EOF
 
-FROM ${CI_REGISTRY_IMAGE}minimal-runtime:$CI_IMAGE_TAG AS instance
+FROM --platform=${TARGETPLATFORM} ${INSTANCE_BASE_IMAGE} AS instance
 
 ARG BUILD_TIME
 ARG GIT_COMMIT_SHA