Building Custom System Images with Composer

Composer is a tool for creating custom system images. The following sections describe how to install it and how to use it.

Introduction to Composer

Composer is a tool that enables users to create customized system images of CentOS. On CentOS 7.6.1810, Composer is available in the lorax-composer package.

Composer is an experimental feature in CentOS 7.6.1810.

Composer Output Formats

Composer can create these output formats:

Description CLI name file extension

QEMU QCOW2 Image

qcow2

.qcow2

Ext4 File System Image

ext4-filesystem

.img

Raw Partitioned Disk Image

partitioned-disk

.img

Live Bootable ISO

live-iso

.iso

TAR Archive

tar

.tar

Composer User Interfaces

The Composer back end runs as a system service lorax-composer. Users can interact with this service through two front ends:

  • GUI available as a Cockpit plugin. This is the preferred method.

  • CLI available as the composer-cli tool for running commands.

Composer Blueprints

In Composer, a blueprint defines a customized system image by listing packages that will be part of the system. Blueprints can be edited and they are versioned.

When a system image is created from a blueprint, the image is associated with the blueprint in Composer Cockpit interface.

Composer System Requirements

Use a virtual machine to run Composer, because the underlying lorax tool performs a number of potentially insecure and unsafe actions while creating the system images. The environment where Composer runs should meet these requirements:

Parameter Minimal Required Value

System type

A dedicated virtual machine

Processor

2 cores

Memory

4 GiB

Disk space

20 GiB

Access privileges

Administrator level (root)

SElinux

Off (permissive mode)

Network

Connectivity to Internet and to a system with repository mirrors

Apart from the virtual machine that runs Composer itself, another system is needed to provide mirrors of Red Hat content delivery network (CDN) package repositories.

Composer is an experimental feature in CentOS 7.6.1810.

Preparing a Repository Mirror for Composer

For technical reasons, Composer cannot directly use the Red Hat content delivery network (CDN). This procedure describes how to prepare a mirror of such content on a system different from the one running Composer.

Prerequisites

  • The file system containing the /var/www directory must have at least 50 GiB of free space available. To check this:

    $ df -h /var/www/
  • The system must use the same version of Red Hat Enterprise Linux as the system using Composer and be fully subscribed.

Procedure

  1. Install the tools for handling packages and repositories, and the Apache web server:

    # yum install yum-utils createrepo httpd
  2. List the repositories enabled on this machine and note their identifiers:

    # yum repolist
  3. Create local mirrors of the repositories that you want to use in Composer. For each of these repositories, run:

    # mkdir -p /var/www/html
    # reposync --gpgcheck -l --download_path=/var/www/html --repoid REPO-ID --downloadcomps --download-metadata
    $ cd /var/www/html/REPO-ID
    $ createrepo -v /var/www/html/REPO-ID -g comps.xml

    Replace REPO-ID with the identifier you noted in the previous step.

  4. Make sure that the repositories have the correct SELinux context so that the httpd Apache web server can access the repository mirrors:

    # chcon -vR -t httpd_sys_content_t /var/www/html/
  5. Enable the web server to start after each reboot, configure the system firewall, and start the server for the first time:

    # systemctl enable httpd
    # firewall-cmd --add-service=http --permanent
    # firewall-cmd --add-service=http
    # systemctl start httpd

Installing Composer

To install Composer on a dedicated virtual machine, follow these steps.

Composer is an experimental feature in CentOS 7.6.1810.

Prerequisites

  • The virtual machine for Composer must be already installed, meet the requirements, be subscribed, and be running.

  • The system with repository mirrors must be accessible on network.

  • The Composer system must use the same version of CentOS as the system containing repository mirrors.

  • You must be connected to the virtual machine and run all the commands there.

  • The repository RHEL-7-Extras must be enabled on the system.

Procedure

  1. Install the Composer packages:

    # yum install lorax-composer composer-cli cockpit-composer

    If Cockpit is not installed yet, it is implicitly installed as a dependency of the cockpit-composer package.

  2. List the repositories enabled on this machine and note their identifiers:

    # yum repolist
  3. Create a repository configuration file in the /etc/yum.repos.d directory which points to the mirrored repositories. Include the IP address or host name of the virtual machine system. For each of the repository mirrors, run:

    # cat >> /etc/yum.repos.d/mirror.repo <<EOF
    [mirror-REPO-ID]
    name=NAME
    baseurl=http://IP-ADDR/cdrom/
    enabled=1
    gpgcheck=1
    gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
    
    EOF

    Replace REPO-ID with the repository identifier, NAME with the repository name, and IP-ADDR with the IP address or host name. This will present the repository mirrors to the system with an identifier containing the prefix mirror-.

  4. Verify the repository configuration:

    # yum clean all
    # yum repolist
  5. Disable the original subscribed repositories from Red Hat content delivery network. For each of the mirrored repositories, run:

    # yum-config-manager --disable REPO-ID

    Replace REPO-ID with the repository identifier.

  6. Enable Composer to start after each reboot and configure the system firewall:

    # systemctl enable lorax-composer.socket
    # systemctl enable cockpit.socket
    # firewall-cmd --add-service=cockpit && firewall-cmd --add-service=cockpit --permanent
  7. The Composer and Cockpit services are started automatically on each system reboot. For this first session after installation, start these services manually:

    # systemctl start lorax-composer
    # systemctl start cockpit

Accessing Composer GUI in Cockpit

Using Cockpit is the recommended way of accessing Composer functionality.

Composer is an experimental feature in CentOS 7.6.1810.

Prerequisites

  • You must have root access to the system.

