Container Unpack Performance Benchmark - One-line Docker deployment

README-gist.md

Container Unpack Performance Benchmark

Measures pure container image unpacking performance, isolated from download overhead.

🚀 One-Line Quick Start

curl -sL https://gist.githubusercontent.com/h4x3rotab/89374fdf8048550986f5e3b3935fa072/raw/gist-docker-compose.yml -o docker-compose.yml && docker compose up

🎯 Custom Benchmarks

# Quick Alpine test
curl -sL https://gist.githubusercontent.com/h4x3rotab/89374fdf8048550986f5e3b3935fa072/raw/gist-docker-compose.yml -o docker-compose.yml && TARGET_IMAGE=docker.io/library/alpine:latest NUM_RUNS=3 docker compose up

# Heavy TensorFlow benchmark with resource limits
curl -sL https://gist.githubusercontent.com/h4x3rotab/89374fdf8048550986f5e3b3935fa072/raw/gist-docker-compose.yml -o docker-compose.yml && TARGET_IMAGE=docker.io/tensorflow/tensorflow:latest NUM_RUNS=10 CPU_LIMIT=2.0 MEMORY_LIMIT=4g docker compose up

# Ubuntu benchmark
curl -sL https://gist.githubusercontent.com/h4x3rotab/89374fdf8048550986f5e3b3935fa072/raw/gist-docker-compose.yml -o docker-compose.yml && TARGET_IMAGE=docker.io/library/ubuntu:latest NUM_RUNS=5 docker compose up

📊 View Results

# Summary
cat results/benchmark_*.json | jq '.summary'

# Peak metrics from latest run
cat results/benchmark_$(ls -t results/ | head -1) | jq '.runs[0].peak_metrics'

# All results
ls -la results/

🔧 How It Works

1. Pre-download: Downloads image layers once to populate content store
2. Snapshot clearing: Removes unpacked filesystem layers between runs
3. Pure unpack measurement: Each run measures only extraction from content store to filesystem
4. Metrics collection: Captures CPU, Memory, Disk I/O, and Network stats during unpacking

📈 Sample Results

TensorFlow Image (580MB compressed, 1.8GB uncompressed):

• Unpack time: 15-17 seconds
• CPU usage: 240% peak (multi-core)
• Disk writes: 2.5-3.8GB during unpacking
• Memory: 200MB peak

Alpine Image (3.6MB compressed):

• Unpack time: 0.8-2.3 seconds
• CPU usage: 25% peak
• Disk writes: 7-18MB during unpacking

🐳 Architecture

• Docker-in-Docker: Containerd runs inside Docker containers for isolation
• Real-time monitoring: Live CPU/Memory/Disk I/O stats during unpacking
• JSON output: Structured results for analysis and automation
• Volume caching: Persistent storage for downloaded content across runs

🛠️ Requirements

• Docker with docker compose
• Privileged container support (for Docker-in-Docker)
• ~1GB free disk space for caching

⚙️ Environment Variables

Variable	Description	Default	Example
TARGET_IMAGE	Container image to benchmark	docker.io/tensorflow/tensorflow:latest	docker.io/library/ubuntu:22.04
NUM_RUNS	Number of benchmark iterations	5	10
CPU_LIMIT	CPU core limit (0=unlimited)	0	2.0
MEMORY_LIMIT	Memory limit (0=unlimited)	0	4g

🔗 Links

• Docker Hub: https://hub.docker.com/r/h4x3rotab/bench-unpack
• Source Code: https://github.com/user/repo (if public)

gist-docker-compose.yml

# Container Unpack Performance Benchmark
# 
# Quick start:
#   curl -O https://gist.githubusercontent.com/h4x3rotab/GIST_ID/raw/docker-compose.yml
#   docker compose up
#
# Custom benchmark:
#   TARGET_IMAGE=ubuntu:latest NUM_RUNS=10 docker compose up
#
# Resource limits:
#   CPU_LIMIT=2.0 MEMORY_LIMIT=4g docker compose up
#
# View results:
#   cat results/benchmark_*.json | jq '.summary'

services:
  benchmark:
    image: h4x3rotab/bench-unpack:latest
    container_name: unpack-benchmark
    privileged: true
    working_dir: /workspace
    deploy:
      resources:
        limits:
          cpus: '${CPU_LIMIT:-0}'
          memory: ${MEMORY_LIMIT:-0}
    volumes:
      # Mount current directory for results output only
      - ./results:/workspace/results
      # Mount Docker socket for stats collection inside container
      - /var/run/docker.sock:/var/run/docker.sock
      # Cache downloaded images to avoid re-downloading
      - containerd-cache:/var/lib/containerd
      # Mount Docker lib for Docker-in-Docker
      - /var/lib/docker:/var/lib/docker
    environment:
      - TARGET_IMAGE=${TARGET_IMAGE:-docker.io/tensorflow/tensorflow:latest}
      - NUM_RUNS=${NUM_RUNS:-5}
      - OUTPUT_DIR=/workspace/results
      - CONTAINER_NAME=unpack-benchmark
      - PYTHONUNBUFFERED=1
      - CPU_LIMIT=${CPU_LIMIT:-0}
      - MEMORY_LIMIT=${MEMORY_LIMIT:-0}
    depends_on: []

volumes:
  # Persistent cache for containerd images
  containerd-cache:
    driver: local