# Quickstart Guide

> Get your first contribution done in 5 minutes

---

LLMS index: [llms.txt](/llms.txt) | Full content: [llms-full.txt](/llms-full.txt)

---

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

For more detailed information, see the full [contributor
documentation](https://hummingbird-project.io/l/contributing-images/).

## Prerequisites

- **Container tools**: [Podman](https://podman.io/) or [Docker](https://www.docker.com/)
- **Build tools**: `buildah`, `make`, `git`
- **Python**: Python 3.11+ with dependencies from `requirements.txt`

Install on Fedora/RHEL:

```bash
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](https://gitlab.com/redhat/hummingbird/containers/-/forks/new)
2. Clone your fork:

```bash
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

```bash
# Update dependent files
make

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

### 4. Test Your Changes

```bash
# 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](https://gitlab.com/redhat/hummingbird/containers/-/merge_requests/new)

**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](https://gitlab.com/redhat/hummingbird/containers/-/project_members?max_role=static-40) 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](LICENSE.txt) for the full license text.

## Common Tasks

### Adding a New Image

```bash
# 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

```bash
# 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

```bash
# 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

- [Development Workflow](https://hummingbird-project.io/l/development-workflow) - Detailed
  development environment and workflow
- [Adding Images](https://hummingbird-project.io/l/adding-images) - Step-by-step guide for adding
  new container images
- [Testing](https://hummingbird-project.io/l/testing-images) - How to run and write tests locally

## Getting Help

- **Documentation**: [hummingbird-project.io/l/contributing-images/](https://hummingbird-project.io/l/contributing-images/)
- **Code**: [gitlab.com/redhat/hummingbird](https://gitlab.com/redhat/hummingbird)