Jump to content
documentation.suse.com / Container Guide
SUSE Linux Enterprise Server 15 SP4

Container Guide

This guide provides an introduction to the SUSE container ecosystem. This document is a work in progress. The content in this document is subject to change without notice.

Authors: Dmitri Popov and Nora Kořánová
Publication Date: September 13, 2022

Copyright © 2006– 2022 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see https://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.


1 Required background

To keep the scope of these guidelines manageable, certain technical assumptions have been made:

  • You have some computer experience and are familiar with common technical terms.

  • You are familiar with the documentation for your system and the network on which it runs.

  • You have a basic understanding of Linux systems.

2 Available documentation

Online documentation

The online documentation for this product is available at https://documentation.suse.com/#sles. Browse or download the documentation in various formats.

Find the online documentation for other products at https://documentation.suse.com/.

Note: Latest updates

The latest documentation updates are usually available in the English version of the documentation.

Release notes

For release notes, see https://www.suse.com/releasenotes/.

In your system

For offline use, find documentation in your installed system under /usr/share/doc. Many commands are also described in detail in their manual pages. To view them, run man, followed by a specific command name. If the man command is not installed on your system, install it with sudo zypper install man.

3 Improving the documentation

Your feedback and contributions to this documentation are welcome. The following channels for giving feedback are available:

Service requests and support

For services and support options available for your product, see https://www.suse.com/support/.

To open a service request, you need a SUSE subscription registered at SUSE Customer Center. Go to https://scc.suse.com/support/requests, log in, and click Create New.

Bug reports

Report issues with the documentation at https://bugzilla.suse.com/. To simplify this process, you can use the Report an issue link in the HTML version of this document. Position the cursor in the affected sentence and in the Give feedback section of the right-hand navigation panel, click Report an issue. This preselects the right product and category in Bugzilla and adds a link to the current section. You can start typing your bug report right away. A Bugzilla account is required.


To contribute to this documentation, use the Edit source document link in the HTML version of this document. Position the cursor in the affected sentence and in the Give feedback section of the right-hand navigation panel, click Edit source document. This takes you to the source code on GitHub, where you can open a pull request. A GitHub account is required.

Note: Edit source document only available for English

The Edit source document links are only available for the English version of each document. For all other languages, use the Report an issue link as described above.

For more information about the documentation environment used for this documentation, see the repository's README at https://github.com/SUSE/doc-sle/blob/main/README.adoc


You can also report errors and send feedback concerning the documentation to <>. Include the document title, the product version, and the publication date of the document. Additionally, include the relevant section number and title (or provide the URL), and provide a concise description of the problem.

4 Documentation conventions

The following notices and typographical conventions are used in this documentation:

  • /etc/passwd: directory names and file names

  • PLACEHOLDER: replace PLACEHOLDER with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • package name : name of a package

  • Alt, AltF1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File › Save As: menu items, buttons

  • AMD/Intel This paragraph is only relevant for the AMD64/Intel 64 architecture. The arrows mark the beginning and the end of the text block.

    IBM Z, POWER This paragraph is only relevant for the architectures IBM Z and POWER. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

  • Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.

    # command
    > sudo command
  • Commands that can be run by non-privileged users.

    > command
  • Notices

    Warning: Warning notice

    Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.

    Important: Important notice

    Important information you should be aware of before proceeding.

    Note: Note notice

    Additional information, for example about differences in software versions.

    Tip: Tip notice

    Helpful information, like a guideline or a piece of practical advice.

1 Introduction to Linux containers

The Linux kernel's namespaces and kernel control groups features enable the container to be isolated from the rest of the host system and other containers. Linux containers offer a lightweight virtualization method to run multiple isolated environments simultaneously on a single host. Unlike Xen and KVM, where a full guest operating system is executed through a virtualization layer, Linux containers share and directly use the host OS kernel. This reduces the overhead required for accessing the operating system resources and allows for better overall performance compared to a generic Virtual Machine environment.

Advantages of using containers
  • Containers make it possible to isolate applications in self-contained units.

  • Containers provide near-native performance, as the kernel overhead is lower compared to virtualization and emulation.

  • It is possible to control network interfaces and apply resources inside containers through kernel control groups (cgroups).

  • Portability and ease of development for application developers as the container will hold all necessary libraries, dependencies, and files needed.

Limitations of containers
  • Containers run on the host system's kernel, so the containers will have to use the specific kernel version provided by the host.

  • Only Linux-based applications can be containerized.

  • A container encapsulates binaries for a specific architecture (x86_64 or aarch64 for instance). So a container made for x86_64 only runs on a x86_64 system host.

  • Containers in themselves are no more secure than executing binaries outside of a container, and the overall security of containers depends on the host system. While containerized applications can be secured through AppArmor or SELinux profiles, container security require putting in place tools and policies that ensure security of the container infrastructure and applications.

1.1 Key concepts and brief introduction to Podman

Although Docker Open Source Engine is a popular choice for working with images and containers, Podman provides a drop-in replacement for Docker that offers several advantages. While Chapter 11, Podman overview provides more information on Podman, this chapter offers a quick introduction to key concepts and a basic procedure for creating a container image and using it to run a container.

The basic Podman workflow is as follows:


Running a container, either on a local machine or cloud service, usually involves the following steps:

  1. Fetch a base image by pulling it from a registry to your local machine.

  2. Create a Dockerfile and use it to build a custom image on top of the base image.

  3. Use the created image to start one or more containers.

To run a container, you need an image. An image includes all dependencies needed to run the application. For example, the SLE base image contains the SLE distribution with a minimal package selection.

While it is possible to create an image from scratch, few applications would work in such an empty environment. Thus, using an existing base image is more practical in most situations. A base image has no parent, meaning it is not based on another image.

Although you can use a base image for running containers, the main purpose of base images is to serve as foundations for creating custom images that can run containers with specific applications, servers, services, and so on.

Both base and custom images are usually available through a repository of images called a registry. Unless a registry is explicitly specified, Podman pulls images from the Docker Hub registry. While you can fetch a base image manually, Podman can do that automatically when building a custom image.

To build a custom image, you need to create a special file called a Containerfile or Dockerfile, containing building instructions. For example, a Dockerfile can contain instructions to update the system software, install the desired application, open specific network ports, run commands, etc.

You can build images not only from base images, but also on top of custom images. So you can have an image consisting of multiple layers:


1.1.1 Practical example

The following procedure shows how to build a custom Docker image that can be used to run a container with a simple PHP application called example, served using the built-in PHP development server.

Procedure 1.1: Building an image and running a container
  1. Install Podman:

    > sudo zypper in podman
  2. Switch to the PHP project's directory and create a file named Dockerfile :

    > cd example
    > touch Dockerfile
  3. Open the Dockerfile file for editing and add the following:

    FROM php:7.4-cli
    COPY . /usr/src/example
    WORKDIR /usr/src/example
    EXPOSE 8000
    CMD [ "php", "-S", "" ]
  4. Build a container image:

    > sudo podman build -t example .
  5. Run a container:

    > sudo podman run -it -p 8000:8000 --rm example
  6. Point the browser to localhost:8000 to access the application running in the container.

Note that SUSE does not provide support for third-party images, such as the one used in this example.

2 SLE Base Container Images

2.1 Introduction to SLE Base Container Images

SLE Base Container Image (SLE BCI) are minimal SUSE Linux Enterprise Server 15-based images that you can use to develop, deploy, and share applications. There are two types of SLE BCI:

  • General-purpose SLE BCI can be used for building custom container images and for deploying applications.

  • Language stack SLE BCI provide minimal environments for developing and deploying applications in specific programming languages.

In addition to that, we will provide Application Container Images based on SLE BCI featuring popular containerized applications like Nginx, PostgreSQL, MariaDB and RMT.

2.1.1 Highlights

  • SLE BCI are fully compatible with SUSE Linux Enterprise Server, but they do not require a subscription to run and distribute them.

  • SLE BCI automatically run in FIPS-compatible mode when the host operating system is running in FIPS mode.

  • Each SLE BCI includes the RPM database, which makes it possible to audit the contents of the container image. You can use the RPM database to determine the specific version of the RPM package any given file belongs to. This allows you to ensure that a container image is not susceptible to known and already fixed vulnerabilities.

  • All SLE BCI (except for those without zypper) come with the container-suseconnect service. This gives containers that run on a registered SLES host access to the full SLES repositories. container-suseconnect is invoked automatically when you run zypper for the first time, and the service adds the correct SLES repositories into the running container. On an unregistered SLES host or on a non-SLES host, the service does nothing.

2.1.2 General-purpose SLE BCI

There are four general purpose SLE BCI, and each container image comes with a minimum set of packages to keep its size low. You can use a general purpose SLE BCI either as a starting point for building custom container images, or as a platform for deploying specific software. For more information about general purpose SLE BCI, see Section 2.3, “BCI-Base, BCI-Minimal, BCI-Micro, and BCI-BusyBox”.

2.1.3 Language stack SLE BCI

Language stack SLE BCI are built on top of the BCI-Base general-purpose SLE BCI. Each container image comes with the zypper stack and the free SLE_BCI repository. Additionally, each image includes most common tools for building and deploying applications in the specific language environment. This includes tools like a compiler or interpreter as well as the language specific package manager. For more information about language stack SLE BCI, see Section 2.4, “Language stack SLE Base Container Images”.

