How to Use bpftime Docker Images: Complete Setup and Customization Guide

The bpftime project provides an official Docker image at ghcr.io/eunomia-bpf/bpftime:latest that packages the complete build environment, LLVM JIT runtime, and CLI tools, enabling you to develop and test eBPF programs without installing host dependencies.

The eunomia-bpf/bpftime repository maintains ready-to-use container images that streamline the setup process for userspace eBPF development. These bpftime Docker images eliminate the need to manually install LLVM 17, Boost, and other complex dependencies on your host system.

What Are bpftime Docker Images?

The official bpftime Docker image serves as a self-contained development environment built on ubuntu:24.04. According to the source code in Dockerfile, the image includes:

• System dependencies: Boost libraries, libelf, LLVM 17, clang, and build essentials
• Pre-compiled runtime: The bpftime runtime built with BPFTIME_VM_NAME=llvm environment variable selecting the LLVM JIT backend
• CLI tools: The bpftime command-line interface installed under /root/.bpftime/ and added to $PATH

The CI workflow defined in .github/workflows/docker.yml automatically builds and publishes this image to the GitHub Container Registry (ghcr.io/eunomia-bpf/bpftime:latest) whenever the master branch updates.

Pulling and Running the Official bpftime Docker Image

Starting an Interactive Development Container

To begin using bpftime Docker images for development, mount your local source directory into the container:

docker run -it --rm \
  -v "$(pwd)":/workdir \
  -w /workdir \
  ghcr.io/eunomia-bpf/bpftime:latest /bin/bash

This command starts an interactive shell with your current working directory mounted at /workdir. The container inherits the bpftime environment variables, including LLVM_DIR and BPFTIME_VM_NAME=llvm, ensuring the LLVM JIT backend is active.

Building and Testing eBPF Programs

Once inside the container, you can build the project using the pre-configured environment:

# Compile the whole project in release mode

make release JOBS=$(nproc)

# The bpftime CLI is available immediately

bpftime --help

# Load an eBPF program and start the runtime

bpftime load ./example/malloc/malloc
bpftime start ./example/malloc/victim

These steps leverage the build system configured in Dockerfile lines 17-26, which compiles bpftime with CMake and installs binaries to /root/.bpftime/.

Building Custom bpftime Docker Images

Local Development Builds

For scenarios requiring modifications to the runtime or dependencies, build the image locally from the repository:

# Clone with submodules to ensure all dependencies are present

git clone --recursive https://github.com/eunomia-bpf/bpftime.git
cd bpftime

# Build the image locally

docker build -t my-bpftime:dev .

This process uses the main Dockerfile, which copies the repository into the image and initializes git submodules (lines 9-12).

ARM64 Architecture Support

The repository provides tools/Dockerfile.arm for building on ARM64 platforms. The helper script tools/test_arm_build.sh demonstrates the complete workflow:

# Build for ARM64

docker build --platform linux/arm64 -f tools/Dockerfile.arm -t bpftime-arm .

# Run tests on ARM64 architecture

docker run --platform linux/arm64 --rm bpftime-arm sh -c "cd /bpftime && make release -j\$(nproc)"

This approach is essential for cross-platform development targeting embedded ARM devices or Apple Silicon Macs.

Extending bpftime Docker Images for Advanced Workflows

When you need additional tools like Python scripting or GDB debugging, extend the official image rather than modifying the base:

FROM ghcr.io/eunomia-bpf/bpftime:latest

RUN apt-get update && apt-get install -y python3 gdb

Build and run your extended image:

docker build -t bpftime-with-tools .
docker run -it --rm -v "$(pwd)":/workdir -w /workdir bpftime-with-tools /bin/bash

This pattern keeps your customizations separate from the upstream bpftime environment while maintaining compatibility with the LLVM JIT backend and pre-installed dependencies.

Understanding the bpftime Docker Image Architecture

The bpftime Docker image construction follows a layered approach defined in the repository's Dockerfile:

Component	Implementation Details	Source Location
Base Environment	ubuntu:24.04 provides the foundational Linux user-space.	Dockerfile line 1
Build Dependencies	Installs Boost, libelf, LLVM 17, clang, and CMake via apt-get.	Dockerfile lines 4-7
Source Integration	Copies repository and recursively initializes git submodules.	Dockerfile lines 9-12
Environment Configuration	Sets BPFTIME_VM_NAME=llvm, LLVM_DIR, and extends PATH to include /root/.bpftime/.	Dockerfile lines 13-16
Compilation	CMake configures the project with LLVM toolchain; make -j$(nproc) compiles and installs to ~/.bpftime.	Dockerfile lines 17-26

The resulting image is published to ghcr.io/eunomia-bpf/bpftime:latest through the automated workflow in .github/workflows/docker.yml, ensuring the container always reflects the latest master branch state.

Summary

• The official bpftime Docker image (ghcr.io/eunomia-bpf/bpftime:latest) provides a complete, ready-to-use environment based on Ubuntu 24.04 with LLVM 17 and Boost pre-installed.
• Quick start workflow involves running the container with volume mounts for your source code, then using make release and bpftime CLI commands immediately.
• Custom builds are supported through the main Dockerfile for x86_64 and tools/Dockerfile.arm for ARM64 architectures, with helper scripts available for cross-platform compilation.
• Extension capabilities allow you to layer additional tools (Python, GDB) on top of the base image without modifying the upstream Dockerfile.

Frequently Asked Questions

How do I access the bpftime CLI tools inside the Docker container?

The bpftime CLI is automatically available when you start the container because the Dockerfile adds /root/.bpftime/ to the PATH environment variable (line 16). Simply type bpftime --help or use bpftime load and bpftime start to interact with the runtime.

Can I use bpftime Docker images for ARM64 development?

Yes, the repository provides tools/Dockerfile.arm specifically for ARM64 builds. Use the command docker build --platform linux/arm64 -f tools/Dockerfile.arm -t bpftime-arm . to create an ARM-compatible image, or run the helper script tools/test_arm_build.sh which automates the build and test process for the ARM platform.

How do I mount my host source code into the bpftime container?

Use the -v flag when running the container to bind-mount your local directory. The standard pattern is docker run -it --rm -v "$(pwd)":/workdir -w /workdir ghcr.io/eunomia-bpf/bpftime:latest /bin/bash, which mounts your current working directory to /workdir inside the container and sets it as the working directory.

Where are the bpftime binaries installed inside the Docker image?

The build process installs all bpftime binaries to /root/.bpftime/ (configured in Dockerfile lines 17-26). The Dockerfile then prepends this directory to the system PATH (line 16), making the binaries accessible from any shell location without specifying the full path.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}