1Docker Containers
2=================
3
4These Docker containers should make it possible to build Xen in
5any of the available environments on any system that supports
6running Docker. They are organized by distro and tagged with
7the version of that distro. They are available from the GitLab
8Container Registry under the Xen project at the [registry] and
9can be pulled with Docker from the following path:
10
11```
12docker pull registry.gitlab.com/xen-project/xen/DISTRO:VERSION
13```
14
15To see the list of available containers run `make` in this
16directory. You will have to replace the `/` with a `:` to use
17them.
18
19Building Xen
20------------
21
22From the top level of the source tree it should be possible to
23run the following:
24
25```
26./automation/scripts/containerize make
27```
28
29Which will cause the top level `make` to execute within the default
30container, which is currently defined as Debian Stretch. Any arguments
31specified to the script will be executed within the container from
32the default shell.
33
34There are several environment variables which the containerize script
35understands.
36
37- DOCKED_CMD: Whether to use docker or podman for running the containers.
38  podman can be used as a regular user (rootless podman), but for that
39  to work, /etc/subuid and /etc/subgid needs to containe the proper
40  entries, for such user.
41  docker is the default, for running with podman, do:
42
43  ```
44  DOCKER_CMD=podman ./automation/scripts/containerize make
45  ```
46
47- CONTAINER: This overrides the container to use. For CentOS 7, use:
48
49  ```
50  CONTAINER=centos7 ./automation/scripts/containerize make
51  ```
52
53- CONTAINER_PATH: This overrides the path that will be available under the
54  `/build` directory in the container, which is the default path.
55
56  ```
57  CONTAINER_PATH=/some/other/path ./automation/scripts/containerize ls
58  ```
59
60- CONTAINER_ARGS: Allows you to pass extra arguments to Docker
61  when starting the container.
62
63- CONTAINER_UID0: This specifies whether root is used inside the container.
64
65- CONTAINER_NO_PULL: If set to 1, the script will not pull from docker hub.
66  This is useful when testing container locally.
67
68If your docker host has Linux kernel > 4.11, and you want to use containers
69that run old glibc (for example, CentOS 6 or SLES11SP4), you may need to add
70
71```
72vsyscall=emulate
73```
74
75to the host kernel command line. That enables a legacy interface that is used
76by old glibc.
77
78
79Building a container
80--------------------
81
82There is a makefile to make this process easier. You should be
83able to run `make DISTRO/VERSION` to have Docker build the container
84for you.
85
86Xen's dockerfiles use heredocs, which depend on the standardised dockerfile
87syntax introduced by [BuiltKit].  This should work by default starting with
88docker 23.0, or podman/buildah v1.33.  For older versions of docker, it can be
89activated with `DOCKER_BUILDKIT=1` in the environment.
90
91If you define the `PUSH` environment variable when running the
92former `make` command, it will push the container to the [registry] if
93you have access to do so and have your Docker logged into the registry.
94
95To login you must run `docker login registry.gitlab.com`. For more
96information see the [registry help].
97
98This example shows how to refresh a container for a rolling release
99such as openSUSE Tumbleweed. Login with the gitlab.com credentials.
100
101```
102docker login registry.gitlab.com/xen-project/xen
103make -C automation/build opensuse/tumbleweed-x86_64
104env CONTAINER_NO_PULL=1 \
105  CONTAINER=tumbleweed \
106  CONTAINER_ARGS='-e CC=gcc -e CXX=g++ -e debug=y' \
107  automation/scripts/containerize automation/scripts/build < /dev/null
108make -C automation/build opensuse/tumbleweed-x86_64 PUSH=1
109```
110
111To rebuild all containers the `all` make target can be used, with or without
112the `PUSH` environment variable:
113
114```
115make -C automation/build all PUSH=1
116```
117
118[BuildKit]: https://docs.docker.com/build/buildkit/
119[registry]: https://gitlab.com/xen-project/xen/container_registry
120[registry help]: https://docs.gitlab.com/ee/user/packages/container_registry/
121
122
123Building/Running container for a different architecture
124-------------------------------------------------------
125
126On a x86 host, it is possible to build and run containers for other arch (like
127running a container made for Arm) with docker taking care of running the
128appropriate software to emulate that arch. For this, simply install the package
129`qemu-user-static`, and that's it. Then you can start an Arm container on x86
130host like you would start an x86 container.
131
132If that doesn't work, you might find some information on
133[multiarch/qemu-user-static](https://github.com/multiarch/qemu-user-static).
134