2.1.4 Important note on status and lifecycle

All container images, except for base, are currently classified as tech preview, and SUSE doesn't provide official support for them. This information is visible on the web on registry.suse.com. In addition to that, it is also indicated via the com.suse.supportlevel label whether a container image still has the tech preview status. You can use the skopeo and jq utilities to check the status of the desired SLE BCI as follows:

❯ skopeo inspect docker://registry.suse.com/bci/bci-micro:15.4 | jq '.Labels["com.suse.supportlevel"]'

❯ skopeo inspect docker://registry.suse.com/bci/bci-base:15.4 | jq '.Labels["com.suse.supportlevel"]'

In the example above, the com.suse.supportlevel label is set to techpreview in the bci-micro container image, indicating that the image still has the tech preview status. The bci-base container image on the other hand is fully l3 supported. Unlike like the general purpose SLE BCI, the language stack SLE BCI may not follow the lifecycle of the SLE distribution: they are supported as long as the respective language stack receives support. In other words, new versions of SLE BCI (indicated by the OCI tags) may be released during the lifecycle of a SLE Service Pack, while older versions may become unsupported. Refer to suse.com/lifecycle to find out whether the container in question is still under support.

Important: No updates beyond support period

A SLE Base Container Image is no longer updated after its support period ends. You will not receive any notification when that happens.

2.1.5 Getting started

The SLE BCI are available as OCI-compatible container images directly from registry.suse.com and can be used like any other container image. For example, using one of the general purpose containers:

> podman run --rm -it registry.suse.com/bci/bci-base:15.4 grep '^NAME' /etc/os-release

Alternatively, you can use SLE BCI in Dockerfile as follows:

FROM registry.suse.com/bci/bci-base:15.4
RUN zypper -n in python3 && \
    echo "Hello Green World!" > index.html
ENTRYPOINT ["/usr/bin/python3", "-m", "http.server"]

You can then build container images using the docker build . or buildah bud . commands:

> docker build .
Sending build context to Docker daemon  2.048kB
Step 1/4 : FROM registry.suse.com/bci/bci-base:15.4
 ---> e34487b4c4e1
Step 2/4 : RUN zypper -n in python3 &&     echo "Hello Green World!" > index.html
 ---> Using cache
 ---> 9b527dfa45e8
Step 3/4 : ENTRYPOINT ["/usr/bin/python3", "-m", "http.server"]
 ---> Using cache
 ---> 953080e91e1e
Step 4/4 : EXPOSE 8000
 ---> Using cache
 ---> 48b33ec590a6
Successfully built 48b33ec590a6
> docker run -p 8000:8000 --rm -d 48b33ec590a6
> curl localhost:8000
Hello Green World!

2.2 Why SLE Base Container Images

SLE BCIs offer a platform for creating SLE-based custom container images and containerized applications that can be distributed freely. SLE BCIs feature the same predictable enterprise lifecycle as SLES. The SLE_BCI 15 SP3 and SP4 repository (which is a subset of the SLE repository) gives SLE BCIs access to 4,000 packages available for the AMD64/Intel 64, AArch64, ppc64le, and s390x architectures. The packages in the repository have undergone quality assurance and security audits by SUSE. The container images are FIPS-compliant when running on a host in FIPS mode. In addition to that, SUSE can provide official support for SLE BCIs through SUSE subscription plans.


Each package in the SLE_BCI repository undergoes security audits, and SLE BCIs benefit from the same mechanism of dealing with CVEs as SLES. All discovered and fixed vulnerabilities are announced via e-mail, the dedicated CVE pages, and as OVAL and CVRF data. To ensure a secure supply chain, all container images are signed with Notary v1, Podman's GPG signatures, and Sigstore Cosign.


Since SLE BCIs are based on SLE, they feature the same level of stability and quality assurance as SUSE Linux Enterprise Server. Similar to SLES, SLE BCIs receive maintenance updates that provide bug fixes, improvements, and security patches.

Tooling and integration

SLE BCIs are designed to provide drop-in replacements for popular container images available on hub.docker.com. You can use the general-purpose SLE BCIs and the tools they put at your disposal to create custom container images, while the language stack SLE BCIs provide a foundation and the required tooling for building containerized applications.


BCIs are covered by a permissive EULA that allows you to redistribute custom container images based on a BCI.

2.3 BCI-Base, BCI-Minimal, BCI-Micro, and BCI-BusyBox

SUSE offers several general-purpose SLE Base Container Images that are intended as deployment targets or as foundations for creating customized images: BCI-Base, BCI-Minimal, BCI-Micro, and BCI-BusyBox. These images share the common SLES base, and none of them ship with a specific language or an application stack. All images feature the RPM database (even if the specific image does not include the RPM package manager) that can be used to verify the provenance of every file in the image. Each image includes the SLES certificate bundle, which allows the deployed applications to use the system's certificates to verify TLS connections.

2.3.1 Quick overview

The table below provides a quick overview of the differences between BCI-Base, BCI-Minimal, BCI-Micro, and BCI-BusyBox.


2.3.2 BCI-Base and BCI-Init: When you need flexibility

This SLE BCI comes with the Zypper package manager and a free SLE-BCI repository. This allows you to install software available in the repository and customize the image during the build. The downside is the size of the image. It is the largest of the general-purpose SLE BCIs, so it is not always the best choice for a deployment image.

A variant of BCI-Base called BCI-Init comes with systemd preinstalled. The BCI-Init container image can be useful in scenarios requiring systemd for managing services in a single container.

Note: Using BCI-init with Docker or nerdctl

When using BCI-init container with Docker, you must use the following arguments for systemd to work correctly in the container:

docker run -ti --tmpfs /run -v /sys/fs/cgroup:/sys/fs/cgroup:rw --cgroupns=host registry.suse.com/bci/bci-init:latest

In case of nerdctl, the correct command is as follows:

nerdctl run -ti --env container=containerd --tmpfs /run -v /sys/fs cgroup:/sys/fs/cgroup:rw --cgroupns=host  registry.suse.com/bci bci-init:latest

To correctly shut down the container use the following command:

docker kill -s SIGRTMIN+3 CONTAINER_ID

2.3.3 BCI-Minimal: When you do not need Zypper

This is a stripped-down version of the BCI-Base image. BCI-Minimal comes without Zypper, but it does have the RPM package manager installed. This significantly reduces the size of the image. However, while RPM can install and remove packages, it lacks support for repositories and automated dependency resolution. The BCI-Minimal image is therefore intended for creating deployment containers, and then installing the desired RPM packages inside the containers. Although you can install the required dependencies, you need to download and resolve them manually. However, this approach is not recommended as it is prone to errors.

2.3.4 BCI-Micro: When you need to deploy static binaries

This image is similar to BCI-Minimal but without the RPM package manager. The primary use case for the image is deploying static binaries produced externally or during multi-stage builds. As there is no straightforward way to install additional dependencies inside the container image, we recommend deploying a project using the BCI-Minimal image only when the final build artifact bundles all dependencies and has no external runtime requirements (like Python or Ruby).

2.3.5 BCI-BusyBox: When you need the smallest and GPLv3-free image

Similar to BCI-Micro, the BCI-BusyBox image comes with the most basic tools only. However, these tools are provided by the BusyBox project. This has the benefit of further size reduction. Furthermore, the image contains no GPLv3 licensed software. When using the image, keep in mind that there are certain differences between the BusyBox tools and the GNU Coreutils. So scripts written for a system that uses GNU Coreutils may require modification to work with BusyBox.

2.3.6 Approximate sizes

For your reference, the list below provides an approximate size of each SLE BCI. Keep in mind that the provided numbers are rough estimations.

  • BCI-Base ~94 MB

  • BCI-Minimal ~42 MB

  • BCI-Micro ~26 MB

  • BCI-BusyBox ~14 MB

2.4 Language stack SLE Base Container Images

If you have a working knowledge of containers, you will not have any difficulties using SLE BCIs. However, there are certain features that set SLE BCIs apart from similar offerings, like images based on Debian or Alpine Linux. And understanding the specifics can help you to get the most out of SLE BCIs in the shortest time possible.

2.4.1 Language stack SLE BCIs

Language stack SLE BCI are built on top of BCI-Base. Below is an overview of the available language stack SLE BCIs.


2.4.2 Package manager

The default package manager in SUSE Linux Enterprise is Zypper. Similar to APT in Debian and APK in Alpine Linux, Zypper offers a command-line interface for all package management tasks. Below is brief overview of commonly used container-related Zypper commands.

Install packages

zypper --non-interactive install PACKAGE_NAME

Add a repository

zypper --non-interactive addrepo REPOSITORY_URL; zypper --non-interactive refresh

Update all packages

zypper --non-interactive update

Remove a package

zypper --non-interactive remove --clean-deps PACKAGE_NAME (the --clean-deps flag ensures that no longer required dependencies are removed as well)

Clean up temporary files

zypper clean

For more information on using Zypper, refer to https://documentation.suse.com/sles-15/html/SLES-all/cha-sw-cl.html#sec-zypper.

