---
title: "Build container images with BuildKit"
description: "Build a container image from a Dockerfile on a TIR Instance with BuildKit, and push it straight to Container Registry."
content_type: "how-to"
product: "tir-instance"
platform: "TIR"
url: "/tir/tir-instance/how-to/build-container-images-with-buildkit/"
topic: ["guides"]
---

# Build container images with BuildKit

<!-- cspell:ignore buildctl buildkitd jovyan -->

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](/tir/tir-instance/how-to/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](/tir/tir-instance/how-to/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](/tir/tir-instance/how-to/create-an-instance-from-your-own-image/#push-the-image-to-container-registry).

## Install BuildKit's client

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

```bash
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:

```bash
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](/tir/tir-instance/how-to/run-start-scripts-on-an-instance/).

Check that it is on `PATH`:

```bash
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**:

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

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

```json
{
  "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:

```bash
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](/tir/tir-instance/how-to/create-an-instance-from-your-own-image/#launch-from-a-private-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](/tir/tir-instance/how-to/create-an-instance-from-your-own-image/).