Chapter 4. Adding software to a running UBI container

UBI images are built from Red Hat content. These UBI images also provide a subset of Red Hat Enterprise Linux packages that are freely available to install for use with UBI. To add or update software, UBI images are pre-configured to point to the freely available yum repositories that hold official Red Hat RPMs.

To add packages from UBI repos to running UBI containers:

  • On ubi images, the yum command is installed to let you draw packages.
  • On ubi-minimal images, the microdnf command (with a smaller feature set) is included instead of yum.

Keep in mind that installing and working with software packages directly in running containers is just for adding packages temporarily or learning about the repositories. Refer to the "Build a UBI-based image" for more permanent ways of building UBI-based images.

Here are a few issues to consider when working with UBI images:

  • Hundreds of RPM packages used in existing Application streams runtime images are stored in the yum repositories packaged with the new UBI images. Feel free to install those RPMs on your UBI images to emulate the runtime (python, php, nodejs, etc.) that interests you.
  • Because some language files and documentation have been stripped out of the minimal UBI image (ubi8/ubi-minimal), running rpm -Va inside that container will show the contents of many packages as being missing or modified. If having a complete list of files inside that container is important to you, consider using a tool such as Tripwire to record the files in the container and check it later.
  • After a layered image has been created, use podman history to check which UBI image it was built on. For example, after completing the webserver example shown earlier, type podman history johndoe/webserver to see that the image it was built on includes the image ID of the UBI image you added on the FROM line of the Dockerfile.

When you add software to a UBI container, procedures differ for updating UBI images on a subscribed RHEL host or on an unsubscribed (or non-RHEL) system. Those two ways of working with UBI images are illustrated below.

4.1. Adding software to a UBI container on subscribed host

If you are running a UBI container on a registered and subscribed RHEL host, the main RHEL Server repository is enabled inside the standard UBI container, along with all the UBI repositories. So the full set of Red Hat packages is available. From the UBI minimal container, all UBI repositories are enabled by default, but no repositories are enabled from the host by default.

4.2. Adding software inside the standard UBI container

To ensure the containers you build can be redistributed, disable non-UBI yum repositories in the standard UBI image when you add software. If you disable all yum repositories except for UBI repositories, only packages from the freely available repositories are used when you add software.

With a shell open inside a standard UBI base image container (ubi8/ubi) from a subscribed RHEL host, run the following command to add a package to that container (for example, the bzip2 package):

# yum install --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos bzip2

To add software inside a standard UBI container that is in the RHEL server repository, but not in UBI repositories, do not disable any repositories and just install the package:

# yum install zsh

To install a package that is in a different host repository from inside the standard UBI container, you have to explicitly enable the repository you need. For example:

# yum install --enablerepo=rhel-7-server-optional-rpms zsh-html

Installing Red Hat packages that are not inside the Red Hat UBI repos might limit how widely you can distribute the container outside of subscribed hosts.

4.3. Adding software inside the minimal UBI container

UBI yum repositories are enabled inside the UBI minimal image by default.

To install the same package demonstrated earlier (bzip2) from one of those UBI yum repositories on a subscribed RHEL host from the UBI minimal container, type:

# microdnf install bzip2

To install packages inside a minimal UBI container from repositories available on a subscribed host that are not part of a UBI yum repository, you would have to explicitly enable those repositories. For example:

# microdnf install --enablerepo=rhel-7-server-rpms zsh
# microdnf install --enablerepo=rhel-7-server-rpms \
        --enablerepo=rhel-7-server-optional-rpms zsh-html

Using non-UBI RHEL repositories to install packages in your UBI images could restrict your ability to share those images to run outside of subscribed RHEL systems.

4.4. Adding software to a UBI container on unsubscribed host

To add software packages to a running container that is either on an unsubscribed RHEL host or some other Linux system, you do not have to disable any yum repositories. For example:

# yum install bzip2

To install that package on an unsubscribed RHEL host from the UBI minimal container, type:

# microdnf install bzip2

As noted earlier, both of these means of adding software to a running UBI container are not intended for creating permanent UBI-based container images. For that, you should build new layers on to UBI images, as described in the following section.

4.5. Building an UBI-based image

You can build UBI-based container images in the same way you build other images, with one exception. You should disable all non-UBI yum repositories when you actually build the images, if you want to be sure that your image only contains Red Hat software that you can redistribute.

Here is an example of creating a UBI-based Web server container from a Dockerfile with the buildah utility:


For ubi8/ubi-minimal images, use microdnf instead of yum below:

