logo

Faster 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 below guide to find out how to move your Docker builds to Namespace.

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.

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:
	  # Set permissions for GitHub OIDC token authentication
      id-token: write
    steps:
      - name: Checkout
        uses: actions/checkout@v3
 
	  # 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 Docker's build-push action
      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: .
          tags: app:latest

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:

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

In order to pull images from nscr.io with Docker-like tools, you need to set the credentials with nsc docker login.

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@v3
 
      # 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@v4
        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@v3
 
      # 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@v4
        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:

$ 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@v3
 
      # 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?

Chat with the team on Discord