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 http://download.opensuse.org/repositories/Virtualization:/containers/<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
/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
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
workdir: Sets the working directory to be used when running
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:
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
In order to execute commands during build time in KIWI it can be done by extending the
config.shscript. Note that the
config.shis executed after all the packages have been installed and after the overlay tree has been applied.
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
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="myscript.sh"/> <subcommand clear="true"/> </containerconfig> </type>
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
builds are an exception, they can be wiped using the
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
be use as base image in the KIWI XML description as follows:
<type image="docker" derived_from="file:///tmp/opensuse-42.2.tar.xz"> ... </type>