Environment:Vespa engine Vespa Docker OCI Container Runtime

Knowledge Sources	Vespa Engine build-container.sh
Domains	Infrastructure, Containers
Last Updated	2026-02-09 00:00 GMT

Overview

Docker container runtime for building Vespa preview and system-test OCI images on AlmaLinux 8/9 base for amd64 and arm64 architectures.

Description

This environment provides the Docker/OCI container context for building Vespa container images. It supports two base OS variants (AlmaLinux 8 and 9) and two architectures (amd64 and arm64). The build process creates both a Vespa preview container and a system-test container. Images are published to GitHub Container Registry (ghcr.io) and Docker Hub.

Usage

Use this environment for container image building and container publishing operations. It is the mandatory prerequisite for running the Build_Container_Sh implementation. The container build depends on completed RPM packages and Maven artifacts.

System Requirements

Category	Requirement	Notes
OS	Linux	Docker host with daemon running
Hardware	amd64 or arm64 CPU	Images are architecture-specific
Memory	4GB+ RAM	Docker build context can be large
Disk	20GB+	Container images, RPM cache, Maven repo
Software	Docker (functional)	Verified at build start

Dependencies

System Packages

• Docker (with daemon running and accessible)
• Git (for cloning docker-image and system-test repositories)
• crane (for getting container image digests)

Base Images

Build OS Label	Vespa Base Image	System Test Base Image
alma8	el8	almalinux:8
alma9	el9	almalinux:9

Credentials

The following environment variables must be set for publishing:

• VESPA_ENGINE_GHCR_IO_WRITE_TOKEN: GitHub Container Registry authentication token
• VESPA_ENGINE_ARTIFACTS_BUCKET: S3 bucket for artifact storage
• VESPA_ENGINE_ARTIFACTS_PREFIX: Artifact path prefix
• VESPA_BUILDOS_LABEL: OS label (alma8 or alma9)
• ARCH: CPU architecture (amd64 or arm64)
• VESPA_VERSION: Version number (default: 8.999.1)
• VESPA_CONTAINER_IMAGE_VERSION_TAG_SUFFIX: Tag suffix (default: -dev-only)

Quick Install

# Verify Docker is functional
docker info > /dev/null 2>&1 || { echo "Docker not available"; exit 1; }

# Clone required repositories
git clone --quiet --depth 1 https://github.com/vespa-engine/docker-image
git clone --quiet --filter="blob:none" https://github.com/vespa-engine/system-test

Code Evidence

Docker validation from build-container.sh:14-17:

if ! docker info > /dev/null 2>&1; then
    echo "Docker not available. Exiting."
    exit 1
fi

Base image selection from build-container.sh:19-26:

case "$VESPA_BUILDOS_LABEL" in
    alma8) VESPA_BASE_IMAGE="el8"; SYSTEM_TEST_BASE_IMAGE="almalinux:8" ;;
    alma9) VESPA_BASE_IMAGE="el9"; SYSTEM_TEST_BASE_IMAGE="almalinux:9" ;;
esac

Shallow clone optimization from build-container.sh:

git clone --quiet --depth 1 https://github.com/vespa-engine/docker-image
git clone --quiet --filter="blob:none" https://github.com/vespa-engine/system-test

Common Errors

Error Message	Cause	Solution
Docker not available. Exiting.	Docker daemon not running	Start Docker daemon: systemctl start docker
unauthorized: authentication required	GHCR token missing	Set VESPA_ENGINE_GHCR_IO_WRITE_TOKEN
no space left on device	Disk full from images	Run docker system prune to free space

Compatibility Notes

• amd64 vs arm64: Images are architecture-specific; no multi-arch manifests at build time.
• AlmaLinux 8 vs 9: Base image selected via VESPA_BUILDOS_LABEL; affects system library versions.
• Shallow clones: --depth 1 for docker-image repo, --filter="blob:none" for system-test repo to minimize download size.

Related Pages

• Implementation:Vespa_engine_Vespa_Build_Container_Sh