Docker Image Pusher

A high-performance command-line tool written in Rust for pushing Docker image tar packages directly to Docker registries. Designed for enterprise environments and offline deployments, it efficiently handles large images (>10GB) through intelligent chunked uploads and concurrent processing.

🇨🇳 中文文档

✨ Key Features

🚀 High Performance: Multi-threaded chunked uploads with configurable concurrency
📦 Large Image Support: Optimized for images larger than 10GB with resume capability
🔐 Enterprise Security: Comprehensive authentication support including token management
🌐 Multi-Registry: Compatible with Docker Hub, Harbor, AWS ECR, Google GCR, Azure ACR
📊 Progress Tracking: Real-time upload progress with detailed feedback
🛡️ Robust Error Handling: Automatic retry mechanisms and graceful failure recovery
⚙️ Flexible Configuration: Environment variables, config files, and CLI arguments
🔄 Resume Support: Resume interrupted uploads automatically
🎯 Dry Run Mode: Validate configurations without actual uploads

🎯 Use Cases

Enterprise & Production Environments

Air-Gapped Deployments: Transfer images to internal registries without internet access
Security Compliance: Meet data sovereignty and security audit requirements
Edge Computing: Deploy to remote locations with limited connectivity
CI/CD Pipelines: Automate image transfers between development and production environments
Disaster Recovery: Backup and restore critical container images

📥 Installation

Option 1: Download Pre-built Binary

Download from GitHub Releases:

# Linux x64
curl -L -o docker-image-pusher https://github.com/yorelog/docker-image-pusher/releases/latest/download/docker-image-pusher-x86_64-unknown-linux-gnu
chmod +x docker-image-pusher

# macOS Intel
curl -L -o docker-image-pusher https://github.com/yorelog/docker-image-pusher/releases/latest/download/docker-image-pusher-x86_64-apple-darwin
chmod +x docker-image-pusher

# macOS Apple Silicon  
curl -L -o docker-image-pusher https://github.com/yorelog/docker-image-pusher/releases/latest/download/docker-image-pusher-aarch64-apple-darwin
chmod +x docker-image-pusher

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/yorelog/docker-image-pusher/releases/latest/download/docker-image-pusher-x86_64-pc-windows-msvc.exe" -OutFile "docker-image-pusher.exe"

Option 2: Install via Cargo

cargo install docker-image-pusher

Option 3: Build from Source

git clone https://github.com/yorelog/docker-image-pusher.git
cd docker-image-pusher
cargo build --release
# Binary will be at ./target/release/docker-image-pusher

🚀 Quick Start

Basic Usage

# Simple push with authentication
docker-image-pusher \
  --repository-url https://registry.example.com/project/app:v1.0 \
  --file /path/to/image.tar \
  --username myuser \
  --password mypassword

Common Workflow

# 1. Export image from Docker
docker save nginx:latest -o nginx.tar

# 2. Push to private registry
docker-image-pusher \
  -r https://harbor.company.com/library/nginx:latest \
  -f nginx.tar \
  -u admin \
  -p harbor_password \
  --verbose

📖 Command Reference

Core Arguments

Short	Long	Description	Required	Example
`-f`	`--file`	Docker image tar file path	✅	`/path/to/image.tar`
`-r`	`--repository-url`	Full repository URL	✅	`https://registry.com/app:v1.0`
`-u`	`--username`	Registry username	⚠️	`admin`
`-p`	`--password`	Registry password	⚠️	`secret123`

Configuration Options

Short	Long	Description	Default	Example
`-t`	`--timeout`	Network timeout (seconds)	`7200`	`3600`
	`--large-layer-threshold`	Large layer threshold (bytes)	`1073741824`	`2147483648`
	`--max-concurrent`	Maximum concurrent uploads	`1`	`4`
	`--retry-attempts`	Number of retry attempts	`3`	`5`

Control Flags

Long	Description	Usage
`--skip-tls`	Skip TLS certificate verification	For self-signed certificates
`--verbose`	Enable detailed output	Debugging and monitoring
`--quiet`	Suppress all output except errors	Automated scripts
`--dry-run`	Validate without uploading	Configuration testing
`--skip-existing`	Skip uploading layers that already exist	Resume interrupted uploads
`--force-upload`	Force upload even if layers exist	Overwrite existing layers

