Build Docker Images on Instances (BuildKit)

This guide explains how to install BuildKit, build Docker images from a Dockerfile, and push them to a registry on a Instance

---

1. Install BuildKit

Download and extract BuildKit (example: v0.9.0):

wget https://github.com/moby/buildkit/releases/download/v0.9.0/buildkit-v0.9.0.linux-amd64.tar.gz
tar xvf buildkit-v0.9.0.linux-amd64.tar.gz

---

2. Make buildctl Available

Option A: Temporary (session only):

export PATH=$PATH:$(pwd)/buildkit-v0.9.0.linux-amd64/bin

Option B: System-wide (requires sudo):

sudo cp buildkit-v0.9.0.linux-amd64/bin/buildctl /usr/local/bin/
sudo chmod +x /usr/local/bin/buildctl

---

3. Verify Installation

buildctl --version

---

4. Prepare a Dockerfile

Place your Dockerfile in the working directory. For testing, download a sample:

wget --no-check-certificate https://raw.githubusercontent.com/courselabs/kubernetes/main/labs/docker/simple/Dockerfile

---

5. Build and Push an Image

First, configure registry authentication.

Encode your credentials:

echo -n "username:password" | base64

Create $HOME/.docker/config.json with this format (replace BASE64_TOKEN):

{
  "auths": {
    "registry.e2enetworks.net": {
      "auth": "BASE64_TOKEN"
    }
  }
}

For Docker Hub, use "https://index.docker.io/v1/" as the registry key.

Now build and push the image:

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

---

6. Troubleshooting

• Auth errors → Check base64 token and registry URL in config.json
• BuildKit not found → Verify PATH or /usr/local/bin
• Network/DNS issues → Ensure Instance can reach registry and BuildKit endpoint
• Permission denied → Use sudo if installing system-wide

---