Skip to content

KhmerStack/kforge

BranchesTags

Repository files navigation

kforge

Personal multi-platform Docker image builder powered by BuildKit

License: MIT Go Release

About

kforge is a personal Docker image build CLI inspired by Docker Buildx, built on top of BuildKit. It works both as a standalone binary and as a Docker CLI plugin (docker kforge).

Made by: Ing Muyleang Founder: KhmerStack

Features

  • Multi-platform builds — linux/amd64, linux/arm64, and more simultaneously
  • Docker plugin mode — works as docker kforge build ... (same as docker buildx)
  • Interactive setup wizard — kforge setup guides QEMU or multi-node configuration
  • 5 progress styles — spinner, bar, banner, dots, plain (pick at runtime)
  • Declarative bake config — define targets in kforge.hcl or kforge.json
  • Flexible caching — registry, local, S3, Azure, GitHub Actions
  • Secrets — inject files without baking them into layers
  • Registry auth — reads your ~/.docker/config.json automatically
  • Builder management — create, list, switch, and remove builders

Install

Download pre-built packages from the v1.0.0 release page. Verify downloads with checksums.txt.

macOS (Apple Silicon / arm64)

tar.gz (terminal):

curl -Lo kforge.tar.gz https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_1.0.0_darwin_arm64.tar.gz
tar -xzf kforge.tar.gz
sudo mv kforge /usr/local/bin/

# Verify
kforge version

DMG installer (GUI):

curl -Lo kforge.dmg https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_v1.0.0_darwin_arm64.dmg
open kforge.dmg

macOS (Intel / amd64)

tar.gz (terminal):

curl -Lo kforge.tar.gz https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_1.0.0_darwin_amd64.tar.gz
tar -xzf kforge.tar.gz
sudo mv kforge /usr/local/bin/

# Verify
kforge version

DMG installer (GUI):

curl -Lo kforge.dmg https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_v1.0.0_darwin_amd64.dmg
open kforge.dmg

Linux (amd64)

Debian / Ubuntu (.deb):

curl -Lo kforge.deb https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_1.0.0_linux_amd64.deb
sudo dpkg -i kforge.deb

# Verify
kforge version

RHEL / Fedora / CentOS (.rpm):

curl -Lo kforge.rpm https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_1.0.0_linux_amd64.rpm
sudo rpm -i kforge.rpm

# Verify
kforge version

tar.gz (any distro):

curl -Lo kforge.tar.gz https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_1.0.0_linux_amd64.tar.gz
tar -xzf kforge.tar.gz
sudo mv kforge /usr/local/bin/

# Verify
kforge version

Linux (arm64)

Debian / Ubuntu (.deb):

curl -Lo kforge.deb https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_1.0.0_linux_arm64.deb
sudo dpkg -i kforge.deb

# Verify
kforge version

RHEL / Fedora / CentOS (.rpm):

curl -Lo kforge.rpm https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_1.0.0_linux_arm64.rpm
sudo rpm -i kforge.rpm

# Verify
kforge version

tar.gz (any distro):

curl -Lo kforge.tar.gz https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_1.0.0_linux_arm64.tar.gz
tar -xzf kforge.tar.gz
sudo mv kforge /usr/local/bin/

# Verify
kforge version

Windows (amd64)

# Download zip
curl -Lo kforge.zip https://github.com/MuyleangIng/kforge/releases/download/v1.0.0/kforge_1.0.0_windows_amd64.zip

# Extract
Expand-Archive kforge.zip -DestinationPath C:\tools\kforge

# Add C:\tools\kforge to your PATH, then verify
kforge version

Homebrew (coming soon)

# brew install kforge

Build from source

git clone https://github.com/MuyleangIng/kforge
cd kforge
go build -o kforge ./cmd/
sudo mv kforge /usr/local/bin/

Install as Docker CLI plugin

mkdir -p ~/.docker/cli-plugins
go build -o ~/.docker/cli-plugins/docker-kforge ./cmd/
chmod +x ~/.docker/cli-plugins/docker-kforge

Now use both:

kforge build ...           # standalone
docker kforge build ...    # via Docker CLI (just like docker buildx)

Progress Styles

Use --progress <style> during any build:

