Build container images with BuildKit

Build a container image from a Dockerfile on a TIR Instance and push it to Container Registry. An instance is itself a container with no Docker daemon, so you build with BuildKit’s buildctl client in place of Docker. It sends the build to a BuildKit build service at buildkit.internal:1234, which builds and pushes the image for you.

Before you begin

• A running TIR Instance, connected over SSH. See Connect to an instance over SSH.
• A Dockerfile and the files it needs, copied to the instance under /home/jovyan so they survive a restart. See Copy files to and from an instance.
• A namespace in your project’s Container Registry, and its username and password from Docker Commands. See Create an instance from your own image.

Install BuildKit’s client

Download buildctl, the BuildKit client, into the workspace so it survives a restart:

mkdir -p /home/jovyan/buildkit && cd /home/jovyan/buildkit
wget https://github.com/moby/buildkit/releases/download/v0.34.0/buildkit-v0.34.0.linux-amd64.tar.gz
tar xvf buildkit-v0.34.0.linux-amd64.tar.gz

The archive unpacks to a bin folder holding buildctl and the other BuildKit binaries. Add it to PATH for this session:

export PATH=$PATH:/home/jovyan/buildkit/bin

A PATH line you add to ~/.bashrc is lost at the next start, so run the export command again in each new session, or add it to a start script. See Run start scripts on an instance.

Check that it is on PATH:

buildctl --version

Set up registry authentication

buildctl reads registry credentials from ~/.docker/config.json, the same file Docker itself uses. Encode your Container Registry username and password from Docker Commands:

echo -n "<username>:<password>" | base64

Create ~/.docker/config.json with the encoded value:

{
  "auths": {
    "registry.e2enetworks.net": {
      "auth": "<base64-encoded-username-and-password>"
    }
  }
}

Use in-south1-registry.e2enetworks.net instead in Chennai. For a public registry such as Docker Hub, use "https://index.docker.io/v1/" as the key.

Build and push the image

From the folder holding your Dockerfile, build the image and push it to Container Registry in one step:

buildctl --addr tcp://buildkit.internal:1234 build \
  --frontend dockerfile.v0 \
  --local context=. --local dockerfile=. \
  --output type=image,name=registry.e2enetworks.net/<namespace>/<image>:<tag>,push=true

Replace <namespace> with your Container Registry namespace, and <image> and <tag> with the name and version you want for the image. The image then shows under Available Images when you pick that namespace on the Private tab, ready to launch. See Create an instance from your own image.

Fix common problems

• An authentication error on push means the base64 token or the registry host in ~/.docker/config.json is wrong; re-encode the credentials and check the host for your region.
• buildctl: command not found means this session’s PATH lacks the BuildKit folder; run the export command again.
• A connection error on --addr tcp://buildkit.internal:1234 means the instance cannot reach the build service. Check that the instance can reach both the registry and buildkit.internal:1234, then contact support with the instance ID and the exact error if it still fails.

Once the image is in Container Registry, launch new instances from it the same way as any other private image; see Create an instance from your own image.