All the described commands use the --non-interactive flag to skip confirmations, since you cannot approve these manually during container builds. Keep in mind that you must use the flag with any command that modifies the system. Also note that --non-interactive is not a "yes to all" flag. Instead, --non-interactive confirms what is considered to be the intention of the user. For example, an installation command with the --non-interactive option fails if it needs to import new repository signing keys, as that is something that the user should verify themselves.

2.4.3 Common patterns

Here are a few examples that can give you an idea how to accomplish certain tasks in SLE BCI compared to Debian.

Remove orphaned packages
  • Debian: apt-get autoremove -y

  • SLE BCI: Not required as long as you remove installed packages using the zypper --non-interactive remove --clean-deps PACKAGE_NAME

Obtain container's architecture
  • Debian: dpkgArch="$(dpkg --print-architecture | awk -F- '{ print $NF }')"

  • SLE BCI: arch="$(uname -p|sed 's/x86_64/amd64/')"

Install packages required for compilation
  • Debian: apt-get install -y build-essential

  • SLE BCI: zypper -n in gcc gcc-c++ make

Verify GnuPG signatures
  • Debian: gpg --batch --verify SIGNATURE_URL FILE_TO_VERIFY

  • SLE BCI: zypper -n in dirmngr; gpg --batch --verify SIGNATURE_URL FILE_TO_VERIFY; zypper -n remove --clean-deps dirmngr; zypper -n clean

2.4.4 Package naming conventions

SUSE Linux Enterprise package naming conventions differ from Debian, Ubuntu, and Alpine, and they are closer to those of Red Hat Enterprise Linux. The main difference is that development packages of libraries (that is, packages containing headers and build description files) are named PACKAGE-devel in SUSE Linux Enterprise, as opposed to PACKAGE-dev as they are in Debian and Ubuntu. When in doubt, search for the package directly using the following command: docker run --rm registry.suse.com/bci/bci-base:OS_VERSION zypper search PACKAGE_NAME (replace OS_VERSION with the appropriate service version number, for example: 15.3 or 15.4).

2.4.5 Adding GPG signing keys

Adding external repositories to a container or container image normally requires importing the GPG key used for signing the packages. This can be done with the rpm --import KEY_URL command. This adds the key to the RPM database, and all packages from the repository can be installed afterwards.

3 Tools for building images and managing containers

This chapter provides a brief overview of tools for building images and managing containers. Most of the tools mentioned below are part of the SUSE Linux Enterprise Server 15 SP4 Containers Module. You can see the full list of packages in the Containers Module in the SUSE Customer Center.

3.1 Tools available to customers

3.1.1 Docker

Docker is a system for creating and managing containers. Its core is the Docker Open Source Engine—a lightweight virtualization solution to run containers simultaneously on a single host. Docker containers can be built using Dockerfiles (see Dockerfile). For a general introduction to Docker Open Source Engine, refer to Chapter 4, Docker Open Source Engine overview.

3.1.2 Podman

Podman stands for Pod Manager tool. It is a daemonless container engine for developing, managing, and running Open Container Initiative (OCI) containers on a Linux system, and it offers a drop-in alternative for Docker. Podman is the default container runtime in openSUSE Kubic—a certified Kubernetes distribution built on top of openSUSE. For a general introduction to Podman, refer to Chapter 11, Podman overview.

3.1.3 Buildah

Buildah facilitates building OCI container images. It is a complementary tool to Podman, and podman build uses Buildah to perform container image builds. Buildah makes it possible to build images from scratch, from existing images, and using Dockerfiles. OCI images built using the Buildah command-line tool and the underlying OCI-based technologies (for example, containers/image and containers/storage ) are portable and can therefore run in a Docker Open Source Engine environment.

For information on installing and using Buildah, refer to Chapter 12, Buildah overview.

3.2 SUSE build tools

3.2.1 Open Build Service

The Open Build Service (OBS) provides free infrastructure for building and storing RPM packages including various container formats. The OBS Container Registry provides a detailed listing of all container images built by the OBS, complete with commands for pulling the images into your local Docker environment. The OBS openSUSE container image templates can be modified to specific needs, which offers the easiest way to create your own container branch. Container images can be built with native Docker tools from an existing image using a Dockerfile. Alternatively, images can be built from scratch using the KIWI image-building solution.

Instructions on how to build images on OBS can be found at https://openbuildservice.org/2018/05/09/container-building-and-distribution/.

3.2.2 KIWI

KIWI Next Generation is a multi-purpose tool for building images. In addition to container images, regular installation ISO images, and images for virtual machines, KIWI can build images that boot via PXE or Vagrant boxes. The main building block in KIWI is an image XML description, a directory that includes the config.xml or .kiwi file along with scripts or configuration data. The process of creating images with KIWI is fully automated and does not require any user interaction. Any information required for the image creation process is provided by the primary configuration file config.xml . The image can be customized using the config.sh and images.sh scripts.


It is important to distinguish between KIWI NG (currently version 9.20.9) and its unmaintained legacy versions (7.x.x or older), now called KIWI Legacy.

For specific information on how to install KIWI and use it to build images, see the KIWI documentation. A collection of example image descriptions can be found on the KIWI GitHub repository.

KIWI's man pages provide information on using the tool. To access the man pages, install the kiwi-man-pages package.

3.3 Building official SLE images

Images are considered official only if they are built using the Internal Build Service.

There are no official SLE container images at https://build.opensuse.org, and the RPMs exported there are not identical to the internal ones. This means that it is not possible to build officially supported images at https://build.opensuse.org.

4 Docker Open Source Engine overview

Docker Open Source Engine is a lightweight virtualization solution to run multiple virtual Linux environments (containers) simultaneously on top of a single Linux kernel, without a hypervisor. Containers are isolated using Kernel cgroups (Control groups) and Namespaces.

Full virtualization solutions, such as Xen, KVM, and libvirt, are based on simulating a complete hardware environment and running multiple operating system instances inside these virtual machines. Docker Open Source Engine provides operating-system-level virtualization: a single Linux kernel controls multiple isolated containers.

Docker Open Source Engine allows developers and system administrators to manage the complete life cycle of images. Docker Open Source Engine makes it easy to build, ship, and run images containing applications.

Docker Open Source Engine has the following advantages:

  • Isolation of applications through containers.

  • Near-native performance, as Docker Open Source Engine manages allocation of resources in real time.

  • Control network interfaces and resources available inside containers through cgroups.

  • Versioning of images.

  • Building new images based on existing ones.

  • Container orchestration.

Docker Open Source Engine has the following limitations:

  • Containers run on the host system's kernel and cannot use a different kernel.

  • Only supports Linux applications and not other operating systems.

  • Docker Open Source Engine is not a full virtualization stack like Xen, KVM, or libvirt.

  • Security depends on the host system. Refer to the official security documentation for more details.

4.1 Docker Open Source Engine architecture

Docker Open Source Engine uses a client/server architecture. You can use the CLI client to communicate with the daemon. The daemon performs operations with containers and manages images locally or in registry. The CLI client can run on the same server as the host daemon or on a different machine. The CLI client communicates with the daemon by using network sockets. The architecture is shown in Figure 4.1, “Docker Open Source Engine architecture”.

Docker Open Source Engine architecture
Figure 4.1: Docker Open Source Engine architecture

5 Setting up Docker Open Source Engine

5.1 Preparing the host

Prepare the host as described below. Before installing any Docker-related packages, you need to enable the Containers Module:

Note: Built-in Docker orchestration support

Starting with Docker Open Source Engine 1.12, container orchestration is now an integral part of Docker Open Source Engine. Even though this feature is available in SUSE Linux Enterprise Server, it is not supported by SUSE and is only provided as a technology preview. Use Kubernetes for container orchestration. For details, refer to the Kubernetes documentation.

Procedure 5.1: Enabling the Containers Module using graphical user interface YaST
  1. Start YaST, and select Software › Software Repositories.

  2. Click Add to open the add-on dialog.

  3. Select Extensions and Modules from Registration Server and click Next.

  4. From the list of available extensions and modules, select Containers Module 15 SP4 x86_64 and click Next.

    The Containers Module and its repositories will be added to your system.

  5. If you use Repository Mirroring Tool, update the list of repositories on the RMT server.

Procedure 5.2: Enabling the Containers Module from command line using SUSEConnect
  • The Containers Module can also be added with the following command:

    > sudo SUSEConnect -p sle-module-containers/15.4/x86_64
Procedure 5.3: Installing and setting up Docker Open Source Engine
  1. Install the docker package:

    > sudo zypper install docker
  2. To automatically start the Docker service at boot time:

    > sudo systemctl enable docker.service

    This also automatically enables docker.socket.

    1. Open the /etc/sysconfig/docker file. Search for the parameter DOCKER_OPTS and add --insecure-registry ADDRESS_OF_YOUR_REGISTRY.

    2. Add CA certificates to the directory /etc/docker/certs.d/REGISTRY_ADDRESS

      > sudo cp CA /etc/pki/trust/anchors/
    3. Copy the CA certificates to your system:

      > sudo update-ca-certificates
  3. Start the Docker service:

    > sudo systemctl start docker.service

    This automatically starts docker.socket.

The Docker daemon listens on a local socket accessible only by the root user and by the members of the docker group. The docker group is automatically created during package installation.

To allow a certain user to connect to the local Docker daemon, use the following command:

> sudo /usr/sbin/usermod -aG docker USERNAME

