tug

package module
v0.0.19 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 4, 2025 License: BSD-2-Clause-Views Imports: 8 Imported by: 0

README

tug: Multi-platform Docker rescue ship

logo

ABOUT

tug streamlines Docker pipelines.

Spend less time managing buildx images. Enjoy more time developing your core application.

EXAMPLE

$ cd example

$ tug -t mcandre/tug-demo

$ tug -ls mcandre/tug-demo
Platform:  linux/386
Platform:  linux/amd64
Platform:  linux/amd64/v2
...

$ tug -t mcandre/tug-demo -load linux/amd64

$ docker run --rm mcandre/tug-demo cat /banner
Hello World!

MOTIVATION

buildx is hard. tug is easy.

When Docker introduced the buildx subsystem, their goals included making buildx operationally successful. But not necessarily as straightforward, consistent, and intuitive as single-platform docker commands. (Assuming that you consider Docker straightforward, consistent, and intuitive, ha.) We have run extensive drills on what buildx has to offer, and wrapped this into a neat little package called tug.

We are not replacing buildx, we just provide a proven workflow for high level buildx operation. We hope tug helps you to jumpstart multi-platform projects and even learn some fundamental buildx commands along the way.

You can see more Docker gears turning, apply the tug -debug flag. tug respects your time, but also rewards curiosity.

DOCUMENTATION

https://pkg.go.dev/github.com/mcandre/tug

DOWNLOAD

https://github.com/mcandre/tug/releases

INSTALL FROM SOURCE

$ go install github.com/mcandre/tug/cmd/tug@latest

LICENSE

BSD-2-Clause

RUNTIME REQUIREMENTS

  • a host capable of running musl/Linux containers (e.g. a GNU/Linux, musl/Linux, macOS, or Windows host)
  • Docker First Aid Kit
  • Apply DOCKER_DEFAULT_PLATFORM = linux/amd64 environment variable

Regardless of target application environment, we encourage an amd64 compatible build environment. This tends to improve build reliability.

In time, we may revisit this recommendation. For now, an amd64 compatible host affords better chances for successful cross-compilation than trying, for example, to build mips64 targets from s390x hosts.

CONTRIBUTING

For more information on developing tug itself, see DEVELOPMENT.md.

USAGE

tug -get-platforms lists available platforms.

tug -ls <name> lists cached buildx entries, for the given image name (format name[:tag]). Note that this lookup targets primarily remotely pushed images.

tug -t <name> builds multi-platform images with the given image name (format name[:tag]). This is the essential tug build command.

tug -clean cleans up after junk resources, including the buildx image cache and the tug buildx builder.

Notable options:

  • -debug enables additional logging.
  • -exclude-os <list> rejects image operating systems from builds. The list is comma delimited.
  • -exclude-arch <list> rejects image architectures from builds. The list is comma delimited.
  • -load <os/arch> copies an image of the given platform from the buildx cache to the local Docker registry as a side effect of the build. By default, multi-platform do not appear in the main local image cache. Mainly useful to prepare quick docker run... tests of linux/amd64 platform images.
  • -push uploads buildx cached images to the remote Docker registry, as a side effect of the build. Normally, multi-platform images cannot be pushed from the main local cache, because most platforms do not support loading into the main local cache.
  • . or <directory> are optional trailing arguments for the Docker build directory. We default to the current working directory.

See tug -help for more options.

FAQ

How do I get started?

Practice basic, single-platform Docker. As you gain confidence with Docker, you can extend this work into the realm of multi-platform images.

See the example project, which can be built with plain docker, or with docker buildx, or with tug.

Apply the tug -debug... option to see more commands. Follow the basic, low level buildx documentation. For a more advanced illustration, see how the snek project builds its Docker images.

Unsupported platform?

Depends on your particular base image. Each base image on Docker Hub, for example, is a little platform snowflake. A base image usually supports some smaller subset of the universe of platform combinations. When in doubt, grow your -exclude-arch list and retry the build.

tug-in-docker?

Running tug itself within a Docker context, such as for CI/CD, would naturally require Docker-in-Docker privileges. See the relevant documentation for your particular cluster environment, such as Kubernetes.

DOCKER HUB COMMUNITY

Docker Hub provides an exceptional variety of base images, everything from Debian to Ubuntu to RHEL to glibc to musl to uClibC. If your base image lacks support for a particular platform, try searching for alternative base images. Or, build a new base image from scratch and publish it back to Docker Hub! The more we refine our base images, the easier it is to extend and use them.

SEE ALSO

  • chandler normalizes executable archives
  • crit generates Rust ports
  • factorio ports Go applications
  • gox, an older Go cross-compiler wrapper
  • LLVM bitcode offers an abstract assembler format for C/C++ code
  • snek ports native C/C++ applications
  • tonixxx ports applications of any programming language
  • WASM provides a portable interface for C/C++ code
  • xgo supports Go projects with native cgo dependencies

