ngen-buildx

Docker Buildx CLI wrapper with GitOps integration.

Overview

ngen-buildx is a CLI tool that simplifies Docker image building using docker buildx. It integrates with ngen-gitops to automatically fetch CI/CD configuration from repositories and supports both remote and local builds.

Features

• 🚀 Remote Build: Build directly from remote Git repositories (default)
• 📁 Local Build: Build from local source directory with --local flag (auto-detects repo and branch)
• 🔧 GitOps Integration: Fetches cicd/cicd.json from repositories using gitops get-file
• 📦 Resource Management: Configurable memory and CPU limits for builds
• 🏗️ Multi-platform Support: Build for multiple architectures
• 🔄 Smart Image Check: Skip build if image already exists (use --rebuild to force)
• 📣 Teams Notification: Send build notifications to Microsoft Teams
• 🏷️ Smart Tagging: Uses local/remote commit ID for branches, tag name for version tags

Installation

pip install ngen-buildx

Prerequisites

• Docker with buildx plugin installed
• ngen-gitops installed and configured with Bitbucket credentials
• ~/.netrc configured with Bitbucket credentials (for remote builds)

Create Docker Buildx Builder

Before using ngen-buildx, you need to create a Docker Buildx builder instance:

# Create a new builder (replace 'container-builder' with your preferred name)
docker buildx create --name container-builder --driver docker-container --use

# Verify the builder is active
docker buildx ls

# Bootstrap the builder (optional, but recommended)
docker buildx inspect --bootstrap

Note: Make sure the builder name matches BUILDER_NAME in your ~/.ngen-buildx/.env configuration.

Quick Start

1. Initialize configuration:

   buildx --init
   

2. Edit configuration files:

   # Edit ~/.ngen-buildx/.env for environment variables
   # Edit ~/.ngen-buildx/arg.json for build arguments
   

3. Build an image:

   # Remote build (from Git repository)
   buildx saas-apigateway develop
   
   # Local build (from current directory, auto-detects repo and branch)
   cd /path/to/project
   buildx --local
   

Configuration

Environment Variables (~/.ngen-buildx/.env)

# Builder Configuration
BUILDER_NAME=container-builder
DEFAULT_MEMORY=4g
DEFAULT_CPU_PERIOD=100000
DEFAULT_CPU_QUOTA=200000

# Registry Configuration
REGISTRY01_URL=myregistry

# GitOps Settings
BITBUCKET_ORG=myorg

# Notifications (Microsoft Teams)
TEAMS_WEBHOOK=https://your-org.webhook.office.com/webhookb2/...

Build Arguments (~/.ngen-buildx/arg.json)

{
    "REGISTRY01": "$REGISTRY01_URL",
    "BRANCH": "$REFS",
    "PROJECT": "$IMAGE",
    "PORT": "$PORT",
    "PORT2": "$PORT2"
}

CICD Configuration (cicd/cicd.json in repository)

{
    "IMAGE": "saas-apigateway",
    "CLUSTER": "qoin",
    "PROJECT": "saas",
    "DEPLOYMENT": "saas-apigateway",
    "NODETYPE": "front",
    "PORT": "8005"
}

Usage

Remote Build (Default)

Build directly from remote Git repository:

# Basic build
buildx <repo> <ref>

# Examples
buildx saas-apigateway develop
buildx saas-apigateway develop --dry-run
buildx myrepo v1.0.0

Local Build

Build from local source directory (auto-detects repo and branch from git):

# Auto-detect repo and branch from current git directory
cd /path/to/project
buildx --local
buildx --local --dry-run

# Explicit repo and ref
buildx myrepo develop --local

# Build with custom cicd.json path
buildx --local --cicd config/cicd.json

# Build with custom context
buildx myrepo develop --local --context ./src

# Local build with push
buildx --local --push

Build Options

Configuration Commands

# Show configuration
buildx --config

# Show as JSON
buildx --config --json

Initialize Command

# Create config files
buildx --init

# Recreate config files
buildx --init --force

Image Tagging

The tool uses smart tagging based on the build mode and reference type:

Example tags:

• Branch build: myregistry/app:f51df9 (6-char commit ID)
• Tag build: myregistry/app:v1.0.0 (tag name)

Generated Build Command

Remote Build

docker buildx build \
  --builder container-builder \
  --sbom=true \
  --no-cache \
  --attest type=provenance,mode=max \
  --memory 4g \
  --cpu-period 100000 \
  --cpu-quota 200000 \
  --progress=plain \
  --build-arg REGISTRY01=myregistry \
  --build-arg BRANCH=develop \
  --build-arg PROJECT=saas-apigateway \
  --build-arg PORT=8005 \
  -t myregistry/saas-apigateway:2195e0 \
  --push \
  https://***:***@bitbucket.org/myorg/saas-apigateway.git#develop

Local Build

docker buildx build \
  --builder container-builder \
  --sbom=true \
  --no-cache \
  --attest type=provenance,mode=max \
  --memory 4g \
  --cpu-period 100000 \
  --cpu-quota 200000 \
  --progress=plain \
  --build-arg REGISTRY01=myregistry \
  --build-arg BRANCH=master \
  --build-arg PROJECT=myapp \
  --build-arg PORT=8080 \
  -t myregistry/myapp:f51df9 \
  -f Dockerfile .

Teams Notification

When TEAMS_WEBHOOK is configured in .env, build notifications are sent to Microsoft Teams:

• ✅ Success notification with image details
• ❌ Failure notification with error info

Troubleshooting

Builder not found

If you get "no builder 'mybuilder' found" error:

# Create the builder
docker buildx create --name mybuilder --driver docker-container --use

Authentication issues for remote builds

Ensure ~/.netrc is configured:

machine bitbucket.org
  login your-username
  password your-app-password

Related Tools

• ngen-gitops - GitOps CLI for repository management

License

MIT