This allows the user to communicate with the local Docker daemon.

5.2 Configuring the network

To give the containers access to the external network, enable the ipv4 ip_forward rule.

5.2.1 How Docker Open Source Engine interacts with iptables

To learn more about how containers interact with each other and the system firewall, see the Docker documentation.

It is also possible to completely prevent Docker Open Source Engine from manipulating iptables. See the Docker documentation.

5.3 Storage drivers

Docker Open Source Engine supports different storage drivers:

  • vfs: This driver is automatically used when the Docker host file system does not support copy-on-write. This driver is simpler than the others listed and does not leverage certain advantages of Docker Open Source Engine such as shared layers. It is a reliable but slow driver.

  • devicemapper: This driver relies on the device-mapper thin provisioning module. It supports copy-on-write, so it leverages all the advantages of Docker Open Source Engine.

  • btrfs: This driver relies on Btrfs to provide all the features required by Docker Open Source Engine. To use this driver, the /var/lib/docker directory must be on a Btrfs file system.

Since SUSE Linux Enterprise Server 12 onward, the Btrfs file system is used by default, which forces Docker Open Source Engine to use the btrfs driver.

It is possible to specify what driver to use by changing the value of the DOCKER_OPTS variable defined in the /etc/sysconfig/docker file. This can be done either manually or using YaST by browsing to the System › /etc/sysconfig Editor › System › Management › DOCKER_OPTS menu and entering the -s storage_driver string.

For example, to force the usage of the devicemapper driver, enter the following text:

DOCKER_OPTS="-s devicemapper"
Important: Mounting /var/lib/docker

It is recommended to mount /var/lib/docker on a separate partition or volume. In case of file system corruption, this would leave the operating system running Docker Open Source Engine unaffected.

If you choose the Btrfs file system for /var/lib/docker, it is strongly recommended to create a subvolume for it. This ensures that the directory is excluded from file system snapshots. If you do not exclude /var/lib/docker from snapshots, the file system will likely run out of disk space soon after you start deploying containers. In addition, a rollback to a previous snapshot will also reset the Docker database and images. For more information, see https://documentation.suse.com/sles-15/html/SLES-all/cha-snapper.html#sec-snapper-setup-customizing-new-subvolume.

5.4 Updates

All updates to the docker package are marked as interactive (that is, no automatic updates) to avoid accidental updates breaking running container workloads. In general, we recommend stopping all running containers before applying an update to Docker Open Source Engine.

To avoid data loss, we do not recommend having workloads rely on containers being start-able after an update to Docker Open Source Engine. Although it is technically possible to keep containers running during an update via the --live-restore option, experience has shown that such updates can introduce regressions. SUSE does not support this feature.

6 Configuring image storage

Before creating custom images, decide where you want to store images. The easiest solution is to push images to Docker Hub. By default, all images pushed to Docker Hub are public. Make sure not to publish sensitive data or software not licensed for public use.

You can restrict access to custom container images with the following:

  • Docker Hub allows creating private repositories for paid subscribers.

  • An on-site Docker Registry allows storing all the container images used by your organization.

6.1 What is Docker Registry?

Docker Registry is an open source platform for storing and retrieving container images. You can avoid using Docker Hub by running a local instance of Docker Registry.

Docker Registry is also used by Docker Hub. However, from a user's point of view, Docker Hub consists of the following components:

The user interface (UI)

The part that is accessed by users using a browser. The UI provides an easy way to browse the contents of Docker Hub, either manually or using a search feature. It can be used to create organizations by different users.

This component is closed source.

The authentication component

This component is used to protect the images stored in Docker Hub. It validates all push, pull, and search requests.

This component is closed source.

The storage back-end

A place that images are uploaded to and downloaded from. It is provided by Docker Registry.

This component is open source.

6.2 Running a Docker Registry

The SUSE Registry provides a container image that makes it possible to run a local Docker Registry as a container. Before you start a container, create a config.yml file with the following example configuration:

version: 0.1
  level: info
    rootdirectory: /var/lib/docker-registry

Also create an empty directory to map the /var/lib/docker-registry directory outside the container. This directory is used for storing container images.

Run the following command to pull the registry container image from the SUSE Registry and start a container that can be accessed on port 5000:

podman run -d --restart=always --name registry -p 5000:5000 \
-v /PATH/config.yml:/etc/docker/registry/config.yml \
-v /PATH/DIR:/var/lib/ \ docker-registry registry.suse.com/sles12/registry:2.6.2

To make it easier to manage the registry, create a corresponding system unit:

#  podman generate systemd registry >  \

Enable and start the registry service, then verify its status:

# systemctl enable suse_registry.service
# systemctl start suse_registry.service
# systemctl status suse_registry.service

For more details about Docker Registry and its configuration, see the official documentation at https://docs.docker.com/registry/.

6.3 Limitations

Docker Registry has two major limitations:

  • It lacks any form of authentication. That means everybody with access to Docker Registry can push and pull images to it. That includes overwriting existing images.

  • There is no way to see which images have been pushed to Docker Registry. You need to manually take notes of what is being stored on it. There is also no search functionality.

7 Obtaining containers

This chapter provides information on obtaining container images.

7.1 SUSE Linux Enterprise base images

SUSE offers several official base container images that can be used as a starting point for building custom containers. Each SLE base image provides a minimal environment with a shell and package management.

Base images are available from https://registry.suse.com. For information about the SUSE Registry, see Section 7.3, “SUSE Registry”. The base images in the SUSE Registry all have the status General Availability (that is, they are suitable for production use) and LTSS releases of SLES 12 and SLES 15. SUSE Linux Enterprise base images in the SUSE Registry receive security updates and are covered by the SUSE support plans. For more information about these support plans, see Chapter 15, Compatibility and support conditions.

7.2 SUSE container properties

SUSE container images have identifiers that provide information about their version, origin, and creation time. The individual identifiers listed below can be accessed after you pull a container image from the repository and run podman inspect on it.

7.2.1 Repository names

Repository names start with the name of the product, for example: suse/sle... and opensuse/tumbleweed. The SLE 15 containers for all service packs reside in the repository suse/sle15. However, for SLE 12, there is a separate repository name for each service pack, for example, suse/sles12sp3, suse/sles12sp4, and suse/sles12sp5.

7.2.2 Labels

Labels help to identify images. All SLE container image labels begin with com.suse.PRODUCTCONTAINER_NAME followed by a further specification. Container images also contain org.opencontainers.image labels.

Below is a list of all currently defined labels.

org.opencontainers.image.title, com.suse.sle.base.title
  • Must be provided by derived images: Yes

  • OCI notation: org.opencontainers.image.title

  • Description: Title of the image

  • Example: SUSE Linux Enterprise 15 Base Container

org.opencontainers.image.description, com.suse.sle.base.description
  • Must be provided by derived images: Yes

  • OCI notation: org.opencontainers.image.description

  • Description: Short description of the image

  • Example: Image containing a minimal environment for containers based on SUSE Linux Enterprise 15

org.opencontainers.image.version, com.suse.sle.base.version
  • Must be provided by derived images: Yes

  • OCI notation: org.opencontainers.image.version

  • Description: Image version (MAJOR.SP.CICOUNT.BUILDCOUNT)

  • Example:

org.opencontainers.image.created, com.suse.sle.base.created
  • Must be provided by derived images: Yes

  • OCI notation: org.opencontainers.image.created

  • Description: Timestamp of image build

  • Example: 2018-07-27T14:12:30Z

org.opencontainers.image.vendor, com.suse.sle.base.vendor
  • Must be provided by derived images: No

  • OCI notation: org.opencontainers.image.vendor

  • Description: Image vendor

  • Example: SUSE LLC

org.opencontainers.image.url, com.suse.sle.base.url
  • Must be provided by derived images: No

  • OCI notation: org.opencontainers.image.url

  • Description: Additional information

  • Example: https://www.suse.com/products/server/

org.openbuildservice.disturl, com.suse.sle.base.disturl
  • Must be provided by derived images: Yes

  • OCI notation: org.openbuildservice.disturl

  • Description: Image OBS URL

  • Example: obs://build.suse.de/SUSE:SLE-15:Update:CR/images/2951b67133dd6384cacb28203174e030-sles15-image

org.opensuse.reference, com.suse.sle.base.reference
  • Must be provided by derived images: Yes

  • OCI notation: org.opensuse.reference

  • Description: Reference pointing to the image. The image you get with docker pullREF_NAME must not change.

  • Example: registry.suse.com/suse/sle15:4.2 SLE Base Container Image labels

SLE Base Container Images feature the following labels.


Shows whether this is a pure SLE Base Container Image or an application container based on another SLE Base Container Image.


Marks which section of the SUSE EULA applies to the container image.


Indicates the current release stage of the image.

  • prototype Indicates that the container image is in the ALP prototype phase.

  • alpha Prevents the container image from appearing in the registry.suse.com Web interface even if it is available there. The value also indicates the alpha quality of the container image.

  • beta Lists the container image in the Beta Container Images section of the registry.suse.com Web interface and adds the Beta label to the image. The value also indicates the beta quality of the container image.

  • released Indicates that the container image is released and suitable for production use.


