{"id":50819595,"url":"https://github.com/omaciel/ubi-starter","last_synced_at":"2026-06-13T12:36:38.524Z","repository":{"id":359889515,"uuid":"1247895530","full_name":"omaciel/ubi-starter","owner":"omaciel","description":"Ready-to-use RHEL 8/9/10 UBI containers with host-matched UID/GID for testing applications. No Red Hat subscription required.","archived":false,"fork":false,"pushed_at":"2026-05-24T00:48:38.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-24T01:20:12.471Z","etag":null,"topics":["containers","docker","podman","redhat","rhel","starter-kit","ubi"],"latest_commit_sha":null,"homepage":null,"language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omaciel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T23:32:40.000Z","updated_at":"2026-05-24T00:48:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/omaciel/ubi-starter","commit_stats":null,"previous_names":["omaciel/ubi-starter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/omaciel/ubi-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omaciel%2Fubi-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omaciel%2Fubi-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omaciel%2Fubi-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omaciel%2Fubi-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omaciel","download_url":"https://codeload.github.com/omaciel/ubi-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omaciel%2Fubi-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34285191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","docker","podman","redhat","rhel","starter-kit","ubi"],"created_at":"2026-06-13T12:36:37.893Z","updated_at":"2026-06-13T12:36:38.518Z","avatar_url":"https://github.com/omaciel.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ubi-starter\n\n```\n  _   _ ____ ___              .--.\n | | | | __ )_ _|            |o_o |\n | | | |  _ \\| |             |:_/ |\n | |_| | |_) | |            //   \\ \\\n  \\___/|____/___|          (|     | )\n                          /'\\_   _/`\\\n  STARTER KIT             \\___)=(___/\n```\n\n[![Build \u0026 Test](https://github.com/omaciel/ubi-starter/actions/workflows/build-test.yml/badge.svg)](https://github.com/omaciel/ubi-starter/actions/workflows/build-test.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\nA starter kit for testing applications inside Red Hat Universal Base Image (UBI) containers, with proper user permissions and volume mounting — no Red Hat subscription required.\n\n## Overview\n\n`ubi-starter` provides ready-to-use containerized environments for RHEL 8, 9, and 10 (via UBI), letting you test your applications across RHEL versions without physical systems or virtual machines. Each container includes a non-root user with matching UID/GID from your host system, ensuring proper file permissions when working with mounted volumes.\n\n## Prerequisites\n\n### Required Software\n\nYou need either **Docker** or **Podman** installed on your system:\n\n- **Docker**: [Installation instructions](https://docs.docker.com/get-docker/)\n- **Podman**: [Installation instructions](https://podman.io/getting-started/installation)\n\nThe Makefile will automatically detect which container runtime is available (preferring Docker if both are installed).\n\n### Operating System Requirements\n\nYour host system needs:\n\n- **Linux/macOS/Windows**: Any OS that supports Docker or Podman\n- **User permissions**: Ability to run container commands (may require `sudo` or being in the `docker` group on Linux)\n\n### RHEL Base Images\n\nThis starter kit uses Universal Base Images (UBI) from Red Hat, which are:\n\n- Freely redistributable\n- Available without a Red Hat subscription\n- Based on RHEL packages\n\nThe Containerfiles pin each UBI image by **content digest**, so every build of a given commit produces a bit-for-bit identical base layer:\n\n- `registry.access.redhat.com/ubi8/ubi:latest@sha256:…` (currently RHEL 8.10 — the final RHEL 8 minor)\n- `registry.access.redhat.com/ubi9/ubi:9.8@sha256:…` (currently RHEL 9.8)\n- `registry.access.redhat.com/ubi10/ubi:10.2@sha256:…` (currently RHEL 10.2)\n\n[Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates) watches these references and opens a PR whenever the digest changes — i.e. when a new minor ships **or** the same minor is rebuilt (e.g. for CVE fixes). Merging the PR is the only manual step — CI rebuilds and re-scans automatically. See [`.github/dependabot.yml`](.github/dependabot.yml).\n\n\u003e **Why `:latest` for ubi8 but pinned minors for ubi9/ubi10?** Red Hat publishes build-tagged variants of `:8.10` (e.g. `8.10-1304.1751400627`) that Dependabot's docker file-updater can't write back when combined with a digest pin. Since RHEL 8.10 is the terminal RHEL 8 minor, `:latest` is semantically equivalent to `:8.10` and avoids the bug. Reproducibility is preserved by the digest pin.\n\nThese images are pulled automatically during the build. To pre-pull them (e.g. to warm a cache):\n\n```bash\n# Using Docker\ndocker pull registry.access.redhat.com/ubi8/ubi:latest\ndocker pull registry.access.redhat.com/ubi9/ubi:9.8\ndocker pull registry.access.redhat.com/ubi10/ubi:10.2\n\n# Or using Podman\npodman pull registry.access.redhat.com/ubi8/ubi:latest\npodman pull registry.access.redhat.com/ubi9/ubi:9.8\npodman pull registry.access.redhat.com/ubi10/ubi:10.2\n```\n\n## Quick Start\n\n1. **Clone or download this repository**\n\n2. **Build a container image** (e.g., for RHEL 9):\n\n   ```bash\n   make build-rhel9\n   ```\n\n3. **Run the container**:\n\n   ```bash\n   make run-rhel9\n   ```\n\nYour current directory will be mounted inside the container at `/home/flash/data` (or `/home/\u003cUSERNAME\u003e/data` if you customized the username).\n\n## Usage\n\n### Available Make Targets\n\n**Build containers:**\n\n```bash\nmake build-rhel8    # Build RHEL 8 container\nmake build-rhel9    # Build RHEL 9 container\nmake build-rhel10   # Build RHEL 10 container\nmake build-all      # Build all RHEL containers\n```\n\n**Run containers:**\n\n```bash\nmake run-rhel8      # Run RHEL 8 container\nmake run-rhel9      # Run RHEL 9 container\nmake run-rhel10     # Run RHEL 10 container\n```\n\n**Clean up:**\n\n```bash\nmake clean-rhel8    # Remove RHEL 8 container image\nmake clean-rhel9    # Remove RHEL 9 container image\nmake clean-rhel10   # Remove RHEL 10 container image\nmake clean-all      # Remove all RHEL container images\n```\n\n**Help:**\n\n```bash\nmake help           # Show all available targets\n```\n\n### Working with Mounted Volumes\n\nWhen you run a container, your current directory is automatically mounted inside the container:\n\n- **Host path**: Your current working directory (where you ran `make`)\n- **Container path**: `/home/\u003cUSERNAME\u003e/data` (default: `/home/flash/data`)\n\n#### Example Workflow\n\n1. Place your application code in this directory\n2. Run a container:\n\n   ```bash\n   make run-rhel9\n   ```\n\n3. Inside the container, navigate to the data directory:\n\n   ```bash\n   cd ~/data\n   ```\n\n4. Test your application:\n\n   ```bash\n   # Example: Python application\n   python3 my_app.py\n\n   # Example: Compile and run C code\n   gcc -o myapp myapp.c\n   ./myapp\n\n   # Example: Node.js application\n   npm install\n   npm start\n   ```\n\nAll files created inside `/home/\u003cUSERNAME\u003e/data` will be saved to your host directory with proper permissions.\n\n## Configuration\n\n### Customizing the Username\n\nBy default, containers create a user named `flash`. To use a different username, edit the `Makefile`:\n\n```makefile\n# User configuration\nUSERNAME := your_username_here\n```\n\nOr override it when running make commands:\n\n```bash\nmake build-rhel9 USERNAME=developer\nmake run-rhel9 USERNAME=developer\n```\n\n### Customizing UID and GID\n\nThe containers automatically use your host system's UID and GID to ensure file permissions match. This happens automatically via:\n\n```makefile\nUSER_UID := $(shell id -u)\nUSER_GID := $(shell id -g)\n```\n\nTo use specific values, you can override them:\n\n```bash\nmake build-rhel9 USER_UID=1001 USER_GID=1001\n```\n\n**Important**: Rebuild the container image after changing UID/GID values.\n\n### Installing Optional Developer Tools\n\nBy default, containers include only essential packages (less, python3.12, sudo, vim, uv). You can install additional tool groups during build:\n\n#### Available Tool Groups\n\n1. **Development Tools** (`INSTALL_DEV_TOOLS=true`)\n   - git, curl, wget, tar, unzip, zip\n   - Use case: Version control and file downloads\n\n2. **Build Tools** (`INSTALL_BUILD_TOOLS=true`)\n   - gcc, gcc-c++, make, autoconf, automake, pkgconfig\n   - Use case: Compiling C/C++ applications\n\n3. **Network Tools** (`INSTALL_NET_TOOLS=true`)\n   - jq, bind-utils, iproute, net-tools\n   - Use case: Network debugging and JSON processing\n\n#### Usage Examples\n\nInstall development tools:\n\n```bash\nmake build-rhel9 INSTALL_DEV_TOOLS=true\n```\n\nInstall multiple tool groups:\n\n```bash\nmake build-rhel9 INSTALL_DEV_TOOLS=true INSTALL_BUILD_TOOLS=true\n```\n\nInstall all optional tools:\n\n```bash\nmake build-rhel9 INSTALL_DEV_TOOLS=true INSTALL_BUILD_TOOLS=true INSTALL_NET_TOOLS=true\n```\n\nSet as defaults in Makefile (lines 17-20):\n\n```makefile\nINSTALL_DEV_TOOLS ?= true\nINSTALL_BUILD_TOOLS ?= true\nINSTALL_NET_TOOLS ?= false\n```\n\n**Note**: Each tool group increases the container image size. Only install what you need.\n\n### Why UID/GID Matter\n\nMatching the container user's UID/GID with your host user prevents permission issues:\n\n- ✅ **With matching UID/GID**: Files created in the container are owned by you on the host\n- ❌ **Without matching UID/GID**: Files may be owned by root or unknown users, causing permission errors\n\n## Container Runtime Selection\n\nThe Makefile automatically detects and uses the available container runtime:\n\n1. **Docker** (preferred if available)\n2. **Podman** (fallback)\n\nTo force a specific runtime:\n\n```bash\nmake build-rhel9 CONTAINER_RUNTIME=podman\nmake run-rhel9 CONTAINER_RUNTIME=podman\n```\n\n## Project Structure\n\n```bash\n.\n├── Makefile                # Build, run, and clean targets\n├── Containerfile.rhel8    # RHEL 8 container definition\n├── Containerfile.rhel9    # RHEL 9 container definition\n├── Containerfile.rhel10   # RHEL 10 container definition\n└── README.md               # This file\n```\n\n## Common Use Cases\n\n### Testing Python Applications\n\n```bash\n# Build the container\nmake build-rhel9\n\n# Run and test your Python app\nmake run-rhel9\n\n# Inside container:\ncd ~/data\npython3 --version\npip3 install -r requirements.txt\npython3 your_app.py\n```\n\n### Testing Compiled Applications\n\n```bash\nmake run-rhel9\n\n# Inside container:\ncd ~/data\ngcc --version\ngcc -o myapp myapp.c\n./myapp\n```\n\n### Testing Across Multiple RHEL Versions\n\n```bash\n# Build all versions\nmake build-all\n\n# Test on RHEL 8\nmake run-rhel8\n# ... test your app ...\nexit\n\n# Test on RHEL 9\nmake run-rhel9\n# ... test your app ...\nexit\n\n# Test on RHEL 10\nmake run-rhel10\n# ... test your app ...\nexit\n```\n\n## Troubleshooting\n\n### Permission Denied Errors\n\nIf you get permission errors when accessing files:\n\n1. Verify your UID/GID matches:\n\n   ```bash\n   # On host\n   id\n\n   # Inside container\n   id\n   ```\n\n2. Rebuild with correct UID/GID:\n\n   ```bash\n   make clean-rhel9\n   make build-rhel9\n   ```\n\n### Container Runtime Not Found\n\nIf you see `Neither docker nor podman found in PATH`:\n\n1. Install Docker or Podman (see Prerequisites)\n2. Ensure it's in your system PATH\n3. On Linux, you may need to add your user to the docker group:\n\n   ```bash\n   sudo usermod -aG docker $USER\n   # Log out and back in\n   ```\n\n### Base Image Not Found\n\nIf build fails with image not found:\n\n1. Pull and tag the required UBI image (see Prerequisites)\n2. Verify the image exists:\n\n   ```bash\n   docker images | grep ubi\n   # or\n   podman images | grep ubi\n   ```\n\n## Advanced Usage\n\n### Installing Additional Packages\n\n**Option 1: Use built-in tool groups** (recommended):\n\n```bash\n# Enable development, build, or network tools\nmake build-rhel9 INSTALL_DEV_TOOLS=true INSTALL_BUILD_TOOLS=true\n```\n\nSee the \"Installing Optional Developer Tools\" section for available tool groups.\n\n**Option 2: Manually edit Containerfiles** (for custom packages):\n\nEdit the respective Containerfile (e.g., `Containerfile.rhel9`) to add packages:\n\n```dockerfile\nRUN dnf install -y \\\n    python3 \\\n    python3-pip \\\n    gcc \\\n    make \\\n    your-package-here \\\n    \u0026\u0026 dnf clean all\n```\n\nThen rebuild:\n\n```bash\nmake clean-rhel9\nmake build-rhel9\n```\n\n### Persisting Container Changes\n\nTo save changes made inside a container:\n\n1. Keep the container running (don't exit)\n2. In another terminal, commit the container:\n\n   ```bash\n   docker commit \u003ccontainer-id\u003e localhost/ubi9/ubi-custom:latest\n   # or\n   podman commit \u003ccontainer-id\u003e localhost/ubi9/ubi-custom:latest\n   ```\n\n### Running Without Auto-Remove\n\nThe default `make run-*` targets use `--rm` flag, which deletes the container on exit. To keep the container:\n\n```bash\ndocker run -it -v $(pwd):/home/flash/data localhost/ubi9/ubi:latest\n# or\npodman run -it -v $(pwd):/home/flash/data localhost/ubi9/ubi:latest\n```\n\n## License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.\n\n## Contributing\n\nFeel free to customize these Containerfiles and Makefile for your specific needs!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomaciel%2Fubi-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomaciel%2Fubi-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomaciel%2Fubi-starter/lists"}