Procedure

  1. Open https://localhost:9090/ in a web browser on the system with Composer.

    Accessing Composer from another system falls under the topic of remote access to Cockpit. For more information, see the Getting Started with Cockpit guide.

  2. Log into the Cockpit with credentials for an user account with sufficient privileges on the system.

  3. On the left, click the Image Builder icon to display the Composer controls.

    The Composer view opens, listing existing blueprints.

Creating a Composer Blueprint

These are the steps for creating a blueprint.

Composer is an experimental feature in CentOS 7.6.1810.

Prerequisites

  • You have opened the Composer Cockpit interface in a browser.

Procedure

  1. Click Create Blueprint in the top right corner.

    A pop-up appears with fields for the blueprint name and description.

  2. Fill in the name of the blueprint and its description, then click Create.

    The screen changes to blueprint editing mode.

  3. Add components that you want to include in the system image:

    1. On the left, enter component name or a part of it into the field under the heading Available Components and press Enter.

      The search is added to the list of filters under the text entry field, and the list of components below is reduced to these that match the search.

      If the list of components is too long, add further search terms in the same way.

    2. The list of components is paged. To move to other result pages, use the arrows and entry field above the component list.

    3. Click on name of the component you intend to use to display its details. The right pane fills with details of the components, such as its version and dependencies.

    4. Select the version you want to use in the Component Options box, with the Version Release drop-down menu.

    5. Click Add in the top left.

    6. If you added a component by mistake, remove it by clicking the button at the far right of its entry in the right pane, and select Remove in the menu.

      If you do not intend to select version for some components, you can skip the component details screen and version selection by clicking the + buttons on the right side of the component list.

  4. To save the blueprint, click Commit in the top left. A dialog with a summary of the changes pops up. Click Commit.

    A small pop-up on the right informs you of the saving progress and then result.

  5. In the top left, click Back to Blueprints to exit the editing screen.

    The Composer view opens, listing existing blueprints.

Editing a Composer Blueprint

These are the steps for editing a blueprint.

Composer is an experimental feature in CentOS 7.6.1810.

Prerequisites

  • You have opened the Composer Cockpit interface in a browser.

  • A blueprint exists.

Procedure

  1. Locate the blueprint that you want to edit by entering its name or a part of it into the search box at top left, and press Enter.

    The search is added to the list of filters under the text entry field, and the list of blueprints below is reduced to these that match the search.

    If the list of blueprints is too long, add further search terms in the same way.

  2. On the left side of the blueprint, press the Edit Blueprint button that belongs to the blueprint.

    The view changes to the blueprint editing screen.

  3. Remove unwanted components by clicking their button at the far right of its entry in the right pane, and select Remove in the menu.

  4. Change version of existing components:

    1. On the left, enter component name or a part of it into the field under the heading Blueprint Components and press Enter.

      The search is added to the list of filters under the text entry field, and the list of components below is reduced to these that match the search.

      If the list of components is too long, add further search terms in the same way.

    2. Click the button at the far right of the component entry, and select Edit in the menu.

      A component details screen opens in the right pane.

    3. Select the required version in the Version Release drop-down menu and click Apply Change in top left.

      The change is saved and the right pane returns to listing the blueprint components.

  5. Add new components:

    1. On the left, enter component name or a part of it into the field under the heading Available Components and press Enter.

      The search is added to the list of filters under the text entry field, and the list of components below is reduced to these that match the search.

      If the list of components is too long, add further search terms in the same way.

    2. The list of components is paged. To move to other result pages, use the arrows and entry field above the component list.

    3. Click on name of the component you intend to use to display its details. The right pane fills with details of the components, such as its version and dependencies.

    4. Select the version you want to use in the Component Options box, with the Version Release drop-down menu.

    5. Click Add in the top left.

    6. If you added a component by mistake, remove it by clicking the button at the far right of its entry in the right pane, and select Remove in the menu.

      If you do not intend to select version for some components, you can skip the component details screen and version selection by clicking the + buttons on the right side of the component list.

  6. Commit a new version of the blueprint with your changes:

    1. Click the Commit button in top left.

      A pop-up window with a summary of your changes appears.

    2. Review your changes and confirm them by clicking Commit.

      A small pop-up on the right informs you of the saving progress and then result. A new version of the blueprint is created.

  7. In the top left, click Back to Blueprints to exit the editing screen.

    The Composer view opens, listing existing blueprints.

Creating a System Image with Composer

The following steps below describe creating a system image.

Composer is an experimental feature in CentOS 7.6.1810.

Prerequisites

  • You have opened the Composer Cockpit interface in a browser.

  • A blueprint exists.

Procedure

  1. Locate the blueprint that you want to edit by entering its name or a part of it into the search box at top left, and press Enter.

    The search is added to the list of filters under the text entry field, and the list of blueprints below is reduced to these that match the search.

    If the list of blueprints is too long, add further search terms in the same way.

  2. On the left side of the blueprint, press the Create Image button that belongs to the blueprint.

    A pop-up window appears.

  3. Select the image type and architecture and press Create.

    A small pop-up in the top left informs you that the image creation has been added to the queue.

  4. Click the name of the blueprint.

    A screen with details of the blueprint opens.

  5. Click the Images tab to switch to it.

  6. The image that is being created is listed with the status Pending.

    Image creation takes a longer time, measured in minutes. There is no indication of progress while the image is created.

    To abort image creation, press its Stop button on the right.

  7. Once the image is successfully created, the Stop button is replaced by a Download button. Click this button to download the image to your system.

Additional Resources