Shows the support level for the container.

  • l2 Problem isolation, which means technical support designed to analyze data, reproduce customer problems, isolate problem areas, and provide a resolution for problems not resolved by Level 1, or prepare for Level 3.

  • l3 Problem resolution, which means technical support designed to resolve problems by engaging engineering to resolve product defects which have been identified by Level 2 Support.

  • techpreview The image is unsupported and intended for use in proof-of-concept scenarios.

    unsupported No support is provided for the image.


Points to the https://www.suse.com/lifecycle/ page that offers information about the lifecycle of the image. Working with SLE Base Container Image labels

Use Podman and the jq tool to retrieve labels of a local image. The following command lists all labels of the bci-base:15.4 image:

podman inspect registry.suse.com/bci/bci-base:15.4 | \
jq '.[0].Labels'

It is also possible to retrieve the value of a specific label:

podman inspect registry.suse.com/bci/bci-base:15.4 | \
jq '.[0].Labels["com.suse.sle.base.supportlevel"]'

The preceding command retrieves the value of the com.suse.sle.base.supportlevel label.

The skopeo tool makes it possible to examine labels of an image without pulling it first. For example:

skopeo inspect docker://registry.suse.com/bci/bci-base:15.4 | \
jq '.Labels'
skopeo inspect docker://registry.suse.com/bci/bci-base:15.4 | \
jq '.Labels["com.suse.sle.base.supportlevel"]'

7.2.3 Tags

Tags are used to refer to images. A tag forms a part of the image's name. Unlike labels, tags can be freely defined, and they are usually used to indicate a version number.

If a tag exists in multiple images, the newest image is used. The image maintainer decides which tags to assign to the container image.

The conventional tag format is repository name: image version specification (usually version number). For example, the tag for the latest published image of SUSE Linux Enterprise Server 15 SP2 would be suse/sle15:15.2.

7.3 SUSE Registry

The official SUSE Registry is available at https://registry.suse.com. It contains tested and updated SUSE Linux Enterprise base container images. All images in the SUSE Registry undergo a maintenance process. The images are built to contain the latest available updates and fixes. The SUSE Registry's Web user interface lists a subset of the available images.

7.4 Verifying containers

Signatures for images available through SUSE Registry are stored in the Notary. You can verify the signature of a specific image using the following command:

docker trust inspect --pretty registry.suse.com/suse/IMAGE:TAG

For example, the command docker trust inspect --pretty registry.suse.com/suse/sle15:latest verifies the signature of the latest SLE15 base image.

To automatically validate an image when you pull it, set the environment DOCKER_CONTENT_TRUST to 1. For example:

env DOCKER_CONTENT_TRUST=1 docker pull registry.suse.com/suse/sle15:latest

7.5 Comparing containers

The container-diff tool can be used for analyzing and comparing container images. container-diff can examine images along several criteria, including the following:

  • Docker image history

  • Image file system

  • DEB packages

  • RPM packages

  • PyPI packages

  • NPM packages

You can inspect a single image or perform a diff operation on two images. container-diff supports Docker images located in both a local Docker daemon and a remote registry. It is also possible to use the tool with .tar, .tar.gz, and .tgz archives.

The container-diff package is part of the SUSE Linux Enterprise Server 15 SP4 Containers Module. Alternatively, it can be installed separately. For instructions on installing it, see the container-diff documentation.

8 Creating custom container images

To create a custom image, you need a base image of SUSE Linux Enterprise Server. You can use any of the pre-built SUSE Linux Enterprise Server images.

8.1 Pulling base SLES images

To obtain a pre-built base image for SUSE Linux Enterprise 12 SP5 and later, use the following command:

      > docker pull registry.suse.com/suse/IMAGENAME

For example, for SUSE Linux Enterprise Server 15, the command is as follows:

> docker pull registry.suse.com/suse/sle15

sle2docker is not required, because the image is being pulled from the Docker Registry.

For information on obtaining specific base images, refer to Section 7.1, “SUSE Linux Enterprise base images”.

When the container image is ready, you can customize it as described in Section 8.2, “Customizing SLES container images”.

8.2 Customizing SLES container images

The pre-built images do not have any repositories configured and do not include any modules or extensions. They contain a zypper service that contacts either the SUSE® Customer Center or a Repository Mirroring Tool (RMT) server, according to the configuration of the SUSE Linux Enterprise Server host that runs the container. The service obtains the list of repositories available for the product used by the container image. You can also directly declare extensions in your Dockerfile. For more information, see Section 8.2.3, “Adding SLE extensions and modules to images”.

Note: SLE_BCI repository

Starting with SUSE Linux Enterprise 15 SP3, the default base image includes the SLE_BCI repository. This repository is only used when a container is built or runs on a non-registered SLES host, or when registration credentials are not made available to containers. The repository provides a subset of SUSE Linux Enterprise 15 SP3 packages useful for customizing SLES container images. The repository is available without any registration, and it is not supported.

You do not need to add any credentials to the container image, because the machine credentials are automatically injected into the /run/secrets directory in the container by the docker daemon. The same applies to the /etc/SUSEConnect file of the host system, which is automatically injected into the /run/secrets directory.

Note: Credentials and security

The contents of the /run/secrets directory are never included in a container image, hence there is no risk of your credentials leaking.

Note: Building images on systems registered with RMT

When the host system used for building container images is registered with RMT, the default behavior allows only building containers of the same code base as the host. For example, if your container host is an SLE 15 system, you can only build SLE 15-based images on that host by default. To build images for a different SLE version, for example, SLE 12 on an SLE 15 host, the host machine credentials for the target release can be injected into the container as outlined below. Please note that if the RMT server is using a self-signed certificate, the matching CA certificate needs to be added into the container at CA_TRUSTSTORE/rmt-server.pem for the certificate to be accepted.

When the host system is registered with SUSE Customer Center, this restriction does not apply.

Note: Building container images in on-demand SLE instances in the public cloud

Building container images on SLE instances that were launched as on-demand or pay-as-you-go instances on a public cloud (AWS, GCE, or Azure) requires additional steps. To install packages and updates, the on-demand public cloud instances are connected to the update infrastructure. This infrastructure is based on RMT servers operated by SUSE on the various public cloud providers.

Therefore, your machines need to locate the required services and authenticate with them. This can be done using the containerbuild-regionsrv service. This service is available in the public cloud images provided through the marketplaces of the various public cloud providers. Before building an image, this service must be started on the public cloud instance by running the following command:

> sudo systemctl start containerbuild-regionsrv

To start it automatically on system start-up, enable it:

> sudo systemctl enable containerbuild-regionsrv

The Zypper plug-ins provided by the SLE base images connect to this service and retrieve authentication details and information about which update server to talk to. For this to work, the container has to be built with host networking enabled, for example:

        > docker build --network host build-directory/

Since update infrastructure in the public clouds is based upon RMT, the restrictions on building SLE images for SLE versions different from the SLE version of the host apply as well (see Note: Building images on systems registered with RMT).

To obtain the list of repositories, use the following command:

> sudo zypper ref -s

This automatically adds all the repositories to the container. For each repository added to the system, a new file will be created under /etc/zypp/repos.d . The URLs of these repositories include an access token that automatically expires after 12 hours. To renew the token, run the command zypper ref -s . Including these files in a container image does not pose any security risk.

To use a different set of credentials, put a custom /etc/zypp/credentials.d/SCCcredentials file inside the container image. It contains the machine credentials that have the subscription you want to use. The same applies to the SUSEConnect file: To override the existing file on the host system running the container, add a custom /etc/SUSEConnect file inside the container image.

Now you can create a custom container image by using a Dockerfile as described in Section 8.2.1, “Creating a custom image for SLE 12 SP5 and later”.

If you want to move your application to a container, see Chapter 9, Creating application images.

After you have edited the Dockerfile , build the image by running the following command in the same directory in which the Dockerfile resides:

> docker build .

For more information about docker build options, see the official Docker documentation .

Note: Creating application images

For information about creating a Dockerfile for the application you want to run inside a container, see Chapter 9, Creating application images.

8.2.1 Creating a custom image for SLE 12 SP5 and later

The following Dockerfile creates a simple container image based on SUSE Linux Enterprise Server 15:

        FROM registry.suse.com/suse/sle15

        RUN zypper ref -s
        RUN zypper -n in vim

When the Docker host machine is registered with an internal RMT server, the image requires the SSL certificate used by RMT:

        FROM registry.suse.com/suse/sle15

        # Import the crt file of our private SMT server
        ADD http://smt.example.com/smt.crt /etc/pki/trust/anchors/smt.crt
        RUN update-ca-certificates

        RUN zypper ref -s
        RUN zypper -n in vim

8.2.2 Meta information in SLE container images