Documentation

Overview

Package tug implements primitives to organize docker buildx operations.

Index

Constants

View Source 
const TugBuilderName = "tug"

TugBuilderName denotes the name of the buildx builder.

View Source 
const TugNodeName = "tug0"

TugNodeName denotes the name of the buildx node.

View Source 
const Version = "0.0.19"

Version is semver.

Variables

View Source 
var DefaultPlatformsPattern = regexp.MustCompile(`Platforms:\W+(?P<platforms>.+)$`)

DefaultPlatformsPattern denotes the pattern used to extract supported buildx platforms.

View Source 
var NichePlatforms = []Platform{
	{
		"linux",
		"mips64",
	},
}

NichePlatforms may be disabled by default.

View Source 
var PlatformPattern = regexp.MustCompile(`(?P<os>[^/]+)/(?P<arch>.+)$`)

PlatformPattern denotes the pattern used to extract operating system and architecture variants from buildx platform strings.

View Source 
var TugBuilderPattern = regexp.MustCompile(`^tug\W+`)

TugBuilderPattern denotes the pattern used to search for the tug builder within the buildx builder list.

Functions

func Clean 

func Clean(debug bool) int

Clean empties the active buildx image cache and removes the tug builder,

Returns zero on successful operation. Otherwise, returns non-zero.

func EnsureTugBuilder 

func EnsureTugBuilder(debug bool) error

EnsureTugBuilder prepares the tug buildx builder.

func RemoveBuildxImageCache 

func RemoveBuildxImageCache(debug bool) error

RemoveBuildxImageCache deletes any images/layers in the active buildx cache.

func RemoveTugBuilder 

func RemoveTugBuilder(debug bool) error

RemoveTugBuilder deletes the tug buildx builder.

Types

type Job 

type Job struct {
	// Debug can enable additional logging.
	Debug bool

	// Push can push cached buildx images to the remote Docker registry
	// as a side effect during builds.
	Push bool

	// Builder denotes a buildx builder.
	Builder string

	// LoadPlatform can load the image for a given platform
	// onto the local Docker registry as a side effect during builds.
	LoadPlatform *string

	// Platforms denotes the list of targeted image platforms.
	Platforms []Platform

	// OsExclusions skips the given operating systems.
	OsExclusions []string

	// ArchExclusions skips the given architectures.
	ArchExclusions []string

	// ListImageName can query the buildx cache
	// for any multi-platform images matching the given image name,
	// of the form name[:tag].
	ListImageName *string

	// ImageName denotes the buildx image artifact name,
	// of the form name[:tag].
	ImageName *string

	// BatchSize restricts the number of concurrent builds.
	// Zero indicates no restriction.
	BatchSize int

	// ExtraFlags sends additional command line flags to docker buildx build commands.
	ExtraFlags []string

	// Directory denotes the Docker build directory (defaults behavior assumes the current working directory).
	Directory string

	// DockerfileSource denotes the Dockerfile filename, relative to Directory. Default: Dockerfile.
	DockerfileSource string
}

Job models a Docker muliti-image build operation.

func NewJob 

func NewJob(debug bool) (*Job, error)

NewJob initializes tug and generates a default Job.

func (Job) Run 

func (o Job) Run() error

Run schedules builds.

type Platform 

type Platform struct {
	// Os denotes a buildx operating system, e.g. "linux".
	Os string

	// Arch denotes a buildx architecture, e.g. "arm64".
	Arch string
}

Platform models a targetable Docker image platform.

func AvailablePlatforms 

func AvailablePlatforms(debug bool) ([]Platform, error)

AvailablePlatforms initializes tug and reports the available buildx platforms.

func DisableNichePlatforms added in v0.0.2 

func DisableNichePlatforms(platforms []Platform) []Platform

DisableNichePlatforms filters out some exceedingly niche platforms, which may not have associated base image entries on Docker Hub.

func ParsePlatform 

func ParsePlatform(s string) (*Platform, error)

ParsePlatform extracts metadata from a buildx platform string.

func (Platform) String added in v0.0.19 

func (o Platform) String() string

Format renders a buildx platform string.

type Platforms 

type Platforms []Platform

Platforms models a slice of platform(s).

func (Platforms) Len 

func (o Platforms) Len() int

Len calculates the number of elements in a Platforms collection, in service of sorting.

func (Platforms) Less 

func (o Platforms) Less(i int, j int) bool

Less returns whether the elements a Platforms collection, identified by their indices, are in ascending order or not, in service of sorting.

func (Platforms) Swap 

func (o Platforms) Swap(i, j int)

Swap reverse the order of two elements in a Platforms collection, in service of sorting.

Source Files

View all Source files

Directories

Path Synopsis
cmd
tug command
Package main implements a CLI application to automate common docker buildx workflows.
 Package main implements a CLI application to automate common docker buildx workflows.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.