cnb-docker-mirror

CNB Docker Mirror (cdm)

cdm is a small CLI for moving public Docker images into CNB and for running a local Docker registry mirror backed by a CNB workspace.

It is designed for teams that already use CNB and want a simple, scriptable way to:

• sync upstream images into docker.cnb.cool
• start a local registry mirror without maintaining their own proxy service
• recover automatically when a CNB workspace is recycled

Features

• Sync a single image from Docker Hub, GHCR, or another registry into CNB.
• Start a local mirror endpoint and route Docker pulls through CNB.
• Reconnect automatically after the remote mirror workspace is rebuilt.
• Publish standalone binaries for Linux, macOS, and Windows.
• Keep the workflow lightweight: configure once, then use simple CLI commands.

Screenshots

Image Sync

Local Mirror

Installation

Download a release binary

Download the latest build from the repository releases page:

• GitHub Releases: https://github.com/fanyang89/cnb-docker-mirror/releases
• CNB Releases: https://cnb.cool/fandamira/cnb_docker_mirror/-/releases

Each push to main publishes a unique GitHub Release for that commit.

Typical artifact names:

• cdm-linux-amd64
• cdm-linux-arm64
• cdm-darwin-amd64
• cdm-darwin-arm64
• cdm-windows-amd64.exe
• cdm-windows-arm64.exe

After downloading:

chmod +x cdm
mv cdm /usr/local/bin/cdm

Build from source

git clone https://cnb.cool/fandamira/cnb_docker_mirror
cd cnb_docker_mirror
go build -o cdm .

Quick Start

1. Create a CNB token

Create a token at https://cnb.cool/profile/token/create and grant at least:

• repo-cnb-trigger:rw
• repo-cnb-detail:r

2. Prepare a repository

Create a public CNB repository with a main branch. cdm uses this repository to run image sync jobs and temporary mirror workspaces.

3. Save local configuration

cdm config set --token <your-token> --repo <owner/repo>

Configuration is stored locally at ~/.config/cnb-docker-mirror/config.json.

4. Sync an image

cdm image sync --source nginx

By default, cdm image sync publishes a multi-arch image for linux/amd64 and linux/arm64.

Examples:

cdm image sync --source redis:7
cdm image sync --source ghcr.io/opencontainers/distribution-spec:latest --arch both
cdm image sync --source alpine:latest --arch amd64
cdm image sync --source nginx:stable --target infra/nginx:stable

5. Start the local registry mirror

cdm image mirror

Or choose a custom local port:

cdm image mirror --port 5050

The command prints the daemon.json snippet that Docker needs in order to use the local mirror endpoint.

Commands

cdm config set     Save the CNB token and target repository
cdm image sync     Sync an upstream image into the CNB registry
cdm image mirror   Start a local CNB-backed Docker registry mirror

Run cdm <command> --help for examples and flag descriptions.

How It Works

image sync

cdm generates a temporary CNB pipeline, triggers it through the CNB API, and waits until the resulting image is pushed to docker.cnb.cool/<owner>/<repo>/.... During the wait, it prints live build progress for the remote CNB job. By default, it publishes a manifest that includes both linux/amd64 and linux/arm64, unless --arch is set to a single architecture.

image mirror

cdm starts a CNB workspace that runs registry:2 in proxy mode, obtains the workspace SSH endpoint, and forwards a local port to the remote registry. When the remote session expires, cdm recreates the workspace automatically.

Limitations

• The CNB repository should be public for the current workflow.
• Mirror sessions depend on CNB workspace availability.
• Docker must trust the local insecure registry endpoint printed by the tool.
• The tool currently focuses on CNB-hosted workflows and is not a generic registry mirroring framework.

Development

go test ./...
go vet ./...
go build ./...

Contribution guidelines live in CONTRIBUTING.md.

Related Projects

• cnb.cool VS Code extension: https://cnb.cool/xiaofei/cnb-vscode-plugin
• docker-sync for UI-first image sync workflows: https://cnb.cool/xiaofei/docker-sync

Security

• Do not commit CNB tokens.
• Rotate tokens if they are exposed.
• Report vulnerabilities according to SECURITY.md.

License

This project is released under the MIT License. See LICENSE.

Roadmap

• Better release metadata and checksums
• Additional tests around CLI flows and config handling
• More polished contributor automation under .github/