Newer
Older
# Generating Container Recipes & Images
EasyBuild has support for generating container recipes that will use EasyBuild to build and install a specified software stack. In addition, EasyBuild can (optionally) leverage the build tool provided by the container software of choice to create container images.
## Generating Container Recipes
To generate container recipes, use `eb --containerize`, or `eb -C` for short.
The resulting container recipe will leverage EasyBuild to build and install the software that corresponds to the easyconfig files that are specified as arguments to the eb command (and all required dependencies, if needed).
!!! note
EasyBuild will refuse to overwrite existing container recipes.
To re-generate an already existing recipe file, use the `--force` command line option.
## Base Container Image
In order to let EasyBuild generate a container recipe, it is required to specify which container image should be used as a base, via the `--container-base` configuration option.
Currently, three types of container base images can be specified:
* **localimage: *path***: the location of an existing container image file
* **docker:*name***: the name of a Docker container image (to be downloaded from [Docker Hub][a].
* **shub:*name***: the name of a Apptainer/Singularity container image (to be downloaded from [Singularity Hub][b].
## Building Container Images
To instruct EasyBuild to also build a container image from the generated container recipe, use `--container-build-image` (in combination with `-C` or `--containerize`).
EasyBuild will leverage functionality provided by the container software of choice (see containers_cfg_image_type) to build the container image.
For example, in the case of Apptainer/Singularity, EasyBuild will run `sudo /path/to/singularity build` on the generated container recipe.
The container image will be placed in the location specified by the `--containerpath` configuration option (see Location for generated container recipes & images (`--containerpath`)), next to the generated container recipe that was used to build the image.
## Example Usage
In this example, we will use a pre-built base container image located at `/tmp/example.simg` (see also Base container image (`--container-base`)).
To let EasyBuild generate a container recipe for GCC 6.4.0 + binutils 2.28:
```console
eb GCC-6.4.0-2.28.eb --containerize --container-base localimage:/tmp/example.simg --experimental
```
With other configuration options left to default (see the output of `eb --show-config`), this will result in a Apptainer/Singularity container recipe using example.simg as a base image, which will be stored in `$HOME/.local/easybuild/containers`:
```console
$ eb GCC-6.4.0-2.28.eb --containerize --container-base localimage:/tmp/example.simg --experimental
== temporary log file in case of crash /tmp/eb-dLZTNF/easybuild-LPLeG0.log
== Singularity definition file created at /home/example/.local/easybuild/containers/Singularity.GCC-6.4.0-2.28
== Temporary log file(s) /tmp/eb-dLZTNF/easybuild-LPLeG0.log* have been removed.
== Temporary directory /tmp/eb-dLZTNF has been removed.
```
## Example of a Generated Container Recipe
Below is an example of container recipe generated by EasyBuild, using the following command:
```console
eb Python-3.6.4-foss-2018a.eb OpenMPI-2.1.2-GCC-6.4.0-2.28.eb -C --container-base shub:shahzebsiddiqui/eb-singularity:centos-7.4.1708 --experimental
```
It uses the *shahzebsiddiqui/eb-singularity:centos-7.4.1708* base container image that is available from the Apptainer/Singularity hub ([see this webpage][c]).
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
```
Bootstrap: shub
From: shahzebsiddiqui/eb-singularity:centos-7.4.1708
%post
yum --skip-broken -y install openssl-devel libssl-dev libopenssl-devel
yum --skip-broken -y install libibverbs-dev libibverbs-devel rdma-core-devel
# upgrade easybuild package automatically to latest version
pip install -U easybuild
# change to 'easybuild' user
su - easybuild
eb Python-3.6.4-foss-2018a.eb OpenMPI-2.1.2-GCC-6.4.0-2.28.eb --robot --installpath=/app/ --prefix=/scratch --tmpdir=/scratch/tmp
# exit from 'easybuild' user
exit
# cleanup
rm -rf /scratch/tmp/* /scratch/build /scratch/sources /scratch/ebfiles_repo
%runscript
eval "$@"
%environment
source /etc/profile
module use /app/modules/all
ml Python/3.6.4-foss-2018a OpenMPI/2.1.2-GCC-6.4.0-2.28
%labels
```
!!! note
We also specify the easyconfig file for the OpenMPI component of `foss/2018a` here, because it requires specific OS dependencies to be installed (see the second `yum ... install` line in the generated container recipe).
We intend to let EasyBuild take into account the OS dependencies of the entire software stack automatically in a future update.
The generated container recipe includes `pip install -U easybuild` to ensure that the latest version of EasyBuild is used to build the software in the container image, regardless of whether EasyBuild was already present in the container and which version it was.
In addition, the generated module files will follow the default module-naming scheme (EasyBuildMNS). The modules that correspond to the easyconfig files that were specified on the command line will be loaded automatically; see the statements in the %environment section of the generated container recipe.
## Example of Building Container Image
You can instruct EasyBuild to also build the container image by using `--container-build-image`.
Note that you will need to enter your sudo password (unless you recently executed a sudo command in the same shell session):
```console
$ eb GCC-6.4.0-2.28.eb --containerize --container-base localimage:/tmp/example.simg --container-build-image --experimental
== temporary log file in case of crash /tmp/eb-aYXYC8/easybuild-8uXhvu.log
== Singularity tool found at /usr/bin/singularity
== Singularity version '2.4.6' is 2.4 or higher ... OK
== Singularity definition file created at /home/example/.local/easybuild/containers/Singularity.GCC-6.4.0-2.28
== Running 'sudo /usr/bin/singularity build /home/example/.local/easybuild/containers/GCC-6.4.0-2.28.simg /home/example/.local/easybuild/containers/Singularity.GCC-6.4.0-2.28', you may need to enter your 'sudo' password...
== (streaming) output for command 'sudo /usr/bin/singularity build /home/example/.local/easybuild/containers/GCC-6.4.0-2.28.simg /home/example/.local/easybuild/containers/Singularity.GCC-6.4.0-2.28':
Using container recipe deffile: /home/example/.local/easybuild/containers/Singularity.GCC-6.4.0-2.28
Sanitizing environment
Adding base Singularity environment to container
...
== temporary log file in case of crash /scratch/tmp/eb-WnmCI_/easybuild-GcKyY9.log
== resolving dependencies ...
...
== building and installing GCCcore/6.4.0...
...
== building and installing binutils/2.28-GCCcore-6.4.0...
...
== building and installing GCC/6.4.0-2.28...
...
== COMPLETED: Installation ended successfully
== Results of the build can be found in the log file(s) /app/software/GCC/6.4.0-2.28/easybuild/easybuild-GCC-6.4.0-20180424.084946.log
== Build succeeded for 15 out of 15
...
Building Singularity image...
Singularity container built: /home/example/.local/easybuild/containers/GCC-6.4.0-2.28.simg
Cleaning up...
== Singularity image created at /home/example/.local/easybuild/containers/GCC-6.4.0-2.28.simg
== Temporary log file(s) /tmp/eb-aYXYC8/easybuild-8uXhvu.log* have been removed.
== Temporary directory /tmp/eb-aYXYC8 has been removed.
```
To inspect the container image, you can use `singularity shell` to start a shell session in the container:
```console
$ singularity shell --shell "/bin/bash --norc" $HOME/.local/easybuild/containers/GCC-6.4.0-2.28.simg
Singularity GCC-6.4.0-2.28.simg:~> source /etc/profile
Singularity GCC-6.4.0-2.28.simg:~> module list
Currently Loaded Modules:
1) GCCcore/6.4.0 2) binutils/2.28-GCCcore-6.4.0 3) GCC/6.4.0-2.28
Singularity GCC-6.4.0-2.28.simg:~> which gcc
/app/software/GCCcore/6.4.0/bin/gcc
Singularity GCC-6.4.0-2.28.simg:~> gcc --version
gcc (GCC) 6.4.0
...
```
Or, you can use `singularity exec` to execute a command in the container.
Compare the output of running which gcc and `gcc --version` locally:
```console
$ which gcc
/usr/bin/gcc
$ gcc --version
gcc (GCC) 4.8.5 20150623 (Red Hat 4.8.5-16)
...
```
and the output when running the same commands in the container:
```console
$ singularity exec GCC-6.4.0-2.28.simg which gcc
/app/software/GCCcore/6.4.0/bin/gcc
$ singularity exec GCC-6.4.0-2.28.simg gcc --version
gcc (GCC) 6.4.0
...
```
## Configuration
### Location for Generated Container Recipes & Images
To control the location where EasyBuild will put generated container recipes & images, use the `--containerpath` configuration setting. Next to providing this as an option to the eb command, you can also define the `$EASYBUILD_CONTAINERPATH` environment variable or specify containerpath in an EasyBuild configuration file.
The default value for this location is `$HOME/.local/easybuild/containers`, unless the `--prefix` configuration setting was provided, in which case it becomes <prefix>/containers (see Overall prefix path (`--prefix`)).
Use `eb --show-full-config | grep containerpath` to determine the currently active setting.
### Container Image Format
The format for container images that EasyBuild produces via the functionality provided by the container software can be controlled via the `--container-image-format` configuration setting.
For Apptainer/Singularity containers (see Type of container recipe/image to generate (`--container-type`)), three image formats are supported:
* squashfs (default): compressed images using squashfs read-only file system
* ext3: writable image file using ext3 file system
* sandbox: container image in a regular directory
See also official user guide on [Image Mounts format][d] and [Building a Container][e].
## Name for Container Recipe & Image
By default, EasyBuild will use the name of the first easyconfig file (without the .eb suffix) as a name for both the container recipe and the image.
You can specify an alternate name using the `--container-image-name` configuration setting.
The filename of the generated container recipe will be `Singularity`.<name>.
The filename of the container image will be `<name><extension>`, where the value for `<extension>` depends on the image format (see Container image format (`--container-image-format`)):
* ‘.simg’ for squashfs container images
* ‘.img’ for ext3 container images
* empty for sandbox container images (in which case the container image is actually a directory rather than a file)
### Temporary Directory for Creating Container Images
The container software that EasyBuild leverages to build container images may be using a temporary directory in a location that does not have sufficient free space.
You can instruct EasyBuild to pass an alternate location via the `--container-tmpdir` configuration setting.
For Apptainer/Singularity, the default is to use /tmp, [see][f]. If `--container-tmpdir` is specified, the `$SINGULARITY_TMPDIR` environment variable will be defined accordingly to let Apptainer/Singularity use that location instead.
Type of container recipe/image to generate (`--container-type`).
With the `--container-type` configuration option, you can specify what type of container recipe/image EasyBuild should generate. Possible values are:
* singularity (default): [Singularity][g] container recipes & images
* docker: [Docker][h] container recipe & images
For detailed documentation, see the [webpage][i].
[a]: https://hub.docker.com/
[b]: https://singularity-hub.org/
[c]: https://singularity-hub.org/collections/143
[d]: https://apptainer.org/docs/user/latest/bind_paths_and_mounts.html#image-mounts
[e]: https://apptainer.org/docs/user/latest/build_a_container.html
[f]: https://apptainer.org/docs/user/latest/build_env.html#temporary-folders
[g]: https://singularity.lbl.gov
[h]: https://docs.docker.com/
[i]: http://easybuild.readthedocs.io/en/latest/Containers.html