Docker Builders

WarpBuild provides powerful Docker builders that significantly accelerate your Docker build times, delivering superior performance for your containerization workflow.

Features

• 🚀 Fast Docker builds with WarpBuild's remote builder nodes.
• 🔄 Automatic Docker BuildX integration.
• 🔐 Secure TLS authentication.
• 🌐 Works with both WarpBuild runners and non-WarpBuild runners.
• 🔌 Integrate anywhere via API, supporting local development and various CI platforms (GitHub, GitLab, Bitbucket, Buildkite, etc.).
• 🏗️ Multi-architecture builds (amd64, arm64) out of the box.

See it in Action

Experience up to 50% faster Docker builds compared to traditional solutions. Our optimized builder infrastructure handles the heavy lifting so your CI/CD pipeline runs more efficiently.

To get started with Docker builders, go to the Docker Builders page and create a builder profile.

Concurrency

Each builder profile corresponds to one optimized, dedicated Docker builder virtual machine with caching. Multiple jobs can run on the same builder profile in parallel and these will effectively run on the same VM in parallel.

While there is no limit on the number of builds that can be run concurrently on a builder profile, the recommended minimum resource requirements for builders is approximately 8 vCPU and 16GB memory per build job.

Usage

Using WarpBuild's Build Push Action (Recommended)

WarpBuild provides a drop-in replacement for the widely used docker/build-push-action. Our action automatically sets up the WarpBuild's Remote Docker builders for you.

Note: We recommend that you remove the docker/setup-buildx-action step from your workflow if you are only using it to setup builders.

- name: Setup Buildx
- uses: docker/setup-buildx-action@v3

  name: Docker Build Push Action
- uses: docker/build-push-action@v6
+ uses: Warpbuilds/build-push-action@v6 # Uses WarpBuild Docker Builders
  with:
    context: .
    push: true
    tags: user/app:latest
+   profile-name: "super-fast-builder" # Specify the builder profile to use

Here's how you can use the Warpbuilds/build-push-action in your workflows, whether you are using WarpBuild Runners or non-WarpBuild Runners.

jobs:
  build:
    runs-on: warp-ubuntu-latest-x64-4x
    steps:
      - uses: actions/checkout@v3

      - name: Build and push
        uses: Warpbuilds/build-push-action@v6
        with:
          context: .
          push: true
          tags: user/app:latest
          profile-name: "super-fast-builder"
          api-key: ${{ secrets.WARPBUILD_API_KEY }} # Not required for WarpBuild Runners
          timeout: 600000 # The timeout(in ms) to wait for the Docker Builders to be ready. By default, it is 10 minutes

Using WarpBuild's Bake Action

WarpBuild provides a drop-in replacement for the widely used docker/bake-action. Our action automatically sets up the WarpBuild's Remote Docker builders for you.

Note: We recommend that you remove the docker/setup-buildx-action step from your workflow if you are only using it to setup builders.

- name: Setup Buildx
- uses: docker/setup-buildx-action@v3

  name: Docker Bake Action
- uses: docker/bake-action@v6
+ uses: Warpbuilds/bake-action@v6 # Uses WarpBuild Docker Builders
  with:
    context: .
    push: true
    tags: user/app:latest
+   profile-name: "super-fast-builder" # Specify the builder profile to use

Here's how you can use the Warpbuilds/bake-action in your workflows, whether you are using WarpBuild Runners or non-WarpBuild Runners.

jobs:
  build:
    runs-on: warp-ubuntu-latest-x64-4x
    steps:
      - uses: actions/checkout@v3

      - name: Bake
        uses: Warpbuilds/bake-action@v6
        with:
          context: .
          push: true
          set: |
            *.tags=user/app:latest
          profile-name: "super-fast-builder"
          api-key: ${{ secrets.WARPBUILD_API_KEY }} # Not required for WarpBuild Runners
          timeout: 600000 # The timeout(in ms) to wait for the Docker Builders to be ready. By default, it is 10 minutes

Using WarpBuild's Docker Configure Action

For users wanting more control over their workflows, WarpBuild provides a docker-configure action. This action sets up the builder for you in the VM and outputs all their details which you can then use in your workflow. Although, we recommend using the Warpbuilds/build-push-action as it is easier to use, this action allows you to use builders with your custom steps.

With WarpBuild Runners

 jobs:
   build:
     runs-on: warp-ubuntu-latest-x64-4x
     steps:
       - uses: actions/checkout@v4

-      - name: Setup Buildx
-      - uses: docker/setup-buildx-action@v3

+      - name: Configure WarpBuild Docker Builders
+        uses: Warpbuilds/docker-configure@v1
+        with:
+          api-key: ${{ secrets.WARPBUILD_API_KEY }} # Not required on WarpBuild Runners
+          profile-name: "super-fast-builder"
+          timeout: 300000 # The timeout(in ms) to wait for the Docker Builders to be ready. By default, it is 5 minutes

       - name: Custom Build docker image
         run: |
           ...

