How to Build an OCI Image from a Dockerfile Using Apple Container

Use the container build command to compile a Dockerfile into a standards-compliant OCI image by running the build inside a lightweight isolation VM, then tag the output with -t for local storage or registry pushes.

Apple Container provides a secure, virtualization-based workflow for converting Dockerfiles into OCI-compliant images on macOS and Linux. The container build command orchestrates this process by spawning a dedicated builder virtual machine (VM) that handles layer compilation without affecting your host system or requiring Docker Desktop.

Understanding the Builder VM Architecture

When you invoke container build, the Apple Container CLI automatically provisions a builder VM if one is not already running. This architecture is documented in docs/how-to.md and docs/container-system-config.md.

The builder VM isolates the entire build process inside a lightweight virtualized environment. By default, the VM is provisioned with 2 GiB of RAM and 2 CPUs, though you can adjust these resources to match your build complexity. The VM runs a container-based build engine that reads your build context, processes Dockerfile instructions, and assembles the final image layers.

OCI-Compliant Image Generation

Inside the builder VM, the build engine tar-packs your build context (the directory you specify) and streams it into a Docker daemon running within the VM. This daemon executes each Dockerfile instruction—creating layers according to OCI specifications—and assembles an OCI-compliant image manifest. The resulting image is stored in the local container image store and can be referenced by the tag you provide during the build process.

Managing the Builder VM Lifecycle

While the builder VM starts automatically when you run container build, you can manage it explicitly for resource-intensive projects.

Starting a Custom Builder VM

To provision a builder with more resources before building, use container builder start as described in docs/how-to.md:

container builder start --cpus 8 --memory 32g

This creates a high-performance build environment suitable for large compilation tasks or multi-stage builds.

Stopping the Builder VM

When you have finished building images, shut down the VM to reclaim system resources:

container builder stop

Building Your First OCI Image

The simplest workflow requires only a single command from your project directory containing a Dockerfile:

container build --tag my-app:latest .

This command:

1. Starts the builder VM (if not running)
2. Streams the current directory (.) as the build context
3. Processes the Dockerfile found in the root of that context
4. Tags the resulting OCI image as my-app:latest in the local store

Using Custom Dockerfile Locations

If your Dockerfile uses a non-standard name or resides in a subdirectory, specify it with the -f or --file flag:

container build -f Dockerfile.prod -t my-app:prod .

You can apply multiple tags to a single build output by repeating the -t flag:

container build \
  -f Dockerfile.prod \
  -t my-app:prod \
  -t my-app:1.0.0 \
  .

Advanced Build Options

Apple Container supports several flags to fine-tune the build process, documented in docs/command-reference.md#container-build:

Multi-Architecture Builds

Build for multiple CPU architectures (such as arm64 and amd64) simultaneously using the --arch flag. The builder automatically configures the appropriate cross-compilation environment as detailed in docs/how-to.md#multi-arch-builds:

container build \
  --arch arm64 \
  --arch amd64 \
  -t registry.example.com/my-app:latest \
  -f Dockerfile .

Build-Time Variables and Caching

Pass build arguments to your Dockerfile using --build-arg:

container build --build-arg VERSION=1.0.0 -t my-app:latest .

Disable layer caching for reproducible clean builds with --no-cache:

container build --no-cache -t my-app:latest .

Debugging and Multi-Stage Targets

Build up to a specific stage in a multi-stage Dockerfile using --target, or enable verbose output for troubleshooting with --debug:

container build --target builder --debug -t my-app:builder .

Summary

• container build is the primary command for converting Dockerfiles into OCI images using Apple Container.
• The command runs inside a builder VM that isolates the build process and defaults to 2 GiB RAM and 2 CPUs.
• Control VM resources explicitly using container builder start with --cpus and --memory flags.
• Reference custom Dockerfiles with --file or -f, and apply multiple tags by repeating -t.
• Build for multiple architectures using --arch flags for cross-platform distribution.
• View complete option documentation in docs/command-reference.md.

Frequently Asked Questions

How does Apple Container isolate the build process from my host system?

According to the apple/container source code and docs/how-to.md, the container build command spawns a lightweight "builder" VM that runs the build engine inside a virtualized environment. This VM isolates the Docker daemon and build context, ensuring that build processes cannot affect the host filesystem or security posture.

Can I build OCI images for multiple architectures simultaneously?

Yes. Pass the --arch flag multiple times to request builds for different architectures (e.g., arm64 and amd64). The builder VM will provision the appropriate cross-compilation environments automatically, as implemented in the build engine referenced in docs/how-to.md#multi-arch-builds.

Where is the built OCI image stored after the build completes?

The resulting OCI-compliant image is stored in the local container image store maintained by Apple Container on your machine. You can reference it locally by the tag specified during build (e.g., my-app:latest), or push it to a remote registry using container push <image-name>.

How do I perform a clean build without using cached layers?

Pass the --no-cache flag to container build. This instructs the builder VM to execute every Dockerfile instruction from scratch, ignoring any previously built layers, which is useful for reproducibility testing or debugging layer-related issues.

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