all_images 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa4d01730649fb7a048de62b9631e710aa02e7fe823ab00ca19d996405d94ace
-  data.tar.gz: e921fec235b5ffb2a7e8269619764503a5333bd67fc11847188af55ba1dbb84f
+  metadata.gz: 42e3e498acf5bf4cc5451d1a1ab60124af4dcb7acdb43685ae809250e02b15c4
+  data.tar.gz: 8703e332ac65a45e8ee31925544cc6a73463d26a62ef68ab7506303d0c71a75b
 SHA512:
-  metadata.gz: 511009dab751e51c4bd45c124e6797fba4e20eb697a1c5e859e3b62222ffcaa7a6b9131f4086c6ef470b22b557dd8487b634ebb98aa943ddf2ceb445a624e3c1
-  data.tar.gz: a54813653587cc987946acb99a1212272304c408221179aef52e30d2e9a56b030d15c932798591555be3078af1d94b6ad42b0c4efc8d889de19651526afb0a2a
+  metadata.gz: c816dd193e4843fc2e3592e9b54b12bc1073753a980723f4283338ddd15603ca500c79706b96a62f08b59f2bac79e6fb47c81add60be82deff8af2756a4aeee7
+  data.tar.gz: a9be280b27cad42406bbde54451ed44cecbdc737e2f72a7c6451a1d36535ade126d4ba9055b670d95c5cd622a36dc859f51b99f2af402d02b9047e6bf5fa5ca7

data/CHANGES.md

@@ -1,5 +1,27 @@
 # Changes
 
+## 2025-12-21 v0.10.0
+
+- Updated `rubygems_version` from **3.6.9** to **4.0.2**
+- Updated `gem_hadar` development dependency from **~> 2.7** to **~> 2.12**
+- Enhanced README.md with comprehensive documentation including architecture
+  overview, component descriptions, usage examples, installation instructions,
+  configuration details, and advanced features
+- Added detailed command examples and configuration file structure
+  documentation
+- Enhanced security considerations and error handling sections
+- Accurately documented `run_all`, `run`, `debug`, `ls`, and `help` commands
+- Documented Docker integration, environment variable handling, and interactive debugging
+- Maintained proper documentation of YAML configuration format including
+  `dockerfile`, `script`, `fail_fast`, and `images` sections
+- Preserved accurate description of `SearchUI` integration for interactive
+  image selection
+- Changed `bundle update` command to `bundle update --all` for consistent
+  dependency updates
+- Added `ruby:4.0-rc-alpine` image configuration to CI pipeline
+- Maintains existing Ruby version support for **3.4**, **3.3**, and **3.2**
+- Improves CI coverage for upcoming Ruby **4.0** release candidate
+
 ## 2025-10-09 v0.9.0
 
 - Bumped **gem_hadar** dependency from **2.4** to **2.7**

data/README.md

@@ -1,26 +1,301 @@
 # AllImages - Runs a script in all of the docker images
 
-## Description
+## Description 📝
 
-Run with
+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 🔄
+
+```mermaid
+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]
 ```
-$ all_images
+
+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
+
+```yaml
+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
 ```
 
-Configure the generated `.all_images.yml` configuration file and run it again.
+This configuration automatically runs your test suite across Ruby 3.4, 3.3,
+3.2, and 3.1, ensuring compatibility across versions.
 
-Also supports more than one configuration via
+## Installation 📦
 
+You can install AllImages via RubyGems:
+
+```bash
+gem install all_images
 ```
-$ all_images other_configuration.yml
+
+Or add it to your Gemfile:
+
+```ruby
+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 📋
+
+```bash
+# 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
 ```
 
-## Author
+### Configuration File Structure 📄
+
+Given a configuration file like `.all_images.yml`:
+
+```yaml
+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 🛠️
+
+```bash
+# 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:
+```yaml
+fail_fast: true
+```
+
+### Searchable Image Selection 🎯
+
+When no image is specified, AllImages provides an interactive search interface:
+```bash
+all_images run
+# Shows searchable list of available images
+```
+
+## 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:
+
+```yaml
+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
+
+* https://github.com/flori/all_images
+
+## Author 👨‍💻
 
-Florian Frank mailto:flori@ping.de
+[Florian Frank](mailto:flori@ping.de)
 
-## License
+## License 📄
 
-This software is licensed under the X11 (or MIT) license:
-http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3
+This software is licensed under the [MIT license](LICENSE)

data/all_images.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: all_images 0.9.0 ruby lib
+# stub: all_images 0.10.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "all_images".freeze
-  s.version = "0.9.0".freeze
+  s.version = "0.10.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -17,13 +17,13 @@ Gem::Specification.new do |s|
   s.homepage = "https://github.com/flori/all_images".freeze
   s.licenses = ["MIT".freeze]
   s.rdoc_options = ["--title".freeze, "AllImages -- Runs a script in all of the docker images".freeze, "--main".freeze, "README.md".freeze]
-  s.rubygems_version = "3.6.9".freeze
+  s.rubygems_version = "4.0.2".freeze
   s.summary = "Runs a script in all of the docker images".freeze
   s.test_files = ["spec/app_spec.rb".freeze, "spec/spec_helper.rb".freeze]
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.7".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.12".freeze])
   s.add_development_dependency(%q<rake>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<simplecov>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<rspec>.freeze, [">= 0".freeze])

data/lib/all_images/config.rb

@@ -26,7 +26,7 @@ module AllImages::Config
       echo -e "\e[1m"
       ruby -v
       echo -e "\e[0m"
-      bundle update
+      bundle update --all
       bundle install --jobs=$(getconf _NPROCESSORS_ONLN)
       rake spec
 

data/lib/all_images/version.rb

@@ -1,6 +1,6 @@
 module AllImages
   # AllImages version
-  VERSION         = '0.9.0'
+  VERSION         = '0.10.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: all_images
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.12'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -211,7 +211,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.2
 specification_version: 4
 summary: Runs a script in all of the docker images
 test_files: