This document describes the Docker image build system, multi-architecture support, and deployment configurations for fuel-core. It covers the Dockerfile structure, CI/CD workflows that build and publish images, build optimization strategies, and available image variants. For information about running and operating fuel-core nodes, see Getting Started. For ephemeral test environment provisioning, see Ephemeral Test Environments.
The fuel-core project maintains three primary Docker image variants, all published to multiple container registries with support for both AMD64 and ARM64 architectures:
| Image Variant | Purpose | Dockerfile | Registry Tags |
|---|---|---|---|
| fuel-core | Production node | deployment/Dockerfile | latest, vX.Y.Z, sha-<commit> |
| fuel-core-debug | Profiling-enabled build | deployment/Dockerfile | latest, vX.Y.Z, with -debug suffix |
| fuel-core-e2e-client | Integration test client | deployment/e2e-client.Dockerfile | latest, vX.Y.Z, with -e2e-client suffix |
All images are published to:
ghcr.io/fuellabs/fuel-corepublic.ecr.aws/fuellabs/fuel-coreSources: .github/workflows/docker-images.yml175-185 deployment/Dockerfile1-99 deployment/e2e-client.Dockerfile1-56
The production Dockerfile uses a four-stage build process optimized for layer caching and minimal runtime image size:
Sources: deployment/Dockerfile1-99
The Dockerfile accepts the following build-time arguments:
| Argument | Default | Purpose |
|---|---|---|
BUILDPLATFORM | - | Host platform (set by Docker) |
TARGETPLATFORM | - | Target platform for cross-compilation |
FEATURES | "production" | Cargo feature flags deployment/Dockerfile30 |
DEBUG_SYMBOLS | false | Enable debug symbols for profiling deployment/Dockerfile31 |
Runtime environment variables (configurable via docker run -e):
| Variable | Default | Purpose |
|---|---|---|
IP | 0.0.0.0 | GraphQL API bind address deployment/Dockerfile75 |
PORT | 4000 | GraphQL API port deployment/Dockerfile76 |
DB_PATH | ./mnt/db/ | Database storage path deployment/Dockerfile77 |
Sources: deployment/Dockerfile30-34 deployment/Dockerfile70-77
The build process uses cargo-chef for dependency layer caching, combined with Docker BuildKit's cache mounts to avoid re-downloading and re-compiling dependencies:
Cache mounts are configured at lines deployment/Dockerfile40-43 and deployment/Dockerfile58-61
Sources: deployment/Dockerfile39-65
For ARM64 builds on AMD64 hosts (and vice versa), the Dockerfile uses the tonistiigi/xx toolchain wrapper:
The xx-cargo command automatically:
--target tripleSources: deployment/Dockerfile2-20 deployment/Dockerfile62-65
The Docker image build process runs in parallel on native runners for each architecture, avoiding slow QEMU emulation:
Sources: .github/workflows/docker-images.yml27-122 .github/workflows/docker-images.yml123-194
The workflow uses reproducible-containers/buildkit-cache-dance to persist Rust build artifacts between runs:
This action extracts cache from the Docker layer and stores it in GitHub Actions cache, then injects it back for subsequent builds. Cache extraction is skipped on cache hits for efficiency.
Sources: .github/workflows/docker-images.yml83-94 .github/workflows/docker-images.yml267-278
Build Command:
Features included: The production feature flag enables optimizations and production-ready configurations defined in crates/fuel-core/Cargo.toml
Entrypoint: ./fuel-core run --ip ${IP} --port ${PORT} --db-path ${DB_PATH} deployment/Dockerfile98
Sources: .github/workflows/docker-images.yml96-107
Built with debug symbols for profiling and performance analysis:
Build Differences:
DEBUG_SYMBOLS=true sets CARGO_PROFILE_RELEASE_DEBUG=true deployment/Dockerfile33-debug suffix in image nameUse Cases:
Sources: .github/workflows/docker-images.yml198-291 deployment/Dockerfile31-33
Specialized image for integration testing, built from deployment/e2e-client.Dockerfile1-56:
Key Differences from Main Image:
fuel-core-e2e-client binary instead of fuel-core-binPurpose: Used in automated integration test suites and CI workflows.
Sources: deployment/e2e-client.Dockerfile1-56 .github/workflows/docker-images.yml293-385
Docker images are tagged using docker/metadata-action with the following patterns:
| Tag Type | Pattern | Example | When Applied |
|---|---|---|---|
| SHA | sha-{sha} | sha-a1b2c3d | Always |
| Branch | {branch} | master | On push to branch |
| Tag | {tag} | v0.32.0 | On release |
| Semver | {version} | 0.32.0 | On release |
| Timestamped | sha-{sha}-{timestamp} | sha-a1b2c3d-20240115123045 | Always |
| Latest | latest | latest | On master branch only |
Implementation:
Sources: .github/workflows/docker-images.yml178-184
Images are simultaneously published to two registries:
Authentication Methods:
GITHUB_TOKEN secret .github/workflows/docker-images.yml158-163arn:aws:iam::024848458133:role/github_oidc_FuelLabs_fuel-coreus-east-1 (ECR Public is only available in us-east-1)Sources: .github/workflows/docker-images.yml146-163 .github/workflows/ci.yml22
Start a fuel-core node with default configuration:
Override default environment variables:
The image includes pre-downloaded chain configurations in /root/config/:
The chain configuration is cloned during build at deployment/Dockerfile51-54 and includes:
Sources: deployment/Dockerfile48-54 deployment/Dockerfile90 deployment/Dockerfile98
In addition to Docker images, the CI workflow produces native binaries for multiple platforms:
| Platform | Target Triple | Runner | Cross-compilation |
|---|---|---|---|
| Linux x64 | x86_64-unknown-linux-gnu | buildjet-4vcpu-ubuntu-2204 | Custom Docker image |
| Linux ARM64 | aarch64-unknown-linux-gnu | buildjet-4vcpu-ubuntu-2204 | Custom Docker image |
| macOS x64 | x86_64-apple-darwin | macos-latest | Native |
| macOS ARM64 | aarch64-apple-darwin | macos-latest | Native |
Sources: .github/workflows/ci.yml296-313
Each release artifact (fuel-core-{version}-{target}.tar.gz) contains:
The WASM executor is automatically built as a side effect of building fuel-core with the upgradable executor feature.
Sources: .github/workflows/ci.yml396-416
Release binaries are stripped to reduce size:
Linux x86_64: Standard strip .github/workflows/ci.yml370-374
Linux ARM64: Cross-strip using Docker .github/workflows/ci.yml376-388
macOS: Strip with -x flag (preserve symbols for debugging) .github/workflows/ci.yml390-394
Sources: .github/workflows/ci.yml370-394
For Linux cross-compilation, custom Docker images are built from files in the ci/ directory:
These images are built once per CI run with BuildKit caching:
Sources: .github/workflows/ci.yml337-346 .github/workflows/ci.yml302-307
The two-phase build with cargo-chef ensures maximum cache utilization:
Planner Stage deployment/Dockerfile23-26:
recipe.json containing only dependency informationCook Stage deployment/Dockerfile44:
recipe.jsonCargo.lock changesFinal Build deployment/Dockerfile62:
Mount caches prevent re-downloading from crates.io and Git repositories:
These caches are:
Sources: deployment/Dockerfile39-44 deployment/Dockerfile57-62
By using native ARM64 runners instead of QEMU emulation, build times for ARM64 images are reduced by approximately 5-10x:
buildjet-8vcpu-ubuntu-2204 .github/workflows/docker-images.yml32buildjet-16vcpu-ubuntu-2204-arm .github/workflows/docker-images.yml33Note that ARM64 builds use 16 vCPUs vs 8 for AMD64, as ARM cores typically have lower single-thread performance.
Sources: .github/workflows/docker-images.yml28-35
The runtime stage uses debian:bookworm-slim deployment/Dockerfile68 which provides:
This matches the base of the Rust builder image, preventing runtime dependency mismatches as noted in .changes/fixed/3124.md1
Only essential utilities are included deployment/Dockerfile81-82:
| Package | Purpose |
|---|---|
ca-certificates | HTTPS connections (Relayer, Gas Price Service) |
curl | Health checks and debugging |
procps | Process inspection (ps, top) |
iputils-ping | Network diagnostics |
jq | JSON processing in scripts |
Sources: deployment/Dockerfile68-86 .changes/fixed/3124.md1
Issue: OpenSSL dependency appears in build
rustls instead of openssl cratesIssue: WASM target build fails
wasm32-unknown-unknown targetIssue: ARM64 build slower than expected
buildjet-16vcpu-ubuntu-2204-arm .github/workflows/docker-images.yml33Issue: Container exits immediately
docker logs <container-id>Issue: Cannot connect to GraphQL API
Issue: Missing chain configuration
/root/config/ in containerdocker exec <container> ls -la /root/config/Sources: deployment/Dockerfile70-98
Refresh this wiki