Quickstart Guide

Get your first contribution done in 5 minutes

Welcome! This guide will help you make your first contribution to Project Hummingbird container images.

For more detailed information, see the full contributor documentation.

Prerequisites

  • Container tools: Podman or Docker
  • Build tools: buildah, make, git
  • Python: Python 3.11+ with dependencies from requirements.txt

Install on Fedora/RHEL:

sudo dnf install podman buildah make git python3 python3-pip
pip install -r requirements.txt

Quick Start Workflow

1. Fork and Clone

  1. Fork the repository on GitLab
  2. Clone your fork:
git clone --recurse-submodules https://gitlab.com/<your-username>/containers.git
cd containers
git remote add upstream https://gitlab.com/redhat/hummingbird/containers.git

2. Make Your Changes

Edit files in the images/<image-name>/ directory:

  • properties.yml - Image configuration
  • Containerfile.j2 - Container build template
  • tests-container.yml - Integration tests

3. Generate and Build

# Update dependent files
make

# Build the image
ci/build_images.sh <image-name>

4. Test Your Changes

# Run integration tests
ci/run_tests_container.sh <image-name>

# Run linters and checks
make check

5. Submit a Merge Request

  1. Create a branch: git checkout -b fix-nginx-config
  2. Commit your changes: git commit -am "Fix nginx configuration"
  3. Push to your fork: git push origin fix-nginx-config
  4. Open a merge request from your fork to the upstream repository on GitLab

Note for external contributors: If you’re not a project member, the CI pipeline won’t run automatically. Please ping one of the project maintainers in your merge request to trigger the build and test pipeline.

License

By contributing to this project, you agree that your contributions will be licensed under the MIT License. See LICENSE.txt for the full license text.

Common Tasks

Adding a New Image

# Create image directory
mkdir images/myapp

# Copy templates
cp images/Containerfile.j2 images/myapp/Containerfile.j2
cp images/properties.yml images/myapp/properties.yml

# Edit the template, configuration, and tests
vim images/myapp/properties.yml        # Configure packages and variants
vim images/myapp/Containerfile.j2      # Customize the build template
vim images/myapp/tests-container.yml   # Add integration tests

# Update dependent files
make

# Build and test
ci/build_images.sh myapp
ci/run_tests_container.sh myapp

Testing with Docker

# Automatic Docker-in-Docker setup
ci/build_images.sh --engine docker --setup <image-name>
ci/run_tests_container.sh --engine docker --setup <image-name>

Building Specific Variants

# Build only the rawhide builder variant
ci/build_images.sh nginx/rawhide/builder

# Test only the rawhide default variant
ci/run_tests_container.sh nginx/rawhide/default

# Build/test all variants for a specific distro
ci/build_images.sh nginx/rawhide
ci/run_tests_container.sh nginx/rawhide

Next Steps

Getting Help