Learn more about the outputs of the docker-configure action in the docker-configure action docs.

From CLI

You can use WarpBuild's Docker builders directly from your CLI.

1. Set your API key as an environment variable:

   export WARPBUILD_API_KEY="your-api-key"

2. Assign builders from your profile:

   # Generate a unique idempotency key (16 characters) - Optional
   IDEMPOTENCY_KEY=$(uuidgen | tr -d '-' | cut -c1-16)
   BUILDER_NAME="builder-$IDEMPOTENCY_KEY"
   
   # Request a builder assignment
   # Note: external_unique_id is optional but recommended for idempotency
   RESPONSE=$(curl -s -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $WARPBUILD_API_KEY" \
     -d '{"profile_name": "your-profile-name", "external_unique_id": "'"$IDEMPOTENCY_KEY"'"}' \
     https://api.warpbuild.com/api/v1/builders/assign)
   
   # Get all builder IDs and request IDs (we'll use the first one for this example)
   BUILDER_ID=$(echo $RESPONSE | jq -r '.builder_instances[0].id')
   REQUEST_ID=$(echo $RESPONSE | jq -r '.builder_instances[0].request_id')

3. Wait for builder to be ready and get details:

   # Poll for builder details until status is ready
   echo "Waiting for builder to be ready..."
   while true; do
     DETAILS=$(curl -s -H "Authorization: Bearer $WARPBUILD_API_KEY" \
       https://api.warpbuild.com/api/v1/builders/$BUILDER_ID/details)
     
     STATUS=$(echo $DETAILS | jq -r '.status')
     
     if [ "$STATUS" = "ready" ]; then
       echo "Builder is ready!"
       break
     elif [ "$STATUS" = "failed" ]; then
       echo "Builder failed to initialize"
       exit 1
     fi
     
     echo "Builder status: $STATUS. Waiting..."
     sleep 2
   done
   
   # Extract connection information
   HOST=$(echo $DETAILS | jq -r '.metadata.host')
   
   # Create certificate directory
   CERT_DIR="$HOME/.docker/warpbuild/$BUILDER_NAME/$BUILDER_ID"
   mkdir -p $CERT_DIR
   
   # Save certificates
   echo "$DETAILS" | jq -r '.metadata.ca' > $CERT_DIR/ca.pem
   echo "$DETAILS" | jq -r '.metadata.client_cert' > $CERT_DIR/cert.pem
   echo "$DETAILS" | jq -r '.metadata.client_key' > $CERT_DIR/key.pem

4. Create a buildx instance with your builder:

   docker buildx create --name "$BUILDER_NAME" \
     --node "$BUILDER_ID" \
     --driver remote \
     --driver-opt "cacert=$CERT_DIR/ca.pem" \
     --driver-opt "cert=$CERT_DIR/cert.pem" \
     --driver-opt "key=$CERT_DIR/key.pem" \
     --use \
     tcp://$HOST

5. Use the builder for your Docker builds:

   docker buildx build --builder $BUILDER_NAME -t myimage:latest .

You can now use this builder for faster Docker builds directly from your terminal!

6. Terminate the assigned builders after usage:

   # Complete the builder session
   # To be done for all builder instances (we'll use the first one for this example)
   RESPONSE=$(curl -s -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $WARPBUILD_API_KEY" \
     -d '{"request_id": "'"$REQUEST_ID"'", "external_unique_id": "'"$IDEMPOTENCY_KEY"'"}' \
     https://api.warpbuild.com/api/v1/builder-session-requests/complete)
   
   # Remove the buildx builder configuration
   docker buildx rm $BUILDER_NAME --force

Note : User will be billed for entire duration till the assigned builders are terminated by user.

Resetting the cache

If you need to reset the cache for a builder profile, you can do so by using the following steps.

1. Get the builder profile id using the following command.

curl -s -H "Authorization: Bearer $WARPBUILD_API_KEY" \
  https://api.warpbuild.com/api/v1/builder-profiles?per_page=30&page=1

2. Reset the cache for the builder profile id.

curl -s -X POST \
  -H "Authorization: Bearer $WARPBUILD_API_KEY" \
  https://api.warpbuild.com/api/v1/builder-profiles/$BUILDER_PROFILE_ID/cache/reset

Working with multiple builders

If your assignment returns multiple builders, you can set up additional nodes:

# For a second builder
BUILDER_ID_2=$(echo $RESPONSE | jq -r '.builder_instances[1].id')
REQUEST_ID_2=$(echo $RESPONSE | jq -r '.builder_instances[1].request_id')

# Poll for builder details until status is ready
echo "Waiting for second builder to be ready..."
while true; do
  DETAILS_2=$(curl -s -H "Authorization: Bearer $WARPBUILD_API_KEY" \
    https://api.warpbuild.com/api/v1/builders/$BUILDER_ID_2/details)
  
  STATUS_2=$(echo $DETAILS_2 | jq -r '.status')
  
  if [ "$STATUS_2" = "ready" ]; then
    echo "Second builder is ready!"
    break
  elif [ "$STATUS_2" = "failed" ]; then
    echo "Second builder failed to initialize"
    exit 1
  fi
  
  echo "Builder status: $STATUS_2. Waiting..."
  sleep 2
done

# Extract connection information
HOST_2=$(echo $DETAILS_2 | jq -r '.metadata.host')

# Create certificate directory
CERT_DIR_2="$HOME/.docker/warpbuild/$BUILDER_NAME/$BUILDER_ID_2"
mkdir -p $CERT_DIR_2

# Save certificates
echo "$DETAILS_2" | jq -r '.metadata.ca' > $CERT_DIR_2/ca.pem
echo "$DETAILS_2" | jq -r '.metadata.client_cert' > $CERT_DIR_2/cert.pem
echo "$DETAILS_2" | jq -r '.metadata.client_key' > $CERT_DIR_2/key.pem

# Append second builder to existing buildx instance
docker buildx create --name "$BUILDER_NAME" \
  --append \
  --node "$BUILDER_ID_2" \
  --driver remote \
  --driver-opt "cacert=$CERT_DIR_2/ca.pem" \
  --driver-opt "cert=$CERT_DIR_2/cert.pem" \
  --driver-opt "key=$CERT_DIR_2/key.pem" \
  --use \
  tcp://$HOST_2

With multiple builders configured, your buildx instance can distribute build workloads more efficiently.

Multi platform builds

WarpBuild supports multi-platform builds for Docker images. You can specify the platforms you want to build for using the platforms option in the docker/build-push-action.

Note: Make sure that the builder profile being used has both architectures enabled in WarpBuild UI.

platforms: linux/amd64,linux/arm64

Deleting a Builder Profile

You can delete a builder profile from the Docker Builders page. It is necessary to wait for all the builds to finish before deleting a builder profile.

Pricing

Usage is charged for the duration of the builder and the builder size. Any number of builds can be run concurrently on a builder profile.

Any number of container builds can run on the builders in parallel.

Multi-arch builders are billed at 2x the price of single-arch builders.

F.A.Q.

How does caching work for concurrent builds?

For caching behavior between concurrent builds, note that the cache is shared but eventually consistent. This means that layer caching from one build may not be immediately available to another concurrent build, but will be available for future builds after synchronization occurs.

Build summary doesn't get generated

At the moment, build summary will not be generated from docker/build-push-action. The action might also display a warning. This is expected and does not affect the build process.

We recommend to add the following env variables in docker/build-push-action to disable the build summary.

- name: Build and push
  uses: docker/build-push-action@v6
  env:
    DOCKER_BUILD_RECORD_UPLOAD: false
    DOCKER_BUILD_SUMMARY: false
    DOCKER_BUILD_CHECKS_ANNOTATIONS: false

Docker Builder is timing out

Docker Builders have timeout built-in so that users don't get charged for builders that are idle. We recommend that you invoke the WarpBuilds/docker-configure action just before the build-and-push action or any other step that performs docker build.

How to use cache-to and cache-from with Docker Builders

When using Docker Builders, the cache-to and cache-from options are not required. A cached Docker Builder will automatically cache the layers and reuse them for subsequent builds.

- name: Older Docker WarpCache Backend
-  uses: docker/build-push-action@v6
-  with:
-    context: .
-    push: false
-    tags: "alpine/warpcache:latest"
-    cache-from: type=gha,url=http://127.0.0.1:49160/
-    cache-to: type=gha,url=http://127.0.0.1:49160/,mode=max

+ name: New WarpBuild Docker Builders
+  uses: Warpbuilds/docker-configure@v1
+  with:
+    profile-name: "super-fast-builder"

+ name: Build and push
+  uses: docker/build-push-action@v6
+  with:
+      context: .
+      push: false
+      tags: "alpine/warpcache:latest"

Is the size of the Docker machine related to the the GitHub runner?

No, the size of the Docker machine is not limited by or related to the size of the GitHub runner used. It is determined by the size of the builder profile that you have selected.

Do I get charged for both the GitHub runner and the WarpBuild Docker builder runtime?

Yes. These are two separate, independent resources and you will be charged for both.

exec format error while building for arm64 / multi-platform builds

This is likely because the builder profile does not have the correct architectures selected for your builder profile. Ensure the builder profile has both the architectures enabled.