Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

Red Hat Universal Base Images for Docker users

March 24, 2020
Fernando Lozano
Related topics:
ContainersLinux
Related products:
Red Hat Enterprise Linux

Share:

    Red Hat Universal Base Images (UBIs) allow developers using Docker on Windows and Mac platforms to tap into the benefits of the large Red Hat ecosystem. This article demonstrates how to use Red Hat Universal Base Images with Docker from a non-Red Hat system, such as a Windows or Mac workstation.

    Red Hat Enterprise Linux and Docker

    When Red Hat Enterprise Linux (RHEL) 8 was released almost a year ago, and it came with lots of new features related to containers. The biggest ones were the new container tools (Podman, Buildah, and skopeo) and the new Red Hat Universal Base Images. There was also confusion because RHEL 8 dropped support for the Docker toolset. Some developers thought that they could not work with Docker anymore, and had to either migrate to a Red Hat-ecosystem Linux system such as CentOS or stay away from Red Hat customers.

    This situation was far from the truth because containers are not just about Docker anymore. Container runtimes, container images, registry servers, and other technologies related to the Linux container ecosystem are now standardized by the Open Container Initiative (OCI). Thanks to the OCI, you can develop a container using one tool and then run the same container using another tool. For example, Red Hat builds a container image using Buildah on RHEL 8, and then you run that container image using Docker on a Windows system.

    Another example would be you building a container image using Docker on a Mac system and then later you run that container image on a Red Hat Enterprise Linux 8 server with Podman.

    Introducing Red Hat Universal Base Images

    Red Hat Universal Base images allow commercial and open source developers to build containers based on RHEL without requiring them or their users to be RHEL subscribers. Open source developers need the ability to run and share their applications anywhere, unencumbered by user agreements. While the Red Hat Developer subscription is useful and popular, it was not the best fit for them.

    Some commercial developers want to target both Red Hat customers and non-Red Hat customers. Their Red Hat customers want the ability to use Red Hat support services to their fullest, which implies running container images based on RHEL. So, these developers had to build two versions of their container images, one based on Red Hat Enterprise Linux, and others based on something else, or they had to deny their customers the ability to rely on Red Hat’s support services.

    Commercial and open source developers can use UBI to build container images from RHEL packages, and benefit from Red Hat’s fixes to performance and security issues. At the same time, using UBIs does not require any entitlement to a Red Hat subscription, not even a free Red Hat Developer program subscription.

    Universal Base Images and packages

    UBIs provide a set of base container images to build your application images. Some of these images include only the base operating systems. Others are runtime images that provide a runtime with its dependencies pre-integrated.

    UBIs also provide a set of Yum repositories that include a subset of Red Hat Enterprise Linux packages. Not all of RHEL is part of the UBI repositories. As an example, UBIs do not include packages related to low-level network and storage servers.

    Exploring Universal Base Images

    The best way to see what is provided by UBIs is through a few searches. In the following examples, the prompt is $, which could be on a Mac system running Docker Desktop. This same prompt could also be on a Windows Home system using Docker tools from a Cygwin terminal, or a Windows Professional system using Docker Desktop. It could even be on a non-Red Hat Linux distribution.

    First, do a search for all UBI base images on the Red Hat Container Registry:

    $ docker search registry.access.redhat.com/ubi
    NAME                                          DESCRIPTION                                     STARS               OFFICIAL            AUTOMATED
    jboss-eap-7/eap72-openjdk11-openshift-rhel8   JBoss EAP 7.2 OpenJDK 11 Container Image for…   0      
    ubi8/ubi-init                                 Provides the latest release of the Red Hat U…   0      
    ubi8/ubi                                      Provides the latest release of the Red Hat U…   0      
    ubi8/ubi-minimal                              Provides the latest release of the Minimal R…   0      
    ubi7/ubi-init                                 The Universal Base Image Init is designed to…   0      
    ubi7/ubi                                      The Universal Base Image is designed and eng…   0      
    ubi7/ubi-minimal                              The Universal Base Image Init is designed to…   0
    

    The Red Hat Container Registry is a public registry that hosts all UBI container images. These same images are also available from the Red Hat terms-based container registry. That registry server requires you to authenticate to prove that you have a valid Red Hat subscription. During this article, I’ll stick to Red Hat’s public registry for ease of use.

    Now, start a UBI test container running an interactive shell:

    $ docker run -it --name test registry.access.redhat.com/ubi8/ubi:8.1 bash
    Unable to find image 'registry.access.redhat.com/ubi8/ubi:8.1' locally
    8.1: Pulling from ubi8/ubi
    eae5d284042d: Pull complete
    ff6f434a470a: Pull complete
    Digest: sha256:b6ae810838a1a105b568e5b438a4379ac5e06ee8df1c11d71772f8708180ffcc
    Status: Downloaded newer image for registry.access.redhat.com/ubi8/ubi:8.1
    [root@de1d73d88418 /]#

    Inside the test container, list its preconfigured Yum repositories:

    [root@de1d73d88418 /]# yum repolist
    Updating Subscription Management repositories.
    Unable to read consumer identity
    This system is not registered to Red Hat Subscription Management. You can use subscription-manager to register.
    Red Hat Universal Base Image 8 (RPMs) - BaseOS                                                      123 kB/s | 760 kB     00:06    
    Red Hat Universal Base Image 8 (RPMs) - AppStream                                                   301 kB/s | 3.3 MB     00:11    
    Red Hat Universal Base Image 8 (RPMs) - CodeReady Builder                                           2.2 kB/s | 9.1 kB     00:04    
    repo id                                       repo name                                                                       status
    ubi-8-appstream                               Red Hat Universal Base Image 8 (RPMs) - AppStream                               819
    ubi-8-baseos                                  Red Hat Universal Base Image 8 (RPMs) - BaseOS                                  664
    ubi-8-codeready-builder                       Red Hat Universal Base Image 8 (RPMs) - CodeReady Builder                        12

    Note: You can safely ignore Yum messages about Red Hat’s subscription manager. UBI images are designed to work for Red Hat subscribers as well, letting them add packages from Red Hat Enterprise Linux that require a valid entitlement.

    You can also search for individual packages available from these repositories. The following example searches for Nginx web server packages:

    [root@de1d73d88418 /]# yum search nginx
    Updating Subscription Management repositories.
    Unable to read consumer identity
    This system is not registered to Red Hat Subscription Management. You can use subscription-manager to register.
    Last metadata expiration check: 0:00:06 ago on Mon Feb 24 23:37:46 2020.
    =================================================== Name Exactly Matched: nginx ====================================================
    nginx.x86_64 : A high performance web server and reverse proxy server
    ================================================== Name & Summary Matched: nginx ===================================================
    nginx-mod-mail.x86_64 : Nginx mail modules
    nginx-mod-stream.x86_64 : Nginx stream modules
    nginx-mod-http-perl.x86_64 : Nginx HTTP perl module
    nginx-mod-http-xslt-filter.x86_64 : Nginx XSLT module
    nginx-mod-http-image-filter.x86_64 : Nginx HTTP image filter module
    nginx-filesystem.noarch : The basic directory layout for the Nginx server
    nginx-all-modules.noarch : A meta package that installs all available Nginx modules

    Finally, leave the test container, stop, and remove it:

    [root@de1d73d88418 /]# exit
    $ docker stop test
    test
    $ docker rm test
    test

    As you can see, running UBIs using Docker just works. But what about building container images based on Universal Base Images?

    A sample Dockerfile for a PHP application

    The following listing shows a sample Dockerfile for a PHP application:

    FROM registry.access.redhat.com/ubi8/ubi:8.1
    
    RUN yum --disableplugin=subscription-manager -y module enable php:7.3 \
      && yum --disableplugin=subscription-manager -y install httpd php \
      && yum --disableplugin=subscription-manager clean all
    
    ADD index.php /var/www/html
    
    RUN sed -i 's/Listen 80/Listen 8080/' /etc/httpd/conf/httpd.conf \
      && sed -i 's/listen.acl_users = apache,nginx/listen.acl_users =/' /etc/php-fpm.d/www.conf \
      && mkdir /run/php-fpm \
      && chgrp -R 0 /var/log/httpd /var/run/httpd /run/php-fpm \
      && chmod -R g=u /var/log/httpd /var/run/httpd /run/php-fpm
    
    EXPOSE 8080
    USER 1001
    CMD php-fpm & httpd -D FOREGROUND

    The second RUN instruction allows the image to run unchanged under OpenShift’s default security policies and also under rootless podman. Otherwise, that image would require running as the root user, something that regular OpenShift users cannot do.

    You also need a "hello, world"-style PHP page for the index.php file:

    <html>
    <body>
    <?php print "Hello, world!\n" ?>
    </body>
    </html>

    Now build the sample image:

    $  docker build -t php-hello .
    Sending build context to docker daemon  3.584kB
    Step 1/7 : FROM registry.access.redhat.com/ubi8/ubi:8.1
     ---> fd73e6738a95
    ...
    Successfully tagged php-hello:latest

    And start a container from the sample image:

    $ docker run --name hello -p 8080:8080 -d php-hello

    Finally, open a web browser and access localhost:8080 to see the Hello, world! message returned by your sample container. When you are happy with the results, stop and delete the sample container:

    $ docker stop hello
    hello
    $ docker rm hello
    hello

    As you see, there is nothing unusual about using Universal Base Images with Docker. They just work.

    Updated on September 14, 2020: Fixed the sample Dockerfile to work with rootless podman from RHEL 8.1+ and Fedora. The change does not affect running under Docker and early OpenShift 4.x.

    Learning more about UBIs

    • Universal Base Images (UBI): Images, repositories, and packages from the Red Hat Customer Portal.
    • Red Hat Universal Base Images (UBI) at Red Hat Developer, which also provides the UBI FAQ among other resources.
    • Using Red Hat Universal Base Image with Azure Pipelines and Red Hat Quay.io from the Red Hat blog, which is a great example of using UBIs with non-Red Hat tools.
    • How Red Hat partners can now freely redistribute more RHEL packages.
    Last updated: February 22, 2024

    Recent Posts

    • How to run a fraud detection AI model on RHEL CVMs

    • How we use software provenance at Red Hat

    • Alternatives to creating bootc images from scratch

    • How to update OpenStack Services on OpenShift

    • How to integrate vLLM inference into your macOS and iOS apps

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue