Build a Docker Container Image

KIWI is capable of building native Docker images, from scratch and derived ones. KIWI Docker images are considered to be native since the KIWI tarball image is ready to be loaded to a Docker daemon, including common container configurations.

The Docker configuration metadata is provided to KIWI as part of the XML description file using the <containerconfig> tag. The following configuration metadata can be specified:

containerconfig attributes:

  • name: Specifies the repository name of the Docker image.
  • tag: Sets the tag of the Docker image.
  • maintainer: Specifies the author field of the container.
  • user: Sets the user name or user id (UID) to be used when running entrypoint and subcommand. Equivalent of the USER directive of a Docker file.
  • workingdir: Sets the working directory to be used when running cmd and entrypoint. Equivalent of the WORKDIR directive of a Docker file.

containerconfig child tags:

  • subcommand: Provides the default execution parameters of the container. Equivalent of the CMD directive of a Docker file.
  • labels: Adds custom metadata to an image using key-value pairs. Equivalent to one or more LABEL directives of a Docker file.
  • expose: Informs at which ports is the container listening at runtime. Equivalent to one or more EXPOSE directives of a Docker file.
  • environment: Sets an environment values using key-value pairs. Equivalent to one or more the env directives of a Docker file.
  • entrypoint: Sets the command that the container will run, it can include parameters. Equivalent of the ENTRYPOINT directive of a Docker file.
  • volumes: Create mountpoints with the given name and mark it to hold external volumes from the host or from other containers. Equivalent to one or more VOLUME directives of a Docker file.

Other Docker file directives such as RUN, COPY or ADD, can be mapped to KIWI by using the config.sh script file to run bash commands or the overlay tree to include extra files.

The following example shows how to build a Docker base image based on openSUSE Leap:

  1. Make sure you have checked out the example image descriptions, see Example Appliance Descriptions.

  2. Include the Virtualization repository to your list:

    $ zypper ar -f http://download.opensuse.org/repositories/Virtualization:/containers/<DIST>
    

    where the placeholder <DIST> is the preferred distribution.

  3. Install umoci and skopeo tools

    $ zypper in umoci skopeo
    
  4. Build the image with KIWI:

    $ sudo kiwi-ng --type docker system build \
        --description kiwi-descriptions/suse/x86_64/suse-leap-42.2-docker \
        --target-dir /tmp/myimage
    
  5. Test the Docker image.

    First load the new image

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

    then run the loaded image:

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