Skip to content

README.md

Latest commit

 

History

History
200 lines (162 loc) · 7.45 KB

README.md

File metadata and controls

200 lines (162 loc) · 7.45 KB
Raw

Docker Base Images

Build and Push Images Scheduled Build

Professional collection of production-ready Docker base images with a clean, declarative build system.

Overview

This repository provides curated Docker base images for various use cases, built with a focus on:

  • Security: Regular updates, security scanning, and minimal attack surface
  • Consistency: Reproducible builds with declarative configuration
  • Maintainability: Single source of truth, no duplicated logic
  • Simplicity: Easy to understand, easy to extend
  • Multi-version Support: Build matrices for multiple versions of dependencies

🏗️ Architecture

BaseImages/
├── .github/
│   └── workflows/
│       ├── build.yml           # Orchestrator: dispatches per-image builds
│       ├── build-image.yml     # Reusable: builds one image (all variants)
│       ├── scan-image.yml      # Reusable: Trivy scan for one image
│       ├── validate-image.yml  # Reusable: PR validation for one image
│       ├── pr-validate.yml     # PR orchestrator
│       └── scheduled.yml       # Scheduled orchestrator
├── scripts/
│   ├── generate-matrix.py      # Generates build matrix from config
│   ├── list-images.py          # Lists image names for orchestrators
│   ├── detect-changed-images.py # Maps file changes to images
│   └── validate-config.py      # Validates configuration
├── images/
│   ├── ml/
│   │   ├── pytorch/
│   │   │   ├── Dockerfile   # PyTorch image definition
│   │   │   ├── test.sh      # Image tests
│   │   │   └── README.md    # PyTorch image documentation
│   │   └── tensorflow/
│   │       ├── Dockerfile   # TensorFlow image definition
│   │       ├── test.sh      # Image tests
│   │       └── README.md    # TensorFlow image documentation
│   └── languages/
│       ├── python/
│       │   ├── Dockerfile   # Python image definition
│       │   ├── test.sh      # Image tests
│       │   └── README.md    # Python image documentation
│       └── golang/
│           ├── Dockerfile   # Golang image definition
│           ├── test.sh      # Image tests
│           └── README.md    # Golang image documentation
├── images.yaml              # Centralized configuration
├── CONTRIBUTING.md          # How to add or update images
└── README.md

📦 Available Images

Image Description
PyTorch Production-ready PyTorch base image with CUDA support
TensorFlow Production-ready TensorFlow base image with CUDA support
Python Lightweight Python base image for general-purpose development
Golang Lightweight Golang base image for development and production

Images are published to Docker Hub under the devopshobbies namespace (e.g. devopshobbies/pytorch). See each image's README for versions, tags, and pull instructions.

🔄 CI/CD Workflows

Build Workflow (build.yml)

Triggered on:

  • Push to main branch (builds only changed images)
  • Manual dispatch with options
  • Called by other workflows

Architecture:

  • Orchestrator (build.yml) plans which images to build from images.yaml
  • Per-image pipeline (build-image.yml) runs each image in an isolated workflow with its own runners and disk space
  • Variant builds within one image run sequentially (max-parallel: 1) to avoid disk exhaustion on large images

Features:

  • Dynamic build matrix from images.yaml
  • Multi-architecture support where configured (defaults amd64+arm64; ML images currently amd64)
  • Per-image GHA cache scopes
  • Automatic testing
  • Push to Docker Hub (devopshobbies namespace)

Note: Pushing to Docker Hub requires the repository secret DOCKERHUB_TOKEN (a Docker Hub access token) to be configured under Settings → Secrets and variables → Actions. The Docker Hub username is taken from the IMAGE_NAMESPACE workflow variable.

Scheduled Build (scheduled.yml)

Runs weekly (Sundays at 2:00 AM UTC). For each image in images.yaml:

  • Pre-build security scan (isolated runner)
  • Rebuild via build-image.yml (isolated runner)
  • Post-build security scan (isolated runner)
  • Summary report

PR Validation (pr-validate.yml)

Triggered on pull requests. Performs:

  • YAML linting
  • Dockerfile linting (hadolint)
  • Configuration validation
  • Per-image build test via validate-image.yml (isolated runner)
  • Security scanning (Trivy)

🛠️ Adding a New Image

See CONTRIBUTING.md for the full guide (directory layout, Dockerfile conventions, images.yaml registration, tests, and PR checklist).

🔧 Local Development

Build locally

# Build PyTorch image
docker build -t pytorch:local images/ml/pytorch/

# Build with specific versions
docker build \
  --build-arg CUDA_VERSION=12.4 \
  --build-arg PYTHON_VERSION=3.11 \
  --build-arg PYTORCH_VERSION=2.4 \
  -t pytorch:local images/ml/pytorch/

Run tests locally

docker run --rm pytorch:local /bin/bash -c "$(cat images/ml/pytorch/test.sh)"

Generate build matrix

pip install pyyaml
python scripts/generate-matrix.py --config images.yaml --image all
python scripts/generate-matrix.py --config images.yaml --image pytorch --defaults-only

List images / detect changes

python scripts/list-images.py --config images.yaml
python scripts/detect-changed-images.py --config images.yaml < changed-files.txt

Validate configuration

python scripts/validate-config.py --config images.yaml

📋 Configuration Reference

images.yaml Structure

settings:
  registry: docker.io
  organization: devopshobbies
  default_platforms:
    - linux/amd64
    - linux/arm64

images:
  image-name:
    path: path/to/dockerfile      # Required
    description: "Description"     # Optional
    versions:                      # Version matrix
      component1: ["v1", "v2"]
      component2: ["a", "b"]
    defaults:                      # For 'latest' tag
      component1: "v2"
      component2: "b"
    build_args:                    # Docker build args
      ARG_NAME: component1
    platforms:                     # Override default platforms
      - linux/amd64
    tags:
      pattern: "name-{component1}-{component2}"
      include_latest: true
    test:
      enabled: true
      script: "test.sh"
      timeout: 300

🔐 Security

  • Weekly rebuilds: All images are rebuilt weekly to incorporate security patches
  • Vulnerability scanning: Trivy scans on every PR and scheduled build
  • Non-root users: Images include non-root user option
  • Minimal attack surface: Only essential packages installed
  • SBOM generation: Planned (not yet implemented)

License

See LICENSE file for details.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to add or update images, then open an issue or pull request.