docker-image-pusher

Crates.iodocker-image-pusher
lib.rsdocker-image-pusher
version0.5.6
created_at2025-06-05 08:17:33.776966+00
updated_at2025-12-26 06:22:29.214707+00
descriptionA memory-optimized Docker image transfer tool for handling large images efficiently
homepage
repositoryhttps://github.com/yorelog/docker-image-pusher
max_upload_size
id1701248
size154,283
yorelog (yorelog)

documentation

https://github.com/yorelog/docker-image-pusher/blob/main/README.md

README

Docker Image Pusher

English | 简体中文

Build Status Crates.io Downloads License

A tiny, memory‑friendly Docker/OCI image pusher for large images and constrained hosts.

Highlights:

  • Streaming layer uploads with bounded memory
  • Chunked uploads for large layers (auto‑adapts to registry hints)
  • Clear progress reporting; resumable upload sessions
  • Works with tar archives or directly from containerd
  • Simple override: docker.io/nginx:v1 + --target gitea.corp.com/proj -> gitea.corp.com/proj/nginx:v1

📦 Install

  • Releases: download binaries from GitHub Releases

  • Crates.io: cargo install docker-image-pusher

  • From source:

    git clone https://github.com/yorelog/docker-image-pusher
cd docker-image-pusher && cargo build --release

📖 Usage

Quick Start (three commands)

  1. Login (once per registry)

    docker-image-pusher login registry.example.com --username user --password pass

    Credentials are saved under .docker-image-pusher/credentials.json and reused automatically.

  2. Save a local image to a tarball (optional)

    docker-image-pusher save nginx:latest --out ./
# produces ./nginx_latest.tar

  3. Push the tar archive

    docker-image-pusher push --tar ./nginx_latest.tar
    • Use --target to set the exact destination. If omitted, we infer from tar metadata and (optionally) --registry.
    • If the destination was confirmed previously, we auto-continue after a short pause; otherwise we prompt once.

Command Reference

Command When to use Key flags
save [IMAGE ...] Export local images to tar/portable folder --out, --root, --namespace, --digest
push --tar <TAR> Upload a docker-save tar directly to a registry -t/--target, --registry, --username/--password, --blob-chunk
push --image <IMAGE> Push directly from containerd (no tar) --root, --namespace, -t/--target, --username/--password, --blob-chunk
login <registry> Persist credentials for future pushes --username, --password

Destination overrides

  • If the tar contains docker.io/nginx:v1 and you pass --target gitea.corp.com/project1, the final destination resolves to gitea.corp.com/project1/nginx:v1 (repo/tag taken from tar).
  • If you pass a full target like --target gitea.corp.com/project1/nginx:custom, it is used as-is.
  • --registry only affects inference when --target is not provided; it forces the registry host while keeping repo/tag from tar metadata.

🧭 Scenarios

1) Push a docker-save tar to a private registry

docker-image-pusher login harbor.xxx.com --username USER --password PASS
docker-image-pusher push --tar ./app_1.0.0.tar \
    --target harbor.xxx.com/org/app:1.0.0

Notes:

  • Use --target to specify the destination (registry/org/repo:tag)
  • Use --registry harbor.xxx.com only if a host override is needed
  • --blob-chunk sets chunk size (MiB) for large layers

2) Push directly from containerd (no tar)

docker-image-pusher push \
    --root ~/.local/share/containerd \
    --namespace default \
    --image org/app:1.0.0 \
    --target harbor.xxx.com/org/app:1.0.0

Optional: export for offline delivery/audit, then push when needed:

docker-image-pusher save \
    --root ~/.local/share/containerd \
    --namespace default \
    --out ./export \
    org/app:1.0.0

Tip: First push to a new target may ask for a one‑time confirmation based on history/metadata; subsequent pushes auto‑continue.

📚 More

  • Advanced architecture: see ARCHITECTURE.md
  • Reusable OCI library: crates/oci-core/README.md

🤝 Contributing

PRs and issues welcome. Happy pushing! 🐳

Commit count: 26

cargo fmt