# Building AlmaLinux ISO locally

This guide walks you through the process of building AlmaLinux OS ISO on your local AlmaLinux OS 9 machine.

# Prerequisites

# System Requirements

AlmaLinux OS 9 machine
At least 6 CPU cores are recommended
8+ GB RAM
300+ GB free storage space needed for the Docker container

# Software Requirements

A basic knowledge of these tools is needed for successful building of an AlmaLinux ISO image:

Ansible
Docker

# Get Your Machine Ready

The following steps describe how to prepare your AlmaLinux 9 machine to build an ISO image.

Install Docker CE.
Clone this GitHub repository pungi-node-public (opens new window) and switch to the repository's folder to proceed with the next steps.

Install Ansible from the EPEL repository:

dnf install epel-release #enable the repository
dnf install ansible #install Ansible

# Setting Up an Ansible Inventory

Before building AlmaLinux OS ISO images, you need to configure Ansible parameters.

Navigate to the Inventory Directory: Change to the cloned repository and navigate to the inventories folder.
```
cd ~/pungi-node-public/inventories
```
Copy Sample Configuration: The inventories directory contains a sample folder with default settings. Create a copy of this folder and give it a name of your choice, for example, almalinux.
```
cp -r sample almalinux
```
Edit Inventory Settings: Switch to the newly created directory to modify the Ansible inventory.
```
cd ~/pungi-node-public/inventories/almalinux
```
WARNING

Don't forget to replace the almalinux folder name with your chosen name in the following commands and examples.
Add SSH Keys: Navigate to the inventories/almalinux/group_vars/ directory and add your public SSH key to the ssh_public_keys variable in the all.yml file.
Specify Work Directory: Change to the inventories/almalinux/host_vars directory and edit the <arch>.yml file, where <arch> is your system's architecture (e.g., x86_64.yml).

TIP

Ensure that the storage containing your work directory has at least 300 GB of free space, as it will host a local mirror with packages.

Update the work_directory_path parameter in this file to specify your work directory.
Configure Host Parameters: Return to the inventories/almalinux directory and edit the hosts.yml file to update the ansible_host and ansible_user parameters. Make sure that the specified user has passwordless sudo access.

TIP

By default, the Ansible inventory is set to build ISOs for the x86_64 architecture. In case you need to build an ISO for another architecture, make these changes:

Replace x86_64 with architecture of your choice in the names of files:
- x86_64.yml in the inventories/almalinux/group_vars directory
- x86_64.yml, x86_64-al8.yml, x86_64-al9.yml files in the inventories/almalinux/host_vars directory.
Replace mentioning of the x86_64 with architecture of your choice in the hosts.yml in the inventories/almalinux directory

# Setting Ansible to build ISOs for several architectures

By default, the Ansible inventory is set to build an ISO for one architecture. But it's also possible to build ISOs for several architectures of your choice. To do so, please, make these changes:

Make copies of the mentioned below files and rename them according to the required architecture:
- x86_64.yml in the inventories/almalinux/group_vars directory
- x86_64.yml, x86_64-al8.yml, x86_64-al9.yml files in the inventories/almalinux/host_vars directory.
Add required architecture as parameters to the hosts.yml file in the inventories/almalinux directory. Don't forget to fill in the necessary parameters.

# Setting Ansible to build an ISO for one AlmaLinux OS version

By default, the inventory is set to build ISOs for both AlmaLinux OS 8 and AlmaLinux OS 9 versions. What do we do to build for only one of them? You need to edit and comment items in several configuration files.

Go the the inventories/almalinux/group_vars/ directory and edit the all.yml file. Comment one of the sshd_ports_in_containers options accordingly to your needs:

  ---
  sshd_ports_in_containers: # lists possible AlmaLinux OS versions for building ISOs
    8: 6023 # AlmaLinux OS 8, comment this line if you don't want to build this version
    9: 6022 # AlmaLinux OS 9, comment this line if you don't want to build this version