Advanced Examples

Large Image Optimization

# Optimized for 15GB PyTorch model
docker-image-pusher \
  -r https://registry.example.com/ml/pytorch:latest \
  -f pytorch-15gb.tar \
  -u ml-user \
  -p $(cat ~/.registry-password) \
  --large-layer-threshold 2147483648 \    # 2GB threshold
  --max-concurrent 4 \                   # 4 parallel uploads  
  --timeout 3600 \                       # 1 hour timeout
  --retry-attempts 5 \                   # 5 retry attempts
  --verbose

Enterprise Harbor Registry

# Production deployment to Harbor
docker-image-pusher \
  -r https://harbor.company.com/production/webapp:v2.1.0 \
  -f webapp-v2.1.0.tar \
  -u prod-deployer \
  -p $HARBOR_PASSWORD \
  --skip-tls \               # For self-signed certificates
  --max-concurrent 2 \       # Conservative for production
  --skip-existing \          # Skip layers that already exist
  --verbose

Resume Interrupted Upload

# Resume upload that was previously interrupted
docker-image-pusher \
  -r https://registry.company.com/big-app:latest \
  -f big-app.tar \
  -u deploy-user \
  -p $DEPLOY_PASSWORD \
  --skip-existing \          # Skip already uploaded layers
  --retry-attempts 5 \       # Higher retry count
  --verbose

Force Complete Re-upload

# Force complete re-upload of all layers
docker-image-pusher \
  -r https://registry.company.com/app:latest \
  -f app.tar \
  -u admin \
  -p $ADMIN_PASSWORD \
  --force-upload \           # Force upload even if layers exist
  --verbose

Batch Processing Script

#!/bin/bash
# Process multiple images with error handling
REGISTRY_BASE="https://registry.internal.com/apps"
FAILED_IMAGES=()

for tar_file in *.tar; do
  image_name=$(basename "$tar_file" .tar)
  echo "Processing $image_name..."
  
  if docker-image-pusher \
    -r "${REGISTRY_BASE}/${image_name}:latest" \
    -f "$tar_file" \
    -u "$REGISTRY_USER" \
    -p "$REGISTRY_PASS" \
    --retry-attempts 3 \
    --quiet; then
    echo "✅ Successfully pushed $image_name"
  else
    echo "❌ Failed to push $image_name"
    FAILED_IMAGES+=("$image_name")
  fi
done

