AllImages - Runs a script in all of the docker images

Description πŸ“

AllImages is a Ruby-based command-line tool that automates running scripts across multiple Docker images. It provides a configuration-driven approach to testing and executing code in containerized environments, supporting both batch execution and interactive debugging.

Architecture Overview πŸ—οΈ

AllImages follows a well-defined architectural pattern with clear separation of concerns between several key components:

Core Components 🧩

Application Class (AllImages::App)

  • The central hub managing command-line interface, configuration loading, and Docker operations πŸ”„
  • Handles command processing and execution flow 🚦
  • Manages Docker image building, tagging, and cleanup πŸ”§
  • Provides environment variable handling and error reporting πŸ›‘οΈ

Configuration Manager (AllImages::Config)

  • Centralized configuration handling via YAML files πŸ“„
  • Manages default configuration generation and loading πŸ”„
  • Provides example configuration templates πŸ“‹

Component Interactions πŸ”„

graph LR
    A[AllImages::App] --> B[Configuration]
    A --> C[Docker Operations]
    A --> D[SearchUI]
    B --> E[YAML Files]
    C --> F[Docker Engine]
    D --> G[User Interface]

The AllImages::App acts as the main coordinator, loading configuration files and orchestrating Docker operations. The SearchUI enables interactive image selection, while Docker operations handle the actual container execution.

Loading Mechanism πŸ“₯

AllImages supports automatic configuration file generation when none exists:

  1. Automatic initialization when .all_images.yml is missing 🚨
  2. Configuration loading from specified YAML files πŸ“
  3. Default configuration with example content provided πŸ“‹

Command Execution Flow πŸ”„

AllImages supports multiple execution modes:

  • Batch execution: Run scripts across all configured images (run_all)
  • Selective execution: Run scripts on specific images (run <image>)
  • Interactive debugging: Debug scripts in containerized environments (debug <image>)
  • Listing: Display available images (ls)
  • Help: Show usage information (help)

Use Case: Multi-Version Ruby Testing πŸ§ͺ

AllImages is particularly useful for running tests/specs across different Ruby versions and platforms. This makes it an excellent tool for:

  • Cross-version compatibility testing - Ensuring your code works across multiple Ruby versions
  • Platform consistency verification - Testing on different operating systems and environments
  • CI/CD pipeline automation - Automating test execution across multiple environments
  • Dependency resolution testing - Verifying how your code behaves with different dependency versions

Example: Ruby Version Testing

dockerfile: |-
  RUN apk add --no-cache build-base yaml-dev openssl-dev git
  RUN gem update --system
  RUN gem install bundler gem_hadar

script: &script |-
  echo -e "\e[1m"
  ruby -v
  echo -e "\e[0m"
  bundle update --all
  bundle install --jobs=$(getconf _NPROCESSORS_ONLN)
  rake spec

fail_fast: true

images:
  ruby:3.4-alpine: *script
  ruby:3.3-alpine: *script
  ruby:3.2-alpine: *script
  ruby:3.1-alpine: *script

This configuration automatically runs your test suite across Ruby 3.4, 3.3, 3.2, and 3.1, ensuring compatibility across versions.

Installation πŸ“¦

You can install AllImages via RubyGems:

gem install all_images

Or add it to your Gemfile:

gem 'all_images'

Usage πŸ› οΈ

Basic Workflow

  1. Run all_images to generate a default .all_images.yml configuration file
  2. Customize the configuration file to define your Docker images and scripts
  3. Execute commands to run scripts across images

Command Examples πŸ“‹

# Run scripts across all configured images
all_images run_all

# Or

all_images

# Run script on a specific image
all_images run ruby:3.4-alpine

# Debug script in a specific image interactively
all_images debug ruby:3.4-alpine

# List available images
all_images ls

# Show help information
all_images help

Configuration File Structure πŸ“„

Given a configuration file like .all_images.yml:

