{"id":25649767,"url":"https://github.com/openchami/image-builder","last_synced_at":"2026-06-21T00:34:43.931Z","repository":{"id":262719263,"uuid":"888138653","full_name":"OpenCHAMI/image-builder","owner":"OpenCHAMI","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-27T18:50:23.000Z","size":190,"stargazers_count":7,"open_issues_count":17,"forks_count":9,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-02-27T22:57:32.068Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenCHAMI.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":"2024-11-13T22:05:53.000Z","updated_at":"2026-02-02T23:53:00.000Z","dependencies_parsed_at":"2025-01-20T03:27:33.714Z","dependency_job_id":"373a5378-525d-4469-920d-5ca9f48f5fa0","html_url":"https://github.com/OpenCHAMI/image-builder","commit_stats":null,"previous_names":["openchami/image-builder"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/OpenCHAMI/image-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Fimage-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Fimage-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Fimage-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Fimage-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenCHAMI","download_url":"https://codeload.github.com/OpenCHAMI/image-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Fimage-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34590214,"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-20T02:00:06.407Z","response_time":98,"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":[],"created_at":"2025-02-23T14:33:44.270Z","updated_at":"2026-06-21T00:34:43.924Z","avatar_url":"https://github.com/OpenCHAMI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# image-build\n\nA wrapper around various `buildah` commands that makes creating images in layers easier.\nThere are two supported modes at the moment, a \"base\" type layer and an \"ansible\" type layer\n\n# Running\n\nThe recommended and official way to run `image-build` is using the `ghcr.io/openchami/image-build` container (specifically using [Podman](https://podman.io)) as it avoids Python versioning/dependency troubles. Running bare-metal is not officially supported, though it is possible to do at one's own risk. Using Docker has caused issues and is not officially supported, though it is probably possible (again, at one's own risk) with some tweaking.\n\nTo build an image using the container, the config file needs to be mapped into the container, as well as the FUSE filesystem device:\n\n```\npodman run --rm \\\n  --device /dev/fuse \\\n  --userns keep-id:uid=1002,gid=1002 \\\n  -v /path/to/config.yaml:/home/builder/config.yaml \\\n  --network host \\\n  --cap-add=SYS_ADMIN \\\n  --cap-add=SETUID \\\n  --cap-add=SETGID \\\n  --security-opt seccomp=unconfined \\\n  --security-opt label=disable \\\n  --userns=keep-id \\\n  -v /opt/workdir/images/test-rocky-9.5.yaml:/home/builder/config.yaml \\\n  ghcr.io/openchami/image-build:latest \\\n  image-build --config config.yaml --log-level DEBUG\n```\n\nIf you are building EL9 images, use the `ghcr.io/openchami/image-build-el9:latest` image.\n\nIf the config.yaml pushes to S3, specify the credentials by adding `-e S3_ACCESS=\u003cs3-user\u003e` and `-e S3_SECRET=\u003cs3-password\u003e` to the command above. See [S3](#s3) below.\n\n# Building Container\n\nFrom the root of the repository:\n```\nbuildah bud -t ghcr.io/openchami/image-build:latest -f src/dockerfiles/Dockerfile .\n```\n\n# Configuration\n\n## Base Type Layer\n\nThe premise here is very simple. The `image-build` tool builds a base layer by starting a container, then using the provided package manager to install repos and packages. There is limited support for running basic commands inside the container. These settings are provided in a config file and command line options\n\nAn example config file that builds a base OS image based on Rocky 8.10:\n\n```yaml\n# Example image-build config for a base-type image.\n\n# Global image-build options for this image\noptions:\n  # Build a \"normal\" layer (as opposed to an Ansible-type layer)\n  layer_type: 'base'\n\n  # Name and tag for this image, used in publishing to OCI registries\n  # and S3 for identification.\n  name: 'rocky-base'\n  # One or more tags to publish image with. If one, value is a string.\n  # If multiple, the value is a YAML array of strings.\n  publish_tags: '8.10'\n\n  # Distribution flavor of image.\n  pkg_manager: 'dnf'\n\n  # Starting filesystem of image. 'scratch' means to start with a blank\n  # filesystem. Currently, only OCI images can be used as parents. In\n  # this example, the image is pushed to:\n  #\n  #  registry.mysite.tld/openchami/rocky-base:8.10\n  #\n  # This value can be used as the value to 'parent' if one wished to use\n  # the 'rocky-base:8.10' image as a parent.\n  parent: 'scratch'\n\n  # Publish OCI image to local podman registry. Note that if running\n  # the image-build container, this option will not be a benefit if\n  # the container is removed after running, since the container gets\n  # deleted after the build process exits.\n  #publish_local: true\n\n  # Publish OCI image to container registry. This image can be used\n  # as a parent for child images. Use this when this image should\n  # be used as a parent for subsequent images.\n  #\n  # The below config, combined with 'name' and 'publish_tags', will\n  # publish this OCI image to:\n  #\n  #  registry.mysite.tld/openchami/rocky-base:8.10\n  #\n  publish_registry: 'registry.mysite.tld/openchami'\n  registry_opts_push:\n    - '--tls-verify=false'\n\n  # Publish to S3 instance. This image be used for booting. Use this\n  # if an image is to be used for booting.\n  #\n  # The below config, combined with 'name' and 'publish_tags', will\n  # publish this SquashFS image to:\n  #\n  #  http://s3.mysite.tld/boot-images/compute/base/rocky8.10-rocky-base-8.10\n  #\n  publish_s3: 'http://s3.mysite.tld'\n  s3_prefix: 'compute/base/'\n  s3_bucket: 'boot-images'\n\n  # Flags available pertaining to OpenSCAP\n  # Install openscap-utils scap-security-guide bzip2 to image\n  #install_scap: true\n  # Run a SCAP scan using the xccdf option. Use this if a SCAP scan is desired.\n  # (Required if using)\n  # - the file path to xccdf xml - specify with the\n  #   benchmark_path key\n  # - profile selection - depends on xml specify with profile key\n  #scap_benchmark: true\n  # Run an OVAL evaluation\n  # (Required if using)\n  # - Link of URL to latest OVAL available for Linux distribution - specify\n  #   with oval_url key \n  #oval_eval: true\n\n# Package repositories to add. This example uses YUM/DNF repositories.\nrepos:\n  - alias: 'rocky-baseos'\n    url: 'http://dl.rockylinux.org/pub/rocky/8/BaseOS/x86_64/os'\n  - alias: 'rock_appstream'\n    url: 'http://dl.rockylinux.org/pub/rocky/8/AppStream/x86_64/os'\n  - alias: 'rock_powertools'\n    url: 'http://dl.rockylinux.org/pub/rocky/8/PowerTools/x86_64/os'\n  - alias: 'epel'\n    url: 'http://dl.fedoraproject.org/pub/epel/8/Everything/x86_64/'\n\n# Package groups to install, in this example YUM/DNF package groups.\npackage_groups:\n  - 'Minimal Install'\n  - 'Development Tools'\n\n# List of packages to install after repos get added. These names get passed\n# straight to the package manager.\npackages:\n  - kernel\n  - wget\n\n# List of commands to run after package management steps get run. Each\n# command gets passed to the shell, so redirection can be used. Besides\n# 'cmd', an optional 'loglevel` can be passed (e.g. 'INFO', 'DEBUG') to\n# control command verbosity. By default, it is 'INFO'.\ncmds:\n  - cmd: 'echo hello'\n# 'cmd' also supports 'buildah_extra_args' that are passed to 'buildah run'\n  - cmd: 'id user'\n    buildah_extra_args: ['--volume', '/var/lib/sss:/var/lib/sss:z']\n\n# OpenSCAP options to use with scap_benchmark or oval_eval. Each OpenSCAP \n# command gets passed to the shell. By default, the results from OpenSCAP will be saved \n# /root/ inside of the container built.\n# \n# The xccdf or Extensible Configuration Checklist Description Format, is a \n# language used to describe security checklists and benchmarks. The xml for \n# SCAP benchmarks is specific to each Linux distribution, and it is \n# typically, available via scap-security-guide package. Each xml will have profiles \n# associated with it. Available profiles can be checked with 'oscap info \u003cpath to xml\u003e \n# Not every Linux distro is going to provide a out of box ready xccdf xml it may need to \n# be customized\n# \n# The OVAL or Open Vulnerability Assessment Language is a language used to \n# standardize the representation of information about system security states. In \n# short it gives info on if packages on the image have CVEs (Common Vulnerabilities and \n# Exposures) associated with them. Not every Linux distro is going to have a OVAL \n# available for download \n#openscap:\n#  - profile: \"xccdf_org.ssgproject.content_profile_stig\"\n#  - benchmark_path: \"/usr/share/xml/scap/ssg/content/ssg-rl9-ds.xml\"\n#  - oval_url: \"\u003cRocky Linux OVAL .bz2 URL\u003e\"\n```\n\nThen you can use this config file to build a \"base\" layer (make sure the `S3_ACCESS` and `S3_SECRET` environment variables are set to the S3 credentials if being used):\n\n```\npodman run \\\n  --rm \\\n  --device /dev/fuse \\\n  -v /path/to/config.yaml:/home/builder/config.yaml:Z \\\n  -e \"S3_ACCESS=${S3_ACCESS}\" \\\n  -e \"S3_SECRET=${S3_SECRET}\" \\\n  ghcr.io/openchami/image-build \\\n  image-build --config config.yaml --log-level DEBUG\n```\n\nSee [Publishing Images](#publishing-images) below for more explanation on how `image-build` publishes images.\n\nYou can then build on top of this base os with a new config file, just point the `parent` key at the base os container image, in the above example, `registry.mysite.tld/openchami/rocky-base:8.10`.\n\n\n## Ansible Type Layer\n\nYou can also run an Ansible playbook against a buildah container. This type of layer uses the Buildah connection plugin in Ansible to treat the container as a host.\n\nConfiguration for an Ansible-type layer is largely the same as a base-type layer configuration with a few differences.\n\n```yaml\n# An Ansible-type layer only needs the global options block.\noptions:\n  # Layer type us 'ansible' instead of 'base'\n  layer_type: 'ansible'\n\n  # Ansible-specific options.\n  #\n  # 'groups' defines the Ansible groups in the passed inventory to run the\n  # playbook(s) on.\n  groups:\n    - 'img_ochami_compute'\n    - 'img_ochami'\n  #\n  # The playbook(s) to run against the image.\n  playbooks: 'playbooks/images/compute.yaml'\n  #\n  # The Ansible inventory to pass corresponding with the playbook(s).\n  inventory: 'inventory/'\n  #\n  # The numerical Ansible verbosity level:\n  #   0 (default): Displays only critical information.\n  #   1 (-v): Shows basic information like task names and results.\n  #   2 (-vv): Includes more detailed output, such as variable values.\n  #   3 (-vvv): Displays additional debugging data, such as task-level operations.\n  #   4 (-vvvv): Enables connection debugging, providing a deep dive into network communication.\n  ansible_verbosity: '3'\n\n  # Everything else is the same format as base layer.\n  name: 'ansible-layer'\n  publish_tags: '8.10'\n  parent: 'registry.mysite.tld/openchami/rocky-base:8.10'\n  publish_registry: 'registry.mysite.tld/openchami'\n  registry_opts_push:\n    - '--tls-verify=false'\n  publish_s3: 'http://s3.mysite.tld'\n  s3_prefix: 'compute/ansible/'\n  s3_bucket: 'boot-images'\n```\n\nBuild the image with:\n\n```\npodman run \\\n  --rm \\\n  --device /dev/fuse \\\n  -v /path/to/config.yaml:/home/builder/config.yaml:Z \\\n  -v /path/to/ansible/inventory/:/home/builder/inventory/:Z \\\n  -v /path/to/ansible/playbooks/:/home/builder/playbooks/:Z \\\n  -e \"S3_ACCESS=${S3_ACCESS}\" \\\n  -e \"S3_SECRET=${S3_SECRET}\" \\\n  ghcr.io/openchami/image-build \\\n  image-build --config config.yaml --log-level DEBUG\n```\n\n\u003e [!NOTE]\n\u003e In order to be able to use Ansible on the image, the parent must be set up to\n\u003e use Ansible (e.g. Ansible must be installed, etc.).\n\n# Publishing Images\n\nThe `image-build` tool can publish the image layers to a few kinds of endpoints\n\n## S3\n\nUsing the `--publish-s3 \u003cURL\u003e` flag or `publish-s3` config key will push to an S3 endpoint.\n\nCredentials for S3 can be set via environment variables. Use `S3_ACCESS` for the username and `S3_SECRET` for the password.\n\n## Registry\n\nUsing the `--publish-registry \u003cURL\u003e` flag or `publish-registry` config key will push to the passed registry base URL (not including image tag). Use `--registry-opts-push`/`registry-opts-push` to specify flags/args to pass to the `buildah push` command to push.\n\nThere is an equivalent flag/config option `--registry-opts-pull`/`registry-opts-pull` whose value is passed to the `buildah push` command to pull the parent OCI image.\n\n## Local\n\nUsing the `--publish-local` flag or `publish-local` config key will push the resulting OCI image to the local podman registry using `buildah commit`.\n\n## Image Labels and Metadata\n\nThe `image-build` tool automatically adds useful labels to images during the build process. These labels provide metadata about the image's contents and build process. You can also add custom labels through the configuration file.\n\n### Automatic Labels\n\nThe following labels are automatically added to every image:\n\n- `org.openchami.image.name`: The name of the image\n- `org.openchami.image.type`: The layer type (base/ansible)\n- `org.openchami.image.package-manager`: The package manager used (dnf/zypper)\n- `org.openchami.image.parent`: The parent image used\n- `org.openchami.image.tags`: All tags associated with the image\n- `org.openchami.image.build-date`: ISO format timestamp of when the image was built\n- `org.openchami.image.repositories`: Comma-separated list of repository aliases used\n- `org.openchami.image.packages`: Comma-separated list of packages installed\n- `org.openchami.image.package-groups`: Comma-separated list of package groups installed\n\n### Custom Labels\n\nYou can add custom labels to your images by including them in the configuration file:\n\n```yaml\noptions:\n  layer_type: 'base'\n  name: 'rocky8-base'\n  publish_tags: '8.9'\n  pkg_manager: 'dnf'\n  parent: 'scratch'\n  publish_registry: 'registry.mysite.tld/openchami'\n  \n  # Custom labels\n  labels:\n    maintainer: 'Your Name \u003cyour.email@example.com\u003e'\n    version: '1.0.0'\n    description: 'Base Rocky Linux 8 image'\n    org.opencontainers.image.source: 'https://github.com/your-org/your-repo'\n```\n\n### Viewing Labels\n\nYou can view the labels on a built image using either `buildah` or `podman`:\n\n```bash\n# Using buildah\nbuildah inspect \u003cimage-name\u003e\n\n# Using podman\npodman inspect \u003cimage-name\u003e\n```\n\nThe labels will be visible in the output under the `Labels` section. These labels are preserved when the image is pushed to a registry and can be useful for:\n- Version tracking\n- Documentation\n- Build information\n- Compliance requirements\n- Image identification and organization\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenchami%2Fimage-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenchami%2Fimage-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenchami%2Fimage-builder/lists"}