Starting with SUSE Linux Enterprise 12 SP3, all base container images include information such as a build time stamp and description. This information is provided in the form of labels attached to the base images, and is therefore available for derived images and containers (see Section 7.2.2, “Labels”). This information can be viewed with docker inspect :

        > docker inspect registry.suse.com/suse/sle15
        "Labels": {
            "com.suse.sle.base.created": "2020-11-23T11:51:32.695975200Z",
            "com.suse.sle.base.description": "Image containing a minimal environment for containers based on SUSE Linux Enterprise Server 15 SP2.",
            "com.suse.sle.base.disturl": "obs://build.suse.de/SUSE:SLE-15-SP2:Update:CR/images/4a8871be8078bcef2e2417e2a98fc3a0-sles15-image",
            "com.suse.sle.base.reference": "registry.suse.com/suse/sle15:",
            "com.suse.sle.base.title": "SUSE Linux Enterprise Server 15 SP2 Base Container",
            "com.suse.sle.base.url": "https://www.suse.com/products/server/",
            "com.suse.sle.base.vendor": "SUSE LLC",
            "com.suse.sle.base.version": "",
            "org.openbuildservice.disturl": "obs://build.suse.de/SUSE:SLE-15-SP2:Update:CR/images/4a8871be8078bcef2e2417e2a98fc3a0-sles15-image",
            "org.opencontainers.image.created": "2020-11-23T11:51:32.695975200Z",
            "org.opencontainers.image.description": "Image containing a minimal environment for containers based on SUSE Linux Enterprise Server 15 SP2.",
            "org.opencontainers.image.title": "SUSE Linux Enterprise Server 15 SP2 Base Container",
            "org.opencontainers.image.url": "https://www.suse.com/products/server/",
            "org.opencontainers.image.vendor": "SUSE LLC",
            "org.opencontainers.image.version": "",
            "org.opensuse.reference": "registry.suse.com/suse/sle15:"

All labels are shown twice, to ensure that in derived images, the information about the original base image is still visible and not overwritten.

8.2.3 Adding SLE extensions and modules to images

If you have subscriptions to SUSE Linux Enterprise Server extensions or modules that you want to use in your custom image, you can add them to the container image by specifying the ADDITIONAL_MODULES environment variable:

ENV ADDITIONAL_MODULES sle-module-desktop-applications,sle-module-development-tools

9 Creating application images

Docker Open Source Engine is designed to allow running multiple separate application environments in parallel, with lower resource use than when using full virtual machines. Several types of applications are suitable for running inside containers: daemons, Web servers, and applications that expose IP ports for communications. You can use Docker Open Source Engine to automate the building and deployment processes by performing the build process inside a container, building an image, and then deploying containers based on the image.

Running an application inside a container has the following advantages:

  • The image with the application is portable across servers running different Linux host distributions and versions.

  • You can share the image of the application using a repository.

  • You can use different versions of software in the container and on the host system, without creating dependency issues.

  • You can run several instances of the same application that are completely independent from each other.

Using Docker Open Source Engine to build applications has the following advantages:

  • You can prepare an image of the complete build environment.

  • The application can run in the same environment it was built in.

  • Developers can test their code in the same environment as used in production.

The following section provides examples and recommendations on creating container images for applications. Before proceeding, make sure that you have activated your SUSE Linux Enterprise Server base image as described in Section 8.1, “Pulling base SLES images”.

9.1 Running an application with specific package versions

If your application needs a version of a package different from the package installed on the system, you can create a container image that includes the package version the application requires. The following example Dockerfile allows building an image based on an up-to-date version of SUSE Linux Enterprise Server with an older version of the example package:

FROM registry.suse.com/suse/sle15
LABEL maintainer=tux
RUN zypper ref && zypper in -f example-1.0.0-0
COPY application.rpm /tmp/
RUN zypper --non-interactive in /tmp/application.rpm
ENTRYPOINT ["/etc/bin/application"]
CMD ["-i"]

Build the image by running the following command in the directory that the Dockerfile resides in:

> docker build --tag tux_application:latest .

The Dockerfile example shown above performs the following operations during the docker build:

  1. Updates the SUSE Linux Enterprise Server repositories.

  2. Installs the desired version of the example package.

  3. Copies the application package to the image. The binary RPM must be placed in the build context.

  4. Unpacks the application.

  5. The last two steps run the application after a container is started.

After a successful build of the tux_application image, you can start a container based on the new image using the following command:

> docker run -it --name application_instance tux_application:latest

Keep in mind that after closing the application, the container exits as well.

9.2 Running an application with a specific configuration

To run an instance using a different configuration, create a derived image and include the additional configuration with it. For example, if your application is called example and can be configured using the file /etc/example/configuration_example, you could use:

FROM registry.suse.com/suse/sle15 1
RUN zypper ref && zypper --non-interactive in example 2
ENV BACKUP=/backup 3
RUN mkdir -p $BACKUP 4
COPY configuration_example /etc/example/ 5
ENTRYPOINT ["/etc/bin/example"] 6

The above example Dockerfile performs the following operations:


Pulls the sle15 base image from Section 8.1, “Pulling base SLES images”.


Refreshes repositories and installations of the example.


Sets a BACKUP environment variable (the variable persists to containers started from the image). You can always overwrite the value of the variable while running the container by specifying a new value.


Creates the directory /backup.


Copies the configuration_example to the image.


Runs the example application.

You can now build the image. After a successful build, you can run a container based on the image you just created.

9.3 Sharing data between an application and the host system

Docker Open Source Engine allows sharing data between host and a container by using volumes. You can specify a mount point directly in the Dockerfile. However, you cannot specify a directory on the host system in the Dockerfile, as the directory may not be accessible at build time. Find the mounted directory under /var/lib/docker/volumes/ on the host system.

Note: Discarding changes to the directory to be shared

After you specify a mount point by using the VOLUME instruction, all changes made to the directory with the RUN instruction are discarded. After the mount point is specified, the volume becomes a part of a temporary container, which is removed after a successful build. This means that for certain actions to take effect, they must be performed before specifying a mount point. For example, if you need to change permissions, do this before you specify the directory as a mount point in the Dockerfile.

Specify a particular mount point on the host system when running a container by using the -v option:

> docker run -it --name testing -v /home/tux/data:/data sles12sp4:latest /bin/bash

The -v option overwrites the VOLUME instruction if you specify the same mount point in the container.

The following example image contains a Web server that reads Web content from the host's file system. The Dockerfile could look as follows:

FROM registry.suse.com/suse/sles12sp4
RUN zypper ref && zypper --non-interactive in apache2
COPY apache2 /etc/sysconfig/
RUN chown -R admin /data
VOLUME /data
ENTRYPOINT ["apache2ctl"]

The example above installs the Apache Web server to the image and copies the entire configuration to the image. The data directory is owned by the admin user and is used as a mount point to store Web pages.

9.4 Applications running in the background

If your application needs to run in the background as a daemon, or as an application exposing ports for communication, you can run the container in the background.

An example Dockerfile for an application exposing a port looks as follows:

Example 9.1: Building an Apache2 Web server container (Dockerfile)
FROM registry.suse.com/suse/sle15 1
LABEL maintainer=tux 2
ADD etc/ /etc/zypp/ 3
RUN zypper refs && zypper refresh 4
RUN zypper --non-interactive in apache2 5
RUN echo "The Web server is running" > /srv/www/htdocs/test.html 6
# COPY data/* /srv/www/htdocs/ 7
ENTRYPOINT ["/usr/sbin/httpd"]


Pull the base image as in Section 8.1, “Pulling base SLES images”.


Maintainer of the image (optional).


The repositories and service files to be copied to /etc/zypp/repos.d and /etc/zypp/services.d. This makes them available on the host in the container.


Command to refresh repositories and services.


Command to install Apache2.


Test line for debugging purposes. This line can be removed if everything works as expected.


A COPY instruction to copy data from the host system to the directory in the container used by the server. The leading hash character ( # ) marks this line as a comment; it is not executed.


The exposed port for the Apache Web server.

Note: Make sure the ports used by the container image are unused

To use port 80, make sure there is no other server software running on this port on the host.

To use the container, proceed as follows:

Procedure 9.1: Testing the Apache2 Web server
  1. Prepare the host system for the build process.

    1. Make sure the host system is subscribed to the Server Applications Module of SUSE Linux Enterprise Server. To view installed modules or install additional modules, open YaST and select Add System Extensions or Modules.

    2. Make sure the SUSE Linux Enterprise images from the SUSE Registry are installed as described in Section 8.1, “Pulling base SLES images”.

    3. Save the Dockerfile from Example 9.1, “Building an Apache2 Web server container (Dockerfile)” into the docker directory.

    4. Within the container, you need access to software repositories and services that are registered on the host. To make them available, copy repositories and service files from the host to the docker/etc directory:

      > cd docker
      > mkdir etc
      > sudo cp -a /etc/zypp/{repos.d,services.d} etc/

      Instead of copying all repository and service files, you can also copy only the subset that is required by the container.

    5. Add Web site data (such as HTML files) into the docker/data directory. The contents of this directory are copied to the container image and are thus published by the Web server.

  2. Build the container. Set a tag for your image with the -t option (in the command below, it is tux/apache2):

    > sudo docker build -t tux/apache2 .

    Docker Open Source Engine executes the instructions provided in the Dockerfile: Pull the base image, copy content, refresh repositories, install the Apache2, etc.

  3. Start a container instance from the image created in the previous step:

    > docker run --detach --interactive --tty tux/apache2

    Docker Open Source Engine returns the container ID, for example:

  4. Point a browser to http://localhost:80/test.html . You should see the message The Web server is running .

  5. To see an overview of running containers, use:

    > docker ps --latest
    CONTAINER ID        IMAGE               COMMAND                  [...]
    tux/apache2         "/usr/sbin/httpd -..."   [...]

    To stop and delete the container, run the following command:

    > docker rm --force 7bd674eb196d

You can use the resulting container to serve your data with the Apache2 Web server by following these steps:

Procedure 9.2: Creating a container with your own data
  1. In the Dockerfile :

  2. Rebuild the image as described in Step 2 of Procedure 9.1.

  3. Run the image in detached mode:

    > docker run --detach --interactive --tty tux/apache2

    Docker Open Source Engine responds with the container ID, for example:


To view the published data, point a browser at http://localhost:80/test.html .

To avoid copying Web site data into the container, share a directory of the host with the container. For more information, see https://docs.docker.com/storage/volumes/ .

10 Working with containers

After you have created a custom image, you can start containers based on it. You can run an instance of the image using the docker run command. The command accepts several arguments:

  • a container name (it is recommended to name your container)

  • a user for the container

  • a mount point

  • a host name, etc.

10.1 Starting and removing containers

Containers normally exit when their main process finishes. For example, if a container starts a particular application, the container exits when the application quits. You can start the container again by running:

> docker start -ai <container name>

To remove unused containers:

> docker rm <container name>

11 Podman overview

Podman is short for Pod Manager Tool. It is a daemonless container engine for developing, managing, and running Open Container Initiative (OCI) containers on a Linux system, and it offers a drop-in alternative for Docker. Podman is the default container runtime in openSUSE Kubic—a certified Kubernetes distribution built on top of openSUSE. Podman can be used to create OCI-compliant container images using a Dockerfile and a range of commands identical to Docker Open Source Engine. For example, the podman build command performs the same task as docker build. In other words, Podman provides a drop-in replacement for Docker Open Source Engine.

Moving from Docker Open Source Engine to Podman does not require any changes in the established workflow. There is no need to rebuild images, and you can use the exact same commands to build and manage images as well as run and control containers.

Podman differs from Docker Open Source Engine in two important ways.

  • Podman does not use a daemon, so the container engine interacts directly with an image registry, containers, and an image storage. As Podman does not have a daemon, it provides integration with systemd. This makes it possible to control containers via systemd units. You can create these units for existing containers as well as generate units that can start containers if they do not exist in the system. Moreover, Podman can run systemd inside containers.

  • Because Podman relies on several namespaces, which provide an isolation mechanism for Linux processes, it does not require root privileges to create and run containers. This means that Podman can run in root mode as well as in an unprivileged environment. Moreover, a container created by an unprivileged user cannot get higher privileges on the host than the container's creator.

11.1 Podman installation

To install Podman, run the command sudo zypper in podman. Then run podman --version to check whether Podman has been installed successfully.

To run Podman without root privileges, subuids and subgids must be assigned to the user running Podman. If there is no entry in the /etc/subuid file, add an entry using the following command:

>  sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 USER

To enable the change, reboot the machine or stop the session of the current user. To do the latter, run loginctl list-sessions | grep USER and note the session ID. Then run loginctl kill-session SESSION_ID to terminate the session.

The command above defines a range of local UIDs to which the UIDs allocated to users inside the container are mapped on the host. Note that the ranges defined for different users must not overlap. It is also important that the ranges do not reuse the UID of an existing local user or group. By default, adding a user with the useradd command on SLES 15 automatically allocates subUID and subGID ranges.

Running a container with Podman in rootless mode on SUSE Linux Enterprise Server may fail, because the container needs read access to the SUSE Customer Center credentials. For example, running a container with the command podman run -it --rm registry.suse.com/suse/sle15 bash and then executing zypper ref results in the following error message:

Refreshing service 'container-suseconnect-zypp'.
Problem retrieving the repository index file for service 'container-suseconnect-zypp':
Warning: Skipping service 'container-suseconnect-zypp' because of the above error.
Warning: There are no enabled repositories defined.
Use 'zypper addrepo' or 'zypper modifyrepo' commands to add or enable repositories

To solve the problem, grant the current user the required access rights by running the following command on the host:

> sudo setfacl -m u:USER:r /etc/zypp/credentials.d/*

Log out and log in again to apply the changes.

To give multiple users the required access, create a dedicated group using the groupadd GROUPNAME command. Then use the following command to change the group ownership and rights of files in the /etc/zypp/credentials.d/ directory.

> sudo chgrp GROUPNAME /etc/zypp/credentials.d/*
> sudo chmod g+r /etc/zypp/credentials.d/*

You can then grant a specific user write access by adding them to the created group.

11.2 Podman basic usage

Since Podman is compatible with Docker Open Source Engine, it features the same commands and options. For example, the podman pull command fetches a container image from a registry, while the podman build command is used to build images.

One of the advantages of Podman over Docker Open Source Engine is that Podman can be configured to search multiple registries. To make Podman search the SUSE Registry first and use Docker Hub as a fallback, add the following configuration to the /etc/containers/registries.conf file:

registries = ["registry.suse.com", "docker.io"]

Similar to Docker Open Source Engine, Podman can run containers in an interactive mode, allowing you to inspect and work with an image. To run suse/sle15 in interactive mode, use the following command:

> podman run --rm -ti suse/sle15

11.2.1 Building images with Podman

Podman can build images from a Dockerfile. The podman build command behaves as docker build, and it accepts the same options.

Podman's companion tool Buildah provides an alternative way to build images. For further information about Buildah, refer to Chapter 12, Buildah overview.

12 Buildah overview

Buildah is tool for building OCI-compliant container images. Buildah can handle the following tasks:

  • Create containers from scratch or from existing images.

  • Create an image from a working container or via Dockerfile.

  • Build images in the OCI or Docker Open Source Engine image formats.

  • Mount a working container's root file system for manipulation.

  • Use the updated contents of a container's root file system as a file system layer to create a new image.

  • Delete a working container or an image and rename a local container.

Compared to Docker Open Source Engine, Buildah has several advantages:

  • The tool makes it possible to mount a working container's file system, so it becomes accessible by the host.

  • The process of building container images using Buildah can be automated via scripts by using Buildah's subcommands instead of a Containerfile or Dockerfile.

  • Similar to Podman, Buildah does not require a daemon to run and can be used by unprivileged users.

  • It is possible to build images inside a container without mounting the Docker socket, which improves security.

12.1 Podman and Buildah

Both Podman and Buildah can be used to build container images. While Podman makes it possible to build images using Dockerfiles, Buildah offers an expanded range of image building options and capabilities.

12.2 Buildah installation

To install Buildah, run the command sudo zypper in buildah. Run the command buildah --version to check whether Buildah has been installed successfully.

If you already have Podman installed and set up for use in rootless mode, Buildah can be used in an unprivileged environment without any further configuration. If you need to enable rootless mode for Buildah, run the following command:

> sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 USER

This command enables rootless mode for the current user. After running the command, log out and log in again to enable the changes.

The command above defines a range of local UIDs on the host, onto which the UIDs allocated to users inside the container are mapped. Note that the ranges defined for different users must not overlap. It is also important that the ranges do not reuse the UID of any existing local users or groups. By default, adding a user with the useradd command on SLES 15 automatically allocates subUID and subGID ranges.

Note: Buildah in rootless mode

In rootless mode, Buildah commands must be executed in a modified user namespace of the user. To enter this user namespace, run the command buildah unshare. Otherwise, the buildah mount command will fail.

12.3 Building images with Buildah

Instead of a special file with instructions, Buildah uses individual commands to build an image. Building an image with Buildah involves several steps: Run a container based on the specified image, edit the container (install packages, configure settings, etc.), configure the container options, and commit all changes into a new image. While this process may include additional steps, such as mounting the container's file system and working with it, the basic workflow logic remains the same.

The following example can give you a general idea of how to build an image with Buildah.

Example 12.1: Build image example
container=$(buildah from suse/sle15) 1
buildah run $container zypper up 2
buildah copy $container . /usr/src/example/ 3
buildah config --workingdir /usr/src/example $container
buildah config --port 8000 $container
buildah config --cmd "php -S" $container 4
buildah config --label maintainer="Tux" $container
buildah config --label version="0.1" $container 5
buildah commit $container example 6
buildah rm $container 7


Run a container (also called a working container) based on the specified image (in this case, sle15).


Run a command in the working container you just created. In this example, Buildah runs the zypper up command.


Copy files and directories to the specified location in the container. In this example, Buildah copies the entire contents of the current directory to /usr/src/example/.


The buildah config commands specify container options. These include defining a working directory, exposing a port, and running a command inside the container.


The buildah config --label command allows you to assign labels to the container. This may include maintainer, description, version, and so on.


Create an image from the working container by committing all the modifications.


Delete the working container.

13 Container orchestration

13.1 Pod deployment with Podman

In addition to building and managing images, Podman makes it possible to work with pods. A pod is a group of one or more containers with shared resources, such as the network interface. A pod usually encapsulates an application composed of multiple containers into a single unit.

The podman pod can be used to create, delete, query, and inspect pods. To create a new pod, run the podman pod create command. This creates a pod with a random name. To list the existing pods, use the podman pod list command. To view a list of running pods, run podman ps -a --pod. The output of the command looks as follows (the STATUS and CREATED columns are omitted for brevity):

POD ID        NAME                # OF CONTAINERS   INFRA ID
399a120a09ff  suspicious_curie    1                 e57820093817

Notice that the command assigned a random name to the pod (suspicious_curie in this case). You can use the --name parameter to assign the desired name to a pod.

To examine the pod and its contents, run the podman ps -a --pod command and take a look at the output (the COMMAND, CREATED, STATUS, PORTS, and POD ID columns are omitted for brevity):

CONTAINER ID  IMAGE                 NAMES              PODNAME
e57820093817  k8s.gcr.io/pause:3.2  399a120a09ff-infra suspicious_curie

The created pod has an infra container identified by the k8s.gcr.io name. The purpose of this container is to reserve the namespaces associated with the pod and allow Podman to add other containers to the pod.

Using the podman run --pod command, you can run a container and add it to the desired pod. For example, the command below runs a container based on the suse/sle15 image and adds the container to the suspicious_curie pod:

podman run -d --pod suspicious_curie registry.suse.com/suse/sle15 sleep 1h

The command above adds a container that sleeps for 60 minutes and then exits. Run the podman ps -a --pod command again and you should see that the pod now has two containers.

Containers in a pod can be restarted, stopped, and started without affecting the overall status of the pod. For example, you can stop a container using the sudo podman stop CONTAINER_NAME command.

To stop the pod, use the podman pod stop command:

podman pod stop suspicious_curie

14 Troubleshooting

14.1 Analyze container images with container-diff

In case a custom Docker Open Source Engine container image built on top of the SLE base container image is not working as expected, the container-diff tool can help you analyze the image and collect information relevant for troubleshooting.

container-diff makes it possible to analyze image changes by computing differences between images and presenting the diff in a human-readable and actionable format. The tool can find differences in system packages, language-level packages, and files in a container image.

container-diff can handle local container images (using the prefix daemon://), images in a remote registry (using the prefix remote://), and images saved as .tar archives. You can use container-diff to compute the diff between a local version of an image and a remote version.

To install container-diff, run the sudo zypper in container-diff command.

14.1.1 Basic container-diff commands

The command container-diff analyze IMAGE runs a standard analysis on a single image. By default, it returns a hash and size of the container image. For more information that can help you to identify and fix problems, use the specific analyzers. Use the --type parameter to specify the desired analyzer. Two of the most useful analyzers are history (returns a list of descriptions of how an image layer was created) and file (returns a list of file system contents, including names, paths, and sizes):

> sudo container-diff analyze --type=history daemon://IMAGE
> sudo container-diff analyze --type=file daemon://IMAGE

To view all available parameters and their brief descriptions, run the container-diff analyze --help command.

Using the container-diff diff command, you can compare two container images and examine differences between them. Similar to the container-diff analyze command, container-diff diff supports several parameters. The example command below compares two images and returns a list of descriptions of how IMAGE_2 was created from IMAGE_1.

> sudo container-diff diff daemon://IMAGE_1 daemon://IMAGE_2 --type=history

To view all available parameters and their brief descriptions, run the container-diff diff --help command.

15 Compatibility and support conditions

15.1 Support information

The term "support" refers to two distinct concepts: a) technical enablement of a feature or combination of, for example, host and container, and b) enterprise support as delivered by SUSE to SUSE customers. Enterprise support requires a subscription for SUSE products according to https://www.suse.com/products/terms_and_conditions.pdf. Technical enablement is described below.

15.1.1 Support for SLES hosts

Consult the following support and compatibility matrix to make sure that the desired host system and container combination is compatible and supported.


In most scenarios, all SLE containers are expected to be interoperable if the application or its dependencies do not interact directly with kernel version-specific data structures (ioctl, /proc, /sys, routing, iptables, nftables, eBPF, etc.) or modules (KVM, OVS, SystemTap, etc.). Support for ioctl and access to /proc is limited to the most common scenarios needed by unprivileged users.

15.1.2 Support for non-SLES hosts

While SUSE-based containers are fully supported, issues in the host environment must be handled by the host environment vendor. SUSE supports components that are part of the SUSE base containers. Packages from SUSE repositories are also supported. Additional components and applications in the containers are not covered by SUSE support. A SUSE Linux Enterprise subscription is required for building derived containers.

Containers based on SUSE Linux Enterprise Server 12 SP5 and SUSE Linux Enterprise Server 15 (all service packs) are supported according to their official lifecycles and the following table.

The following third-party container host platforms are supported.


15.2 Support plans

There are three guiding principles of SUSE container support.

  1. The container image lifecycle follows the lifecycle of the related products.

    For example, SLES 15 SP4 container images follow the SLES 15 SP4 lifecycle.

  2. Container release status also matches the status of the related product.

    For example, if SLES 15 SP4 is in Alpha, Beta, RC, or GA stage, the related containers have the same release status.

  3. Containers are built using the packages from the related products.

    For example, SLES 15 SP4 container images are built using the same packages as the main SLES 15 SP4 release.

For further information, refer to the Product Support Lifecycle page and the documentation available for specific container images on SUSE Registry.

Container images can have different support status, and they can have limited support. Refer to the appropriate SUSE Registry page for the further information about a specific container image.

15.3 Containers and host environments support overview

The following support options are valid for SUSE Linux Enterprise Server containers on SUSE host environments.

Containers and host environments delivered by SUSE are fully supported. This also applies to all products under support, including both general support and Long Term Service Pack Support (LTSS).

Partner containers and host environments with a joint engineering collaboration agreement are fully supported. This applies to both the container and host environment as well as all products under support (both general and LTSS) covered by the agreement.

While SUSE-based containers are fully supported, issues in the host environment must be handled by the host environment vendor. SUSE supports components that come from the SUSE base containers. Packages from SUSE repositories are also supported. Additional components and applications in the containers are not covered by SUSE support. No subscription is required for building derived containers based on the content of the SLE Base Container Images or the SLE Base Container Image Repository. To build containers that include packages from the full SUSE Linux Enterprise universe, you need a subscription that grants you access to the repositories containing these packages.

Any container and host environment not mentioned above has limited support. Details can be discussed with the SUSE Support Team, who might triage the issue and recommend alternative solutions. In any other case, issues in the host environment must be handled by the host environment vendor.

15.4 Technology previews

Container images labeled as Tech Preview are provided by SUSE to give you an opportunity to test new technologies within your environment and share your feedback. If you test a technology preview, contact your SUSE representative to share your experiences and use cases. Your input is helpful for future development.

Technology previews come with the following limitations:

  • Technology previews can be functionally incomplete, unstable, and not suitable for production use.

  • Technology previews are not supported.

  • Technology previews can be available only for specific hardware architectures.

  • Specifics and functionality of technology previews are subject to change. As a result, upgrading to subsequent releases of a technology preview may not be possible and may require a fresh installation.

  • Technology previews can be canceled at any time. For example, if SUSE discovers that a preview does not meet the customer or market needs, or it does not comply with enterprise standards. SUSE does not commit to providing a supported version of such technologies in the future.

Container images are labeled as Tech Preview and are marked as such at registry.suse.com. Additionally, container images that are technology previews include the com.suse.supportlevel="techpreview" label in the container image metadata. You can check whether the metadata includes the label using the docker inspect command, or an appropriate command in other container runtimes.

A Terminology


A container is a running instance based on a particular container image. Each container can be distinguished by a unique container ID.

Control groups

Control groups, also called cgroups , are a Linux kernel feature that allows aggregating or partitioning tasks (processes) and all their children into hierarchically-organized groups, to manage their resource limits.

Docker Open Source Engine

Docker Open Source Engine is a server-client type application that performs all tasks related to containers. Docker Open Source Engine comprises the following:

  • Daemon:  The server side of Docker Open Source Engine, which manages all Docker objects (images, containers, network connections used by containers, etc.).

  • REST API:  Applications can use this API to communicate directly with the daemon.

  • CLI client:  Enables you to communicate with the daemon. If the daemon is running on a different machine than the CLI client, the CLI client can communicate by using network sockets or the REST API provided by Docker Open Source Engine.


A Dockerfile provides instructions on how to build a container image. Docker Open Source Engine reads instructions in the Dockerfile and builds a new image according to the instructions.


An image is a read-only template used to create a container. A Docker image is made of a series of layers built one over the other. Each layer corresponds to a permanent change, for example, an update of an application. The changes are stored in a file called a Dockerfile. For more details, see the official Docker documentation.

Container image

A container image is an unchangeable, static file that includes executable code so it can run an isolated process on IT infrastructure. The image is comprised of system libraries, system tools, and other platform settings a program needs to run on a containerization platform. A container image is compiled from file system layers built on top of a parent or base image.

Base image

A base image is an image that does not have a parent image. In a Dockerfile, a base image is identified by the FROM scratch directive.

Parent image

The image that serves as the basis for another container image. In other words, if an image is not a base image, it is derived from a parent image. In a Dockerfile, the FROM directive is pointing to the parent image. Most Docker containers are created using parent images.


Docker Open Source Engine uses Linux namespaces for its containers, which isolates resources reserved for particular containers.


In a production environment, you typically need a cluster with many containers on each cluster node. The containers must cooperate and you need a framework that enables you to automatically manage the containers. The act of automatic container management is called container orchestration and is typically handled by Kubernetes.


A registry is storage for already-created images. It typically contains several repositories. There are two types of registries:

  • public registry: Any (usually registered) user can download and use images. A typical example of a public registry is Docker Hub.

  • private registry: Access is restricted to particular users, or from a particular private network.


A repository is storage for images in a registry.