RUN microdnf update -y && rm -rf /var/cache/yum
RUN microdnf install httpd -y && microdnf clean all
  1. Create a Dockerfile: Add a Dockerfile with the following contents to a new directory:

    USER root
    LABEL maintainer="John Doe"
    # Update image
    RUN yum update --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos -y && rm -rf /var/cache/yum
    RUN yum install --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos httpd -y && rm -rf /var/cache/yum
    # Add default Web page and expose port
    RUN echo "The Web Server is Running" > /var/www/html/index.html
    EXPOSE 80
    # Start the service
    CMD ["-D", "FOREGROUND"]
    ENTRYPOINT ["/usr/sbin/httpd"]
  2. Build the new image: While in that directory, use buildah to create a new UBI layered image:

    # buildah bud -t johndoe/webserver .
    STEP 1: FROM
    STEP 2: USER root
    STEP 3: LABEL maintainer="John Doe"
    STEP 4: RUN yum update --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos -y
    . . .
    No packages marked for update
    STEP 5: RUN yum install --disablerepo=* --enablerepo=ubi-8-appstream --enablerepo=ubi-8-baseos httpd -y
    Loaded plugins: ovl, product-id, search-disabled-repos
    Resolving Dependencies
    --> Running transaction check
     Package                  Arch               Version                        Repository                    Size
     httpd              x86_64 2.4.37-10
                                                  latest-rhubi-8.0-appstream 1.4 M
    Installing dependencies:
     apr                x86_64 1.6.3-9.el8        latest-rhubi-8.0-appstream 125 k
     apr-util           x86_64 1.6.1-6.el8        latest-rhubi-8.0-appstream 105 k
     httpd-filesystem   noarch 2.4.37-10
                                                  latest-rhubi-8.0-appstream  34 k
     httpd-tools        x86_64 2.4.37-10.
    Transaction Summary
    STEP 6: RUN echo "The Web Server is Running" > /var/www/html/index.html
    STEP 7: EXPOSE 80
    STEP 8: CMD ["-D", "FOREGROUND"]
    STEP 9: ENTRYPOINT ["/usr/sbin/httpd"]
    Writing manifest to image destination
    Storing signatures
    --> 36a604cc0dd3657b46f8762d7ef69873f65e16343b54c63096e636c80f0d68c7
  3. Test: Test the UBI layered webserver image:

    # podman run -d -p 80:80 johndoe/webserver
    # curl http://localhost/index.html
    The Web Server is Running

4.6. Using Application Stream runtime images

Red Hat Enterprise Linux 8 Application Stream offers another set of container images that you can use as the basis for your container builds. These images are built on RHEL standard base images, with most already updated as UBI images. Each of these images include additional software you might want to use for specific runtime environments.

If you expect to build multiple images that require, for example, php runtime software, you can use provide a more consistent platform for those images by starting with a PHP Application Stream image.

Here are a few examples of Application Stream container images built on UBI base images, that are available from the Red Hat Registry ( or

  • ubi8/php-72: PHP 7.2 platform for building and running applications
  • ubi8/nodejs-10: Node.js 10 platform for building and running applications. Used by Node.js 10 Source-To-Image builds
  • ubi8/ruby25: Ruby 2.5 platform for building and running applications
  • ubi8/python-27: Python 2.7 platform for building and running applications
  • ubi8/python-36: Python 3.6 platform for building and running applications
  • ubi8/s2i-core: Base image with essential libraries and tools used as a base for builder images like perl, python, ruby, and so on
  • ubi8/s2i-base: Base image for Source-to-Image builds

Because these UBI images contain the same basic software as their legacy image counterparts, you can learn about those images from the Using Red Hat Software Collections Container Images guide. Be sure to use the UBI image names to pull those images.

RHEL 8 Application Stream container images are updated every time RHEL 8 base images are updated. For RHEL 7, these same images (referred to as Red Hat Software Collections images) are updated on a schedule that is separate from RHEL base image updates (as are related images for Dotnet and DevTools). Search the Red Hat Container Catalog for details on any of these images. For more information on update schedules, see Red Hat Container Image Updates.

4.7. Getting UBI container image source code

Source code is available for all Red Hat UBI-based images in the form of downloadable containers. Before continuing, be aware about Red Hat source containers:

  • Source container images cannot be run, despite being packaged as containers. To install Red Hat source container images on your system, use the skopeo command, instead of using podman pull command.

    • Use skopeo copy command to copy a source container image to a directory on your local system.
    • Use skopeo inspect command to inspect the source container image.
  • For more details on skopeo command, see Section 1.5. Using skopeo to work with container registries.
  • Source container images are named based on the binary containers they represent. For example, for a particular standard RHEL UBI 8 container append -source to get the source container image (
  • Once a source container image is copied to a local directory, you can use a combination of tar, gzip, and rpm commands to work with that content.
  • It could take several hours after a container image is released for its associated source container to become available.


  1. Use skopeo copy command to copy the source container image to a local directory:

    $ skopeo copy \
    docker:// \
    Copying blob 477bc8106765 done
    Copying blob c438818481d3 done
    Copying blob 26fe858c966c done
    Copying blob ba4b5f020b99 done
    Copying blob f7d970ccd456 done
    Copying blob ade06f94b556 done
    Copying blob cc56c782b513 done
    Copying blob dcf9396fdada done
    Copying blob feb6d2ae2524 done
    Copying config dd4cd669a4 done
    Writing manifest to image destination
    Storing signatures
  2. Use skopeo inspect command to inspect the source container image:

    $ skopeo inspect dir:$HOME/TEST
        "Digest": "sha256:7ab721ef3305271bbb629a6db065c59bbeb87bc53e7cbf88e2953a1217ba7322",
        "RepoTags": [],
        "Created": "2020-02-11T12:14:18.612461174Z",
        "DockerVersion": "",
        "Labels": null,
        "Architecture": "amd64",
        "Os": "linux",
        "Layers": [
        "Env": null
  3. To untar all the content, type:

    $ cd $HOME/TEST
    $ for f in $(ls); do tar xvf $f; done
  4. To check the results, type:

    $ find blobs/ rpm_dir/
  5. Begin examining and using the content.

4.8. Additional resources

  • Red Hat partners and customers can request new features, including package requests, by filling a support ticket through standard methods. Non-Red Hat customers do not receive support, but can file requests through the standard Red Hat Bugzilla for the appropriate RHEL product. For more information, see Red Hat Bugzilla Queue
  • Red Hat partners and customers can file support tickets through standard methods when running UBI on a supported Red Hat platform (OpenShift/RHEL). Red Hat support staff will guide partners and customers. For more information, see Open a Support Case