7.5.3. Building SIMP From Source

7.5.3.1. Getting Started

Please have your environment prepared as specified by Environment Preparation and have the necessary packages mirrored in accordance with Mirroring Packages before continuing.

All of the following items assume that you are running as build_user in the simp_build_centos8 container.

Download the CentOS/RedHat installation media:

  • Refer to release_mappings.yaml to determine the distribution ISO compatible with the version of SIMP you want to build. release_mappings.yaml is maintained the simp/simp-core repository in the build/distributions/<distribution>/<release>/<arch> directory.

7.5.3.1.1. Updating release_mappings.yaml

It is very possible the versions outlined in the release_mappings.yaml are out of date, as such you may need to download a newer version of the installation media and create a new section inside of the file. You can either modify one of the existing release versions or create an entirely new one to house the information for the new iso. We recommend simply copying one of the existing releases, renaming it, and modifying the iso section as necessary.

The size of the iso can be obtained with:

The checksum can be obtained with:

After obtaining the information necessary, ensure that the iso name is correct, modify the build command to have the correct iso name and release version, and ensure that the OS version is correct.

Note

The build process is handled by simp/rubygem-simp-rake-helpers. If you discover issues, that is where you will want to look for answers.

7.5.3.2. Generating The ISO

Clone simp-core:

git clone https://github.com/simp/simp-core
cd simp-core

Check out your desired branch of SIMP:

  • To check out a stable SIMP release, check out a tag (Recommended):

git checkout tags/6.6.0-1

  • To check out an unstable SIMP release, check out the latest master:

git checkout master

Run bundle to make sure that all of the build tools and dependencies are installed and up to date:

bundle install

Make an ISO directory, and copy in the CentOS/RHEL installation media:

mkdir ISO
cp </path/to/dvd*.iso> ISO

Next, you need to prepare your local packages for inclusion in the final ISO. This example builds off of CentOS 8, but all distributions work the same way.

Change to the target distribution directory:

cd build/distributions/CentOS/8/x86_64

You will see two directories DVD and yum_data.

7.5.3.2.1. Boot and Kickstart Customization (Optional)

The DVD directory holds information that is used to provide ISO boot options in both UEFI and BIOS boot modes. It also contains a ks directory that is used as the automated kickstart for hands-off provisioning of the initial server.

7.5.3.2.2. Package Customization

The yum_data directory is where you will modify the settings to include your own packages in the ISO.

Change to the yum_data directory:

cd yum_data

You will now see a reposync directory. Any YUM repository placed into this directory will be copied onto the final ISO using the following rules:

  1. If the reposync directory has the exact same name as a directory already on the ISO

    • Remove the ISO directory and copy in the reposync directory

  2. Otherwise

    • Add the reposync directory as a subdirectory of SimpRepos

For example, if the original ISO has the following directory structure:

/BaseOS
/AppStream

And the reposync directory contains the following repositories:

/BaseOS
/appstream
/SimpRepos/puppet

The resulting ISO will contain the following:

/BaseOS (the reposync version)
/AppStream (the ISO version)
/SimpRepos/appstream (case matters)
/SimpRepos/puppet

7.5.3.2.3. Add the Repositories from Pulp

You can now add the repositories that you mirrored in Mirroring Packages to the reposync directory.

Note

Check the kickstart files in the DVD directory to see what repositories will be used by default.

At this point, the reposync/SimpRepos directory may contain both a puppet and puppet6 directory. If you wish to use puppet version 6 by default, move the puppet directory to puppet7 and rename puppet6 to puppet.

mv reposync/puppet reposync/puppet7
mv reposync/puppet6 reposync/puppet

7.5.3.2.4. Modifying the Repositories (Optional)

At this point, you may perform the following actions:

  1. Add your own additional repositories

  2. Update repositories that do not have groups or modules present

    • Repos with groups will contain a *-comps.xml file in the repodata directory

    • Repos with modules will contain a *-modules.yaml file in the repodata directory

7.5.3.2.5. Verify the Upstream Vendor Repositories

The SIMP component build process first attempts to use an upstream YUM repository to pull down a matching build artifact. Failing that, a local copy is built for packaging. This copy is authoritative and will override anything from reposync.

The optional repos/ directory under yum_data/ holds a selection of repositories that will be used for fetching upstream SIMP RPMs from the official sources. These files should be regular YUM repository configuration files.

Once downloaded, non-SIMP files will be housed in a packages directory and the packages.yaml file will be updated to reflect the download source for auditing purposes. If you need to re-download the files, simply erase the packages and packages.yaml files.

7.5.3.2.5.1. Build the ISO

You are now ready to build the ISO!

To do so, run the following, substituting 6.6 with the expected build version from release_mappings.yaml:

cd </path/to>/simp-core
SIMP_BUILD_prompt=yes \
SIMP_BUILD_reposync_only=yes \
SIMP_BUILD_distro=CentOS,8Stream,x86_64 \
bundle exec rake build:auto[$PWD/ISO,<release_version>] #The release_version is the desired release number defined in release_mappings.yaml

Once the process completes, you should have a bootable SIMP ISO, in: build/distributions/<OS>/<rel>/<arch>/SIMP_ISO/

You can download it as follows (using CentOS 8 as an example):

podman cp simp_build_centos8:/home/build_user/simp-core/build/distributions/CentOS/8/x86_64/SIMP_ISO .

7.5.3.2.6. Rebuilding the ISO

If the ISO build fails for any reason or you simply want to re-build the ISO because you’ve made a change you need to run the following commands to clean up the previous run:

After running these commands the ISO build can be safely re-run.

7.5.3.2.6.1. Other Build Directories of Note

The following directories exist at the same level as SIMP_ISO/ and may be of use:

  • DVD_Overlay

    • The SIMP product RPMs and artifacts as a tar file. This is extracted into the ISO after all other modifications have occurred.

  • SIMP_ISO_STAGING

    • The ‘staging’ directory for the ISO. This is essentially the final ISO in ‘unpacked’ form and a useful place to look if you think something is missing or incorrect.

7.5.3.3. After You Build

You may have noticed that a development GPG key has been generated for the build.

This key is only valid for one week from generation and has been specifically generated for packages compiled specifically for your ISO build. If all of your packages were downloaded via Pulp, then there should be no packages on your ISO that need the development GPG key.

Doing this allows you to have a validly signed set of RPMs while reducing the risk that you will have invalid RPMs distributed around your infrastructure.

Note

If you need to build and sign your RPMs with your own key, you can certainly do so using the rpm --resign command.

The new development key will be placed at the root of your ISO and will be called RPM-GPG-KEY-SIMP_dev. This key can be added to your clients, or served via a web server, if you need to install from a centralized yum repository.

Please see the Red Hat Guide to Configuring Yum and Yum Repositories for additional information.