dockerfile: |-
  RUN apk add --no-cache build-base yaml-dev openssl-dev git
  RUN gem update --system
  RUN gem install bundler gem_hadar

script: &script |-
  echo -e "\e[1m"
  ruby -v
  echo -e "\e[0m"
  bundle update --all
  bundle install --jobs=$(getconf _NPROCESSORS_ONLN)
  rake spec

fail_fast: true

images:
  ruby:3.4-alpine: *script
  ruby:3.3-alpine: *script
  ruby:3.2-alpine: *script

Environment Variables πŸ§ͺ

AllImages supports environment variable handling:

  • Configuration-defined environment variables are passed to containers
  • TERM environment variable is automatically included if present
  • Variables can be specified in the configuration file using env key

Docker Integration πŸ”§

The tool automatically:

  • Pulls base Docker images from Docker Hub
  • Builds custom Docker images with scripts
  • Runs containers with proper volume mounting
  • Cleans up containers after execution
  • Supports both interactive and non-interactive modes

Advanced Features πŸš€

Interactive Debugging πŸ› οΈ

# Start interactive session in container
all_images debug ruby:3.4-alpine

This provides a shell prompt inside the container for debugging scripts.

Failure Handling ⚠️

The fail_fast configuration option stops execution on first failure:

fail_fast: true

Searchable Image Selection 🎯

When no image is specified, AllImages provides an interactive search interface:

all_images run
# Shows searchable list of available images

Pre/Post Execution Hooks πŸ”„

AllImages supports pre/post execution hooks in your configuration:

before: |-
  echo 🏁 Preparing…
  echo Deleting Gemfile.lock
  rm -f Gemfile.lock

after: |-
  if [[ "$RESULT" = "1" ]]
  then
    echo 😡 Some tests failed!
  else
    echo πŸ₯³ All tests passed!
  fi

# ... rest of your configuration
  • before hook runs before each image execution
  • after hook runs after each image execution with RESULT environment variable
  • RESULT indicates success (0) or failure (1) of the test script
  • Hooks are non-fatal (won't stop the workflow if they fail)

Error Handling ⚠️

AllImages provides comprehensive error handling for common scenarios:

Configuration Errors πŸ“

  • Missing configuration file (automatically generates example)
  • Invalid YAML syntax in configuration files

Docker Errors πŸ”§

  • Failed Docker image pulls
  • Build failures
  • Container execution errors

Command Errors 🚨

  • Invalid command-line arguments
  • Missing required parameters

Container Cleanup

AllImages ensures proper cleanup of Docker containers even on failures:

  • Automatic removal of containers after execution
  • Temporary build directories are cleaned up automatically

Logging

The tool provides colored output for better visibility:

  • Success messages in green
  • Failure messages in red
  • Informational messages in white with blue background

Configuration βš™οΈ

Default Configuration

When no .all_images.yml file exists, AllImages generates a default configuration with example content:

dockerfile: |-
  RUN apk add --no-cache build-base yaml-dev openssl-dev git
  RUN gem update --system
  RUN gem install bundler gem_hadar

script: &script |-
  echo -e "\e[1m"
  ruby -v
  echo -e "\e[0m"
  bundle update --all
  bundle install --jobs=$(getconf _NPROCESSORS_ONLN)
  rake spec

fail_fast: true

images:
  ruby:3.4-alpine: *script
  ruby:3.3-alpine: *script
  ruby:3.2-alpine: *script

Security Considerations ⚠️

Docker Security

  • Containers run with mounted current directory for script access
  • Temporary build directories are cleaned up automatically
  • No privileged operations are performed

Script Security

  • Scripts are executed within isolated Docker containers
  • No direct access to host system (except mounted directories)
  • Container cleanup ensures no residual artifacts

Download πŸ“₯

The homepage of this library is located at

Author πŸ‘¨β€πŸ’»

Florian Frank

License πŸ“„

This software is licensed under the MIT license