Multi-Architecture Docker Support#

RAGFlow publishes Docker images as manifest lists covering linux/amd64 and linux/arm64, so docker pull on any supported architecture transparently selects the correct layer. Support spans three distinct layers: the release CI workflow (how images are built and pushed), the ragflow_deps base image (arch-aware binary artifacts), and the sandbox executor (runtime Docker CLI installation).

Release CI: Docker Buildx multi-arch publish#

The release workflow 1 originally built a single-arch image with docker build and pushed only the runner's native amd64 layer. PR #15848 replaced that step with a Docker Buildx flow:

1. Register QEMU binfmt emulators via tonistiigi/binfmt:qemu-v8.1.5 --install arm64,amd64.
2. Create (or reuse) a docker-container-driver buildx builder named ragflow-multiarch.
3. Run docker buildx build --platform linux/amd64,linux/arm64 --tag infiniflow/ragflow:${RELEASE_TAG} --tag infiniflow/ragflow:latest --push so both arches land in a single manifest list.
4. A post-build validation step calls docker buildx imagetools inspect on both tags and fails the workflow if either linux/amd64 or linux/arm64 is absent 2.

The workflow triggers on version tags (v*.*.*) and the mutable nightly tag (via schedule), so both stable releases and nightly builds are multi-arch 3.

Note: infiniflow/ragflow_deps:latest must itself be a multi-arch manifest for the arm64 layer to build. Rebuilding and re-pushing the deps image multi-arch is a prerequisite before the arm64 image layer can succeed 2.

ragflow_deps image: arch-aware artifacts#

The ragflow_deps image is built from a FROM scratch base that bundles both amd64 and arm64 artifacts side by side. download_deps.py downloads both variants ahead of build time:

4 5 6

Both variants are copied into the image root (ragflow_deps/Dockerfile), and the main Dockerfile selects the right one at build time using uname -m checks.

Main Dockerfile: architecture-conditional installation#

The main Dockerfile uses uname -m guards in multiple places to select arch-correct binaries at build time:

• uv installer — checks x86_64 vs aarch64 and extracts the matching tarball from the deps image 7.
• Stagehand server binary — maps x86_64 → x64 and aarch64|arm64 → arm64, copies the matching binary into the stagehand Go cache path 8.
• MS SQL ODBC driver — installs msodbcsql18 on arm64/aarch64 and msodbcsql17 on x86_64 9.
• libssl1.1 legacy DEB — installs the amd64.deb or arm64.deb variant as appropriate 10.

Sandbox executor: arch-aware Docker CLI install#

The agent/sandbox/executor_manager/Dockerfile runs a Python FastAPI service that invokes Docker CLI. PR #12434 fixed failures on ARM CPUs by replacing a hardcoded x86_64 static binary URL with an architecture-aware download:

• Declares ARG TARGETARCH and ARG TARGETVARIANT (BuildKit injected) 11.
• Uses a case statement mapping amd64 → x86_64, arm64 → aarch64, armv7/arm* → armhf, armv6 → armel, ppc64le, s390x 12.
• Downloads docker-29.1.0.tgz from download.docker.com/linux/static/stable/${DOCKER_ARCH}/ and symlinks /usr/bin/docker → /usr/local/bin/docker 13.

Key files#