Faster Docker Builds

We hear you want faster Docker builds, then we got you covered! Namespace offers Remote Builders that are 3-4x more powerful than your usual CI hosting platform. Our default Builder instances come with 16+ CPU cores and 32+ GB of RAM. But we understand that just more compute resources are not enough to provide faster Docker builds. So, we also provide dedicated caching across your team.

We developed our GitHub Actions integration to provide a drop-in replacement for Docker GitHub Actions. But you might also be interested in our nsc CLI that offers the same capabilities in any environment you run in.

Follow the guide below to find out how to move your Docker builds to Namespace.

Why Namespace Remote Builders?

Designed as an drop-in replacement for docker build, Namespace Remote Builders bring to the table:

1 More capacity out of the box, starting at 16 vCPU / 32GB RAM, with higher performance per core. Leads to faster "cold" builds (i.e. not cached).

2 Out-of-the-box support for incremental build caching, with zero configuration.

3 Built-in AMD64 and ARM64 native building.

4 Our pricing model is transparent, predictable and competitive.

5 Full compatibility with docker build: You configure your workstation or CI's docker to use our remote builders using a single command, and can continue using docker build as usual.

Prerequisites

1 Install Namespace CLI

2 (Optional) Onboard Namespace in your GitHub account if you want to use our GitHub Actions integration

Namespace CLI

Namespace CLI allows you to build any application that is packaged through Docker. With nsc you can build, tag and push a Docker image in a single command invocation.

First of all, you need to be logged in to Namespace. This command will open your default browser to authenticate against our backend.

$ nsc login

Now, you are ready for your first build on our Remote Builders. The nsc build command can push the image to any registry. For optimal performance, here we are going to push to Namespace Container Registry. But you can also push the image to other registries, such as GitHub Container Registry, Amazon ECR, etc.

$ nsc build . --name app --push

The command will show the Buildkit logs. At the very end, you will see where your image were pushed. Something like the following:

Pushed:
  nscr.io/8enum0hp1l5ii/app:latest

Multi-platform Builds

You can build the Docker image for multiple platforms in a single command with the --platform flag.

$ nsc build . --platform linux/amd64,linux/arm64 --name app --push

nsc build takes care of appending the architecture to image tags and merging both tags into a single image manifest (i.e. index).

Pushed:
  nscr.io/8enum0hp1l5ii/app:latest-amd64
Pushed:
  nscr.io/8enum0hp1l5ii/app:latest-arm64
Reindex the image:
  nscr.io/8enum0hp1l5ii/app:latest

Remote builds optimize your build times by relying on the same machine types that you're building for. For example, if you're doing a multi-platform build that also includes linux/arm64, most of the times we'll schedule it in an arm64 machine (pending availability). This will dramatically improve your build times.

Seamless Integration with Docker

Namespace offers a seamless integration with Docker allowing you to keep using your familiar Docker CLI while using Remote Builders.

$ nsc docker buildx setup --background --use

This command starts a Unix socket proxy and configures buildx to use the proxy to connect with the Namespace Remote Builders. The builder machines are created on demand whenever the buildx issues a build request, triggering a connection to the remote builders. The architecture of the builder machine (AMD64 or ARM64) is inferred by the build command's platform.

Then, following Docker builds will use Remote Builders.

$ docker build . -t app:latest

To monitor the current state of the buildx proxy, run the following command.

$ nsc docker buildx status

Homebrew Service

The Docker buildx proxy can also be installed as Homebrew Services. Homebrew keeps the proxy running in background, even after machine reboots.

$ brew install namespacelabs/namespace/nsc-remote-builder
$ brew services start nsc-remote-builder

To stop the service, run the following command.

$ brew services stop nsc-remote-builder

GitHub Actions

We also offer a seamless integration with GitHub Actions. The easiest way to use Namespace in your GitHub Workflow is to call our GitHub Action nscloud-setup-buildx-action. The Action works similarly to the official Docker's setup-buildx-action, with the difference that ours configures Docker Buildx to use your Builder instance running in Namespace as backend.

The following Docker Buildx commands - such as docker/build-push-action Action - will build on the Remote Builder rather than in the local GitHub runner. For example:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # Permission to checkout the repository
      contents: read
      # Permission to fetch GitHub OIDC token authentication
      id-token: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      # Install CLI and authenticate to Namespace
      - name: Install and configure Namespace CLI
        uses: namespacelabs/nscloud-setup@v0
 
      # Setup Docker build to use your Namespace workspace builder
      - name: Configure Namespace powered Buildx
        uses: namespacelabs/nscloud-setup-buildx-action@v0
 
      # Run standard multi-platform Docker's build-push action
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          tags: app:latest
          platforms: linux/amd64,linux/arm64

Caching

