https://github.com/yorelog/docker-image-pusher
Docker Image Pusher - a Rust CLI tool for pushing Docker image tar packages directly to registries
https://github.com/yorelog/docker-image-pusher
docker-client docker-tar harbor import-docker-image rust-crate rust-library
Last synced: 4 months ago
JSON representation
Docker Image Pusher - a Rust CLI tool for pushing Docker image tar packages directly to registries
- Host: GitHub
- URL: https://github.com/yorelog/docker-image-pusher
- Owner: yorelog
- License: mit
- Created: 2025-06-05T05:37:56.000Z (about 1 year ago)
- Default Branch: dev
- Last Pushed: 2025-12-26T06:23:49.000Z (6 months ago)
- Last Synced: 2025-12-27T13:58:33.269Z (6 months ago)
- Topics: docker-client, docker-tar, harbor, import-docker-image, rust-crate, rust-library
- Language: Rust
- Homepage:
- Size: 2.78 MB
- Stars: 19
- Watchers: 0
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Docker Image Pusher
[English](README.md) | [简体中文](README.zh-CN.md)
[](https://github.com/yorelog/docker-image-pusher/actions)
[](https://crates.io/crates/docker-image-pusher)
[](https://crates.io/crates/docker-image-pusher)
[](https://github.com/yorelog/docker-image-pusher)
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](https://github.com/yorelog/docker-image-pusher/releases)
- Crates.io: `cargo install docker-image-pusher`
- From source:
```bash
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)**
```bash
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)**
```bash
docker-image-pusher save nginx:latest --out ./
# produces ./nginx_latest.tar
```
3. **Push the tar archive**
```bash
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 ` | Upload a docker-save tar directly to a registry | `-t/--target`, `--registry`, `--username/--password`, `--blob-chunk` |
| `push --image ` | Push directly from containerd (no tar) | `--root`, `--namespace`, `-t/--target`, `--username/--password`, `--blob-chunk` |
| `login ` | 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
```bash
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)
```bash
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:
```bash
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! 🐳