Style What you see
auto Spinner if TTY, plain otherwise (default)
spinner Animated spinner + colored step names + timing
bar ASCII progress bar per Dockerfile stage
banner Big ASCII banner header + streaming logs
dots Minimal pulsing dot + step name
plain Raw log output, no colors 
kforge build --progress spinner -t myapp .
kforge build --progress bar     -t myapp .
kforge build --progress banner  -t myapp .
kforge build --progress dots    -t myapp .
kforge build --progress plain   -t myapp .

Setup (Multi-platform wizard)

Run the interactive setup wizard to configure your builder:

kforge setup
# or via Docker plugin:
docker kforge setup

The wizard guides you through:

  ██╗  ██╗███████╗ ██████╗ ██████╗  ██████╗ ███████╗
  ██║ ██╔╝██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
  █████╔╝ █████╗  ██║   ██║██████╔╝██║  ███╗█████╗
  ██╔═██╗ ██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝
  ██║  ██╗██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗
  ╚═╝  ╚═╝╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝

Choose your build strategy:
  1) QEMU emulation      Build all platforms on one machine (easiest)
  2) Multiple native nodes  Use separate machines per platform (fastest)
  3) Both (recommended)  Native nodes first, QEMU as fallback
  q) Quit

Option 1 — QEMU (one machine): Installs QEMU via docker run --privileged --rm tonistiigi/binfmt --install all then creates a BuildKit builder. Best for most people.

Option 2 — Multiple native nodes: Prompts you for Docker context names per platform, then runs:

docker buildx create --use --name mybuild node-amd64
docker buildx create --append --name mybuild node-arm64

Usage

Build

# Build and load into local Docker
kforge build -t muyleangin/myapp:latest .

# Docker plugin mode (same as docker buildx!)
docker kforge build -t muyleangin/myapp:latest .

# Multi-platform push
kforge build --platform linux/amd64,linux/arm64 --push -t muyleangin/myapp:latest .

# Registry cache
kforge build \
  --cache-from type=registry,ref=muyleangin/myapp:cache \
  --cache-to   type=registry,ref=muyleangin/myapp:cache,mode=max \
  --push -t muyleangin/myapp:latest .

# Build args + target stage
kforge build --build-arg VERSION=1.2.3 --target release -t myapp:1.2.3 .

# Secrets
kforge build --secret id=mysecret,src=./token.txt -t myapp .

Bake (declarative builds)

Create a kforge.hcl file:

variable "TAG" { default = "latest" }

target "app" {
  context    = "."
  dockerfile = "Dockerfile"
  platforms  = ["linux/amd64", "linux/arm64"]
  tags       = ["muyleangin/app:${TAG}"]
  cache-from = ["type=registry,ref=muyleangin/app:cache"]
  cache-to   = ["type=registry,ref=muyleangin/app:cache,mode=max"]
  push       = true
}

group "default" {
  targets = ["app"]
}
kforge bake                              # builds "default" group
kforge bake app                          # builds specific target
kforge bake --set app.platforms=linux/arm64
TAG=1.0.0 kforge bake                    # pass variable via env
kforge bake -f ci/kforge.hcl            # custom file

Builder Management

kforge builder create --name mybuilder
kforge builder create --name remote --driver remote --endpoint tcp://buildkitd:1234
kforge builder ls
kforge builder use mybuilder
kforge builder rm mybuilder

Cache Backends

Type Example
Registry type=registry,ref=muyleangin/app:cache
Local type=local,dest=/tmp/cache
GitHub Actions type=gha
S3 type=s3,bucket=mybucket,region=us-east-1
Azure Blob type=azblob,account=myaccount,name=mycache

Secrets

kforge build --secret id=mysecret,src=/path/to/secret .

In your Dockerfile:

RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret

Project Structure

kforge/
├── cmd/main.go              # entry point (standalone + Docker plugin)
├── commands/
│   ├── build.go             # kforge build
│   ├── bake.go              # kforge bake
│   ├── builder.go           # kforge builder create/ls/use/rm
│   └── version.go           # kforge version
├── builder/builder.go       # builder config store (~/.kforge/)
├── bake/bake.go             # HCL + JSON config file parser
└── util/progress/
    └── progress.go          # 5 styled progress renderers

Made with ❤️ by Ing Muyleang · Founder of KhmerStack

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages