Bazel OCI Container Example

This project demonstrates how to create a container image using Bazel and rules_oci, starting from a DHI Alpine base 3.22 image and copying a local file into the container.

Files Structure

.
├── MODULE.bazel           # Modern Bazel dependency management (bzlmod)
├── WORKSPACE             # Empty WORKSPACE file for compatibility
├── .bazelrc              # Bazel configuration
├── .gitignore            # Git ignore file for build artifacts
├── BUILD.bazel           # Main build targets
├── hello.txt             # Sample file to copy into container
├── platforms/
│   └── BUILD.bazel       # Platform definitions
├── demo.sh               # Demo script to build and show usage
└── README.md             # This file

Prerequisites

• Bazel version 8.0 or later
• Docker (optional, for testing the built image)

What This Example Does

1. Base Image: Uses DHI Alpine base 3.22 as the base image
2. File Copy: Copies the local hello.txt file into the /app directory of the container
3. Entrypoint: Sets the container entrypoint to cat /app/hello.txt, so the container displays the file content when run
4. Configuration: Sets working directory to /app, adds labels and environment variables
5. Outputs: Creates both an OCI image and a tarball for distribution

Quick Demo

For a quick demonstration, run the demo script:

./demo.sh

This will build the container and show you how to test it with Docker.

Building the Container

Build the OCI Image

bazel build //:dhi_alpine_app --platforms=//platforms:linux_amd64

Build the Container Tarball

bazel build //:dhi_alpine_app_tarball --platforms=//platforms:linux_amd64

The tarball can be found at bazel-bin/dhi_alpine_app_tarball/tarball.tar and can be loaded into Docker:

docker load < bazel-bin/dhi_alpine_app_tarball/tarball.tar

Run the Container

After loading the tarball into Docker:

# Run the container (will automatically display hello.txt content due to entrypoint)
docker run --rm dhi-alpine-app:latest

# You can also run other commands by overriding the entrypoint
docker run --rm --entrypoint="" dhi-alpine-app:latest ls -la /app

Build Targets

• :app_layer - Creates a tar layer containing the hello.txt file
• :dhi_alpine_app - The main OCI image target
• :dhi_alpine_app_tarball - Creates a tarball of the image for easy distribution

Key Configuration

MODULE.bazel Dependencies

• rules_oci@1.7.6 - OCI container image building rules
• rules_pkg@1.0.1 - Package creation rules
• rules_cc@0.0.9 - C/C++ rules (needed for platform definitions)
• platforms@0.0.10 - Platform definitions

Base Image

The DHI Alpine base 3.22 image is pulled from the DHI registry:

oci.pull(
    name = "alpine",
    image = "index.docker.io/dhi/alpine-base:3.22",
    platforms = ["linux/amd64"],
)

Container Configuration

• Working Directory: /app
• Entrypoint: cat /app/hello.txt - automatically displays the hello.txt content when container runs
• Environment Variables:
  • APP_NAME=alpine_example
  • APP_VERSION=1.0.0
• Labels: Includes standard OCI image labels
• File Permissions: Copied file has mode 0644

Customization

To adapt this example for your needs:

1. Change the base image: Modify the oci.pull block in MODULE.bazel
2. Add more files: Update the srcs list in the pkg_tar target
3. Modify container config: Update labels, environment variables, or working directory in the oci_image target
4. Add build steps: Create additional targets for compiling code before packaging

Troubleshooting

Platform Issues

If you encounter platform-related errors, ensure you're building with the correct platform:

bazel build //:dhi_alpine_app_tarball --platforms=//platforms:linux_amd64

Dependency Warnings

The build may show warnings about newer versions of dependencies being available. These can usually be ignored or you can update the versions in MODULE.bazel.

Advanced Usage

Multi-Platform Builds

To build for multiple platforms, modify the platforms list in MODULE.bazel and create additional platform definitions.

Layer Optimization

For more complex applications, consider creating multiple tar layers to optimize container build caching.

Custom Base Images

Replace the Alpine base with your preferred base image by updating the oci.pull configuration.

---

This example provides a foundation for building container images with Bazel and can be extended to build more complex applications.

Git Setup

The project includes a comprehensive .gitignore file that excludes:

• Bazel build outputs (bazel-* symlinks)
• Generated lock files (MODULE.bazel.lock)
• IDE files and system files
• Container tarballs (optional)

To initialize a git repository:

git init
git add .
git commit -m "Initial commit: Bazel OCI container example with DHI Alpine base"