Remote Builders perform incremental build caching out of the box - no configuration is required. The build cache is shared for the entire workspace, so every workspace member benefits with fast, incremental builds.

Build caches are powered by Cache Volumes leading to high performance at no startup time tax. The size of the cache volume attached to a builder is computed as: vCPU count x 8GB

Trace Viewer

Every Docker build handled by Namespace's Remote Builders gets its own trace view. You can intuitively debug why a particular build didn't perform as you expected.

The trace view highlights the time spent on each build instruction. Also, it displays the position of that instruction within the total duration of the build, making it trivial to spot which step waited for another one. If an instruction was fully cached, you will see a grayed out line instead.

Examples

Build and Push with Namespace CLI

First of all, we need some code to build and a Dockerfile. You can also follow the same steps with your own project. Here we provide a sample Python Django application for you to try out our Remote Buiders.

$ git clone https://github.com/namespacelabs/examples-nsc-build-simple.git
$ cd examples-nsc-build-simple

Then, you need to login to Namespace. This command will open your default browser to authenticate against our backend.

$ nsc login

You are ready for your first build! The nsc build command can push the image to any registry. Here we are going to push to your dedicated Workspace Container Registry.

$ nsc build . -n django-app:v0.0.1 -p

The command will show the Buildkit logs. At the very end, you will see where your image were pushed. Something like the following:

Pushed:
  nscr.io/8enum0hp1l5ii/django-app:v0.0.1

Finally, you can just consume the image from anywhere you want. For example with docker pull:

$ nsc docker login
$ docker pull nscr.io/8enum0hp1l5ii/django-app:v0.0.1

Build and Push to GitHub Container Registry

You can use the Docker push to upload an image to any container registry. In this example, we log in to GitHub Container Registry using the GITHUB_TOKEN. However, this would work the same way for any other Container Registry provider (e.g. Amazon ECR or GCP Artifact Registry).

name: build-with-actions
on: [push]
 
permissions:
  # Required for requesting the GitHub Token
  id-token: write
  # Required for pushing images to GitHub Container Registry
  packages: write
 
jobs:
  build_with_nscloud:
    runs-on: ubuntu-latest
    name: Build with Namespace
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      # We are going to push to GitHub Container Registry
      - name: Login to GitHub Container Registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      # Install CLI and authenticate to Namespace
      - name: Install and configure Namespace CLI
        uses: namespacelabs/nscloud-setup@v0
 
      # Setup docker build to use your Namespace workspace builder
      - name: Set up Namespace Buildx
        uses: namespacelabs/nscloud-setup-buildx-action@v0
 
      # Run standard Docker's build-push action
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository_owner }}/app:latest

Once the GitHub Workflow is completed, you can pull the newly built image with:

$ docker pull ghcr.io/{ your GitHub username }/app:latest

Build and Push to Namespace Container Registry

We also offer our own Container Registry, which is already set up for you when you logged in Namespace. The advantage of our registry - compared to GitHub's one - is that it's shared across the whole team Workspace, so caching hits are maximized across the team. Using the registry is as straight forward as following the below example.

name: build-and-push-ns-registry
on: [push]
 
permissions:
  # Required for requesting the GitHub Token
  id-token: write
 
jobs:
  build_with_nscloud:
    runs-on: ubuntu-latest
    name: Build with Namespace
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      # Install CLI and authenticate to Namespace
      - name: Install and configure Namespace CLI
        id: nscloud # Needed to access its outputs
        uses: namespacelabs/nscloud-setup@v0
 
      # Setup docker build to use your Namespace workspace builder
      - name: Set up Namespace Buildx
        uses: namespacelabs/nscloud-setup-buildx-action@v0
 
      # Run standard Docker's build-push action
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.nscloud.outputs.registry-address }}/app:latest

Once the GitHub Workflow is completed, you can pull the newly built image with:

$ nsc docker login
$ docker pull nscr.io/8enum0hp1l5ii/app:latest

Build and Export to Docker

If you need the image available in the local Docker of your GitHub runner, then you can simply use our CLI. The nsc build command with --load flag will build the Docker image in the Remote Builder instance and then export it to the local Docker daemon.

name: build-with-cli
on: [push]
 
permissions:
  # Required for requesting the GitHub Token
  id-token: write
 
jobs:
  build_with_nscloud:
    runs-on: ubuntu-latest
    name: Build with Namespace
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      # Install CLI and authenticate to Namespace
      - name: Install and configure Namespace CLI
        uses: namespacelabs/nscloud-setup@v0
 
      # Build and push with your Namespace Workspace Builder
      - name: Build and push with Namespace Remote Builders
        run: |
          nsc build . -t app --load

What's Next?

• Email the team with questions, or leave us feedback.