# Report results
if [ ${#FAILED_IMAGES[@]} -eq 0 ]; then
  echo "🎉 All images pushed successfully!"
else
  echo "⚠️  Failed images: ${FAILED_IMAGES[*]}"
  exit 1
fi

🔧 Configuration

Environment Variables

Set credentials and defaults via environment variables:

# Authentication
export DOCKER_PUSHER_USERNAME=myuser
export DOCKER_PUSHER_PASSWORD=mypassword

# Configuration
export DOCKER_PUSHER_TIMEOUT=3600
export DOCKER_PUSHER_MAX_CONCURRENT=4
export DOCKER_PUSHER_SKIP_TLS=true
export DOCKER_PUSHER_VERBOSE=true

# Simplified command
docker-image-pusher -r https://registry.com/app:v1.0 -f app.tar

Performance Tuning

Network-Optimized Settings

# For slow/unstable networks (< 10 Mbps)
docker-image-pusher \
  -r https://registry.com/app:latest \
  -f app.tar \
  --max-concurrent 1 \       # Single connection
  --timeout 1800 \           # 30 minute timeout
  --retry-attempts 5         # More retries

High-Speed Network Settings

# For fast, stable networks (> 100 Mbps)
docker-image-pusher \
  -r https://registry.com/app:latest \
  -f app.tar \
  --max-concurrent 4 \       # Multiple connections
  --timeout 600 \            # 10 minute timeout
  --retry-attempts 2         # Fewer retries needed

🏢 Enterprise Scenarios

Financial Services - Air-Gapped Deployment

# Development environment
docker save trading-platform:v3.2.1 -o trading-platform-v3.2.1.tar

# Production environment (after secure transfer)
docker-image-pusher \
  -r https://prod-registry.bank.internal/trading/platform:v3.2.1 \
  -f trading-platform-v3.2.1.tar \
  -u prod-service \
  -p "$(vault kv get -field=password secret/registry)" \
  --skip-tls \
  --max-concurrent 2 \
  --timeout 3600 \
  --verbose

Manufacturing - Edge Computing

# Deploy to factory edge nodes with limited bandwidth
docker-image-pusher \
  -r https://edge-registry.factory.com/iot/sensor-collector:v2.0 \
  -f sensor-collector.tar \
  -u edge-admin \
  -p $EDGE_PASSWORD \
  --max-concurrent 1 \       # Single connection for stability
  --timeout 3600 \           # Extended timeout
  --retry-attempts 10        # High retry count

Healthcare - Compliance Environment

# HIPAA-compliant image deployment
docker-image-pusher \
  -r https://secure-registry.hospital.com/radiology/dicom-viewer:v1.2 \
  -f dicom-viewer.tar \
  -u $(cat /secure/credentials/username) \
  -p $(cat /secure/credentials/password) \
  --skip-tls \
  --verbose \
  --dry-run                  # Validate first

🔍 Troubleshooting

Common Issues and Solutions

Authentication Failures

# Test credentials with dry run
docker-image-pusher \
  -r https://registry.com/test/hello:v1 \
  -f hello.tar \
  -u username \
  -p password \
  --dry-run \
  --verbose

Common causes:

Expired credentials
Insufficient registry permissions
Registry-specific authentication requirements

Certificate Issues

# For self-signed certificates
docker-image-pusher \
  -r https://internal-registry.com/app:latest \
  -f app.tar \
  --skip-tls \
  --verbose

Security note: Only use --skip-tls in trusted networks.

Large File Upload Failures

# Optimized settings for large files
docker-image-pusher \
  -r https://registry.com/bigapp:latest \
  -f 20gb-image.tar \
  --large-layer-threshold 1073741824 \  # 1GB threshold
  --max-concurrent 2 \                  # Conservative concurrency
  --timeout 7200 \                      # 2 hour timeout
  --retry-attempts 5 \                  # High retry count
  --verbose

Network Timeout Issues

# For unstable networks
docker-image-pusher \
  -r https://registry.com/app:latest \
  -f app.tar \
  --timeout 1800 \           # 30 minutes
  --retry-attempts 10 \      # More retries
  --max-concurrent 1         # Single connection

Debug Information

Enable verbose logging to get detailed information:

docker-image-pusher \
  -r https://registry.com/app:latest \
  -f app.tar \
  --verbose \
  2>&1 | tee upload.log

The verbose output includes:

Layer extraction progress
Upload attempt details
Retry information
Network timing
Registry responses

📊 Performance Benchmarks

Typical Performance Metrics

Image Size	Network	Time	Concurrency	Settings
500MB	100 Mbps	45s	2	Default
2GB	100 Mbps	3m 20s	4	Optimized
10GB	1 Gbps	8m 15s	4	High-speed
25GB	100 Mbps	45m 30s	2	Large image

Optimization Tips

Concurrency: Start with 2-4 concurrent uploads
Timeouts: Set based on your network stability
Retries: Higher for unstable networks
Large Layer Threshold: Adjust based on typical layer sizes

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/yorelog/docker-image-pusher.git
cd docker-image-pusher
cargo test
cargo run -- --help

Running Tests

# Unit tests
cargo test

# Integration tests with Docker registry
cargo test --test integration -- --ignored

# Performance benchmarks
cargo test --release --test performance

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy

# Security audit
cargo audit

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

🏆 Acknowledgments

Docker Registry HTTP API V2 specification
Rust community for excellent crates
All contributors and users providing feedback

⚠️ Security Notice: Always use secure authentication methods in production. Consider using environment variables, credential files, or secure vaults instead of command-line arguments for sensitive information.

📈 Performance Tip: For optimal performance, test different concurrency settings with your specific network and registry setup.

docker-image-pusher 0.1.3