{"id":17383857,"url":"https://github.com/mcandre/tug","last_synced_at":"2025-04-15T10:09:40.053Z","repository":{"id":57658974,"uuid":"473018501","full_name":"mcandre/tug","owner":"mcandre","description":"Multi-platform Docker rescue ship","archived":false,"fork":false,"pushed_at":"2025-04-01T00:19:24.000Z","size":3996,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-15T10:08:48.552Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcandre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-23T03:06:57.000Z","updated_at":"2025-04-05T12:14:42.000Z","dependencies_parsed_at":"2023-12-27T05:29:21.104Z","dependency_job_id":"2a62e1ed-43b7-4869-a32c-16a862571add","html_url":"https://github.com/mcandre/tug","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcandre%2Ftug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcandre%2Ftug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcandre%2Ftug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcandre%2Ftug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcandre","download_url":"https://codeload.github.com/mcandre/tug/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249048738,"owners_count":21204306,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-16T07:44:00.830Z","updated_at":"2025-04-15T10:09:40.032Z","avatar_url":"https://github.com/mcandre.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tug: Multi-platform Docker rescue ship\n\n![logo](tug.png)\n\n# ABOUT\n\ntug streamlines Docker pipelines.\n\nSpend less time managing buildx images. Enjoy more time developing your core application.\n\n# EXAMPLE\n\n```console\n$ cd example\n\n$ tug -t mcandre/tug-demo\n\n$ tug -ls mcandre/tug-demo\nPlatform:  linux/386\nPlatform:  linux/amd64\nPlatform:  linux/amd64/v2\n...\n\n$ tug -t mcandre/tug-demo -load linux/amd64\n\n$ docker run --rm mcandre/tug-demo cat /banner\nHello World!\n```\n\n# MOTIVATION\n\nbuildx is hard. tug is easy.\n\nWhen 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.\n\nWe 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.\n\nYou can see more Docker gears turning, apply the `tug -debug` flag. tug respects your time, but also rewards curiosity.\n\n# DOCUMENTATION\n\nhttps://pkg.go.dev/github.com/mcandre/tug\n\n# DOWNLOAD\n\nhttps://github.com/mcandre/tug/releases\n\n# INSTALL FROM SOURCE\n\n```console\n$ go install github.com/mcandre/tug/cmd/tug@latest\n```\n\n# LICENSE\n\nBSD-2-Clause\n\n# RUNTIME REQUIREMENTS\n\n* [Docker](https://www.docker.com/) 27+\n\n## Recommended\n\n* [Docker First Aid Kit](https://github.com/mcandre/docker-first-aid-kit)\n* Apply `DOCKER_DEFAULT_PLATFORM` = `linux/amd64` environment variable\n\nRegardless of target application environment, we encourage an amd64 compatible build environment. This tends to improve build reliability.\n\nIn 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.\n\n# CONTRIBUTING\n\nFor more information on developing tug itself, see [DEVELOPMENT.md](DEVELOPMENT.md).\n\n# USAGE\n\n`tug -get-platforms` lists available platforms.\n\n`tug -ls \u003cname\u003e` lists cached buildx entries, for the given image name (format `name[:tag]`). Note that this lookup targets primarily remotely pushed images.\n\n`tug -t \u003cname\u003e` builds multi-platform images with the given image name (format `name[:tag]`). This is the essential tug build command.\n\n`tug -clean` cleans up after junk resources, including the buildx image cache and the tug buildx builder.\n\nNotable options:\n\n* `-debug` enables additional logging.\n* `-exclude-os \u003clist\u003e` rejects image operating systems from builds. The list is comma delimited.\n* `-exclude-arch \u003clist\u003e` rejects image architectures from builds. The list is comma delimited.\n* `-load \u003cos/arch\u003e` 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.\n* `-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.\n* `.` or `\u003cdirectory\u003e` are optional trailing arguments for the Docker build directory. We default to the current working directory.\n\nSee `tug -help` for more options.\n\n# FAQ\n\n## How do I get started?\n\nPractice basic, single-platform [Docker](https://www.docker.com/). As you gain confidence with Docker, you can extend this work into the realm of multi-platform images.\n\nSee the [example](example/) project, which can be built with plain `docker`, or with `docker buildx`, or with `tug`.\n\nApply the `tug -debug`... option to see more commands. Follow the basic, low level [buildx documentation](https://docs.docker.com/buildx/working-with-buildx/). For a more advanced illustration, see how the [snek](https://github.com/mcandre/snek) project builds its Docker images.\n\n## Unsupported platform?\n\nDepends 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.\n\n## tug-in-docker?\n\nRunning 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.\n\n# DOCKER HUB COMMUNITY\n\n[Docker Hub](https://hub.docker.com/) 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.\n\n# SEE ALSO\n\n* [crit](https://github.com/mcandre/crit) generates Rust ports\n* [factorio](https://github.com/mcandre/factorio) ports Go applications\n* [gox](https://github.com/mitchellh/gox), an older Go cross-compiler wrapper\n* [LLVM](https://llvm.org/) bitcode offers an abstract assembler format for C/C++ code\n* [snek](https://github.com/mcandre/snek) ports native C/C++ applications\n* [tonixxx](https://github.com/mcandre/tonixxx) ports applications of any programming language\n* [WASM](https://webassembly.org/) provides a portable interface for C/C++ code\n* [xgo](https://github.com/techknowlogick/xgo) supports Go projects with native cgo dependencies\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcandre%2Ftug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcandre%2Ftug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcandre%2Ftug/lists"}