just-commons/images/README.md

Container Images Module

The images module provides comprehensive container image management capabilities including building, pushing, pulling, tagging, and cleaning images with support for multi-architecture builds and flexible naming conventions.

Quick Start

# Build image with default settings
just images build

# Push with auto-generated commit tag
just images push

# Push latest (tags and pushes all architectures as latest)
just images push latest

# Show image information
just images info

# List all project images
just images list

# Clean project images
just images clean

Image Naming Logic

The module uses a flexible naming system with clear priority order:

1. Full Image Name Override (Highest Priority)

# .env
IMAGE_NAME=ghcr.io/shkafnik/nikamebel-info

When IMAGE_NAME is set, it's used exactly as specified for all operations.

2. Component-Based Naming (Default)

# .env
REGISTRY=ghcr.io
REGISTRY_NAMESPACE=shkafnik
PROJECT_NAME=nikamebel-info

Image name is built as: {REGISTRY}/{REGISTRY_NAMESPACE}/{PROJECT_NAME}:{TAG}

3. Project Name Detection Priority

1. PROJECT_NAME from .env (highest priority)
2. Auto-detection logic:
   • If single Containerfile in root → use root folder name
   • If multiple Containerfiles in subfolders → use subfolder name
   • If docker/ subfolder detected → use root folder name
3. Current folder basename (fallback)

Multi-Architecture Support

Default Behavior

• Always builds: linux/amd64 and linux/arm64
• Automatic detection: Checks Containerfile for platform specifications
• Platform override: If --platform found in Containerfile, builds only that platform

Environment Configuration

# .env - Override default platforms
DEFAULT_PLATFORMS=linux/arm64,linux/amd64

# Single platform builds
DEFAULT_PLATFORMS=linux/amd64

Platform Detection Examples

# This will build only for linux/amd64
FROM --platform=linux/amd64 alpine:latest

# This will build for default platforms (arm64 + amd64)
FROM alpine:latest

Tag Management

Default Tagging

• Regular builds: commit-{short-git-hash} (e.g., commit-a1b2c3d)
• Non-git repos: build-{timestamp} (e.g., build-20240315-143022)

Manual Tags

# Build with custom tag
just images build "" "v1.2.3"

# Push specific tag
just images push "" "v1.2.3"

Latest Tag Handling

# Special latest command - finds all existing tags and:
# 1. Tags them as 'latest'
# 2. Pushes all 'latest' images (all architectures)
just images push latest

Environment Variables

Registry Configuration

# Registry settings
REGISTRY=ghcr.io                    # Default: ghcr.io
REGISTRY_NAMESPACE=shkafnik         # Required for registry operations
GITHUB_USERNAME=shkafnik            # Fallback for REGISTRY_NAMESPACE
GITHUB_TOKEN=ghp_xxxx               # Required for private registries

# Full override (highest priority)
IMAGE_NAME=ghcr.io/custom/path      # Overrides all other naming logic

Project Configuration

# Project identification
PROJECT_NAME=nikamebel-info         # Override auto-detection

# Build configuration
DEFAULT_PLATFORMS=linux/arm64,linux/amd64  # Default platforms to build

Runtime Configuration

# Container runtime
DOCKER=podman                       # Default: docker
DOCKER_COMPOSE=podman-compose      # Default: docker compose

Commands Reference

Build Commands

# Auto-discover and build with commit tag
just images build

# Build specific project
just images build myproject

# Build with custom tag
just images build "" "v1.2.3"

# Build specific project with tag
just images build myproject "v1.2.3"

Push Commands

# Push with auto-generated tag
just images push

# Push specific tag
just images push "" "v1.2.3"

# Push latest (special handling)
just images push latest

# Push specific project
just images push myproject

Pull Commands

# Pull latest tag
just images pull

# Pull specific tag
just images pull "" "v1.2.3"

# Pull specific project
just images pull myproject "v1.2.3"

Management Commands

# Tag existing image
just images tag myproject "new-tag"

# Show image information
just images info

# List all project images
just images list

# Clean project images (with confirmation)
just images clean

# Build all projects with Containerfiles
just images build-all

Architecture Detection

The module automatically detects the build context and Containerfile location:

1. Current directory: ./Containerfile or ./Dockerfile
2. Docker subdirectory: ./docker/Containerfile or ./docker/Dockerfile
3. Project subdirectories: {project}/Containerfile or {project}/Dockerfile

Multi-Platform Build Process

For Multi-Platform Images

# Creates manifest with multiple architectures
docker buildx build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/shkafnik/nikamebel-info:commit-abc123 \
  --push .

For Single Platform Images

# Regular build for detected platform
docker build -t ghcr.io/shkafnik/nikamebel-info:commit-abc123 .

Latest Tag Workflow

When you run just images push latest:

1. Discovery: Auto-discover project name
2. Search: Find all existing images for the project
3. Tag: Tag all found images with latest
4. Push: Push all latest tagged images (all architectures)

This ensures that latest always points to your most recent build across all supported architectures.

Error Handling

Common Issues and Solutions

Missing registry credentials:

# Set in .env
REGISTRY_NAMESPACE=your-namespace
GITHUB_TOKEN=your-token

Platform build failures:

# Check buildx setup
docker buildx create --use
docker buildx inspect --bootstrap

Image not found:

# List available images
just images list

# Check project name detection
just images info

Examples

Basic Workflow

# Build and push commit-tagged image
just images build
just images push

# Later, mark as latest and push
just images push latest

Custom Project Setup

# .env configuration
PROJECT_NAME=my-custom-name
REGISTRY_NAMESPACE=myorg
DEFAULT_PLATFORMS=linux/amd64

# Build and push
just images build
just images push

Multi-Project Repository

# Build specific project
just images build frontend
just images build backend

# Build all projects
just images build-all

Integration with just-commons

This module integrates seamlessly with other just-commons modules:

• Registry module: For authentication (just registry login)
• Container module: For runtime management
• Core utilities: For project discovery and runtime detection

For complete project setup, see the main project documentation.