Build a Docker Container Image


Make sure you have checked out the example image descriptions For details see Example Appliance Descriptions

The following example shows how to build and run a container image based on SUSE Leap for the docker container system.

Installing the Requirements

Building Docker images with KIWI requires a couple of additional tools. In practice, umoci and skopeo utilities are mandatory. These tools are not yet in all regular openSUSE repositories, however a packaged version can be found in the Virtualization:containers repository here. In order to install them first add the repository using the zypper ar command:

$ zypper ar -f<DIST>

where the placeholder <DIST> is the preferred distribution. Once the repository has been added install the required utilities:

$ zypper in umoci skopeo

Building the Image

Run the following KIWI command in order to build the base image example.

$ sudo kiwi-ng --type docker system build \
    --description kiwi-descriptions/suse/x86_64/suse-leap-42.2-docker \
    --target-dir /tmp/myimage

Find the image with the suffix .docker.tar.xz below /tmp/myimage. For testing the docker image it’s required to have the docker subsystem installed and running. The following command can be used to check if docker is installed and functional on your system:

$ docker images

The command above lists all available docker images. If the docker daemon is running and responsive a list output is expected which could also be empty if no images are available. In any other case an error message is displayed which needs to be resolved prior to continue with the next steps.

Once docker works on your system the KIWI built image needs to be loaded into the docker system with the following command:

$ docker load -i Docker-Leap-42.2.x86_64-1.0.0.docker.tar.xz

On success the docker image is available as part of the images list as follows:

$ docker images

REPOSITORY          TAG  ...
opensuse            42.2 ...

In order to run an interactive shell session of the loaded container the following command needs to be called:

$ docker run -it opensuse:42.2 /bin/bash

Container Configuration

A docker container includes a set of information also called metadata. The metadata information is provided within the KIWI XML description as part of the <containerconfig> section. The following parameters can be specified:

  • maintainer: Specifies the author field of the container.
  • cmd: Provides the default execution parameters of the container.
  • label: Adds custom metadata to an image, is key-value pair.
  • expose: Informs at which ports is the container listening at runtime.
  • env: Sets an environment value, is key-value pair.
  • entrypoint: Sets the executable that the container will run, it can include parameters.
  • volume: Creates a mountpoint with the given name and marks it to hold external volumes from the host or from other contianers.
  • user: Sets the user name or UID to be used when running cmd and entrypoint.
  • workdir: Sets the working directory to be used when running cmd and entrypoint.

Map DockerFile Directives to KIWI

The native build description in docker is provided by a so called DockerFile. The DockerFile is a shell like key=value based file. In addition to the metadata information as shown above other additional information could be part of a DockerFile. KIWI can not natively handle the contents of the DockerFile, thus the following list shows how to map the DockerFile directive in KIWI:

  • ADD

    In order to include a tarball and auto extract it in KIWI it can be done by including the files in the overlay tree, or by including an <archive> item inside the <packages type="image"> section. ADD also handles remote content, in KIWI this should be done within the script.

  • RUN

    In order to execute commands during build time in KIWI it can be done by extending the script. Note that the is executed after all the packages have been installed and after the overlay tree has been applied.

  • COPY

    The equivalent in KIWI is to make use of the overlay tree in order to include files in a specific location.

Using an Existing Docker Image as Base Image

KIWI also supports building of a container image on top of another base image. In that case, the resulting image will include the base image layers plus a new one containing the changes added by KIWI. Building derived images works in the same way as for the base images, the only difference is that the base image must be specified in the description file, it can be done using the derived_from optional attribute of <type> tag. The value of the derived_from attribute is the URI of the image; currently KIWI only supports references to local files (it expects a xz compressed tarball image) and any other URI type that is supported by the skopeo tool (for example DockerHub URIs as derived_from="docker://opensuse:leap"). The following example type specification shows how to specify a base image setup:

<type image="docker" derived_from="docker://opensuse:leap">
    <containerconfig name="container_name" tag="container_tag" maintainer="tux">
        <entrypoint execute=""/>
        <subcommand clear="true"/>


The configuration metadata is inherited from the base image to the derived one, the only way to change the inherited metadata is by overwriting it. Only the entrypoint and subcommand statements builds are an exception, they can be wiped using the clear attribute as used in the above example.

Export Image from Docker to Be Usable as Base Image

Given there is an image in docker which should be used as a base image for a KIWI build, we recommend to export the image from docker in the following way:

$ docker save opensuse:42.2 | xz > /tmp/opensuse-42.2.tar.xz

Once the command completed the /tmp/opensuse-42.2.tar.xz could be use as base image in the KIWI XML description as follows:

<type image="docker" derived_from="file:///tmp/opensuse-42.2.tar.xz">