In the same directory edit the hosts.yml file. Comment lines with AlmaLinux OS version that you don't need to build an ISO for:

 ---
 os_versions:
   - 8
   - 9
 per_version_absent_repos:
   8:
     - "crb"
   9:
     - "powertools"
 products:
   - platform: "AlmaLinux-8"
     name: "almalinux8-beta"
     version: 8
   - platform: "AlmaLinux-9"
     name: "AlmaLinux-9-beta"
     version: 9

Switch to the inventories/almalinux/hosts.yml directory and comment a docker host in the hosts.yml and its variables for the architecture you don't need. For example, if you don't want to build an AlmaLinux OS 9 ISO image for the x86_64 architecture, you should comment the x86_64-al9 host and its variables ansible_:

  all:
    children:
      hosts:
        hosts:
          x86_64:
      dockers:
        children:
          x86_64-dockers:
      x86_64:
        hosts:
          x86_64:
            ansible_host: "<IP/domain/ssh alias>"
            ansible_user: "<a host user>"
        children:
          x86_64-dockers:
            hosts:
              x86_64-al8: # comment these lines if you don't need to build ISOs for AlmaLinux OS 8
                ansible_host: "<IP/domain/ssh alias>"  # the same as a host machine
                ansible_user: "root"
                ansible_port: "{{ sshd_ports_in_containers[8] }}"
              x86_64-al9: # comment these lines if you don't need to build ISOs for AlmaLinux OS 9
                ansible_host: "<IP/domain/ssh alias>"  # the same as a host machine
                ansible_user: "root"
                ansible_port: "{{ sshd_ports_in_containers[9] }}"

# Deployment

After you set your Ansible inventory to meet your needs, deploy the Pungi node by running the following command:
```
ansible-playbook -i inventories/almalinux playbooks/build_node_in_docker.yml -vv -b
```
After the deployment it's recommended to check that you can connect successfully through SSH to each deployed Docker container.
Now you can sync RPM packages to a local mirror by running the following command:
```
systemctl start reposync.<arch>.service
```
WARNING

In the command replace the arch part with the architecture you are building an ISO for. For example, x86_64:
```
systemctl start reposync.x86_64.service
```
Please, note, that the first sync can take up to several hours.

# Building an AlmaLinux ISO

When the sync stage is completed you can proceed with building an ISO:

Clone GitHub repository pungi-scripts-public (opens new window) into the previously deployed Docker container.
Switch to the pungi-scripts-public/build_scripts directory.
To build an ISO run the following command with options that meet your needs:
```
python3.9 jenkins.py --working-root-directory <working_root_directory> --arch <arch> --product-name AlmaLinux  --distribution-major-version <major_version>  --distribution-minor-version <minor_version> --beta-suffix <beta_suffix> --sigkeys-fingerprints <fingerprint_1> <fingerprint_2> --git-auth-token <git_auth_token> --git-auth-username <git_auth_username>
```
Command options that you need to fill:
- working_root_directory - specify your work directory as you did in the very beginning in the inventories/almalinux/host_vars/x86_64.yml file
- arch - specify what architecture you are building an ISO for, for example, x86_64
- major_version and minor_version - set the numbers that match a full version of the distribution, for example in 8.9 - 8 is a major version, and 9 is a minor version
- beta_suffix - this parametr can take two values, -beta and empty string "". Please, check the pungi-almalinux (opens new window) repository as it contains branches with the same version and the same beta suffix.
- fingerprint_1 and fingerprint_2 - these parameters are fingerprints of keys that are used to sign RPM packages.
  - For AlmaLinux OS 9:B7BB94F0C9BA6CAA and D36CB86CB86B3716
  - For AlmaLinux OS 8: 51D6647EC21AD6EA and 488FCF7C3ABB34F8
- git_auth_token and git_auth_username - parameters for your auth credits that can be found at git.almalinux.org (opens new window). To generate a token go to the user settings/applications (opens new window)

TIP

Please, note, that building an AlmaLinux ISO can take up to several hours, not including the time for syncing RPM packages to a local mirror.

# Reporting issues

Should you have any issues, please report them to a corresponding project:

Setting up an Ansible inventory and deployment - pungi-node-public/issues (opens new window)
Building an AlmaLinux ISO locally - pungi-scripts-public/issues (opens new window)

← Building Packages Guide Modified packages →