Update documentation on containers (#19631)
fixes #15183 - Moved the container related content from workflows.rst into containers.rst - Deleted the docker_for_developers.rst file, since it describes an outdated procedure Co-authored-by: Axel Huebl <a.huebl@hzdr.de> Co-authored-by: Omar Padron <omar.padron@kitware.com>
This commit is contained in:
Massimiliano Culpo
GitHub
parent
33c3c3c700
commit
c4aa5cb5bc
@ -79,6 +79,13 @@ Environments:
|
|||||||
|
|
||||||
ENTRYPOINT ["/bin/bash", "--rcfile", "/etc/profile", "-l"]
|
ENTRYPOINT ["/bin/bash", "--rcfile", "/etc/profile", "-l"]
|
||||||
|
|
||||||
|
In order to build and run the image, execute:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
$ spack containerize > Dockerfile
|
||||||
|
$ docker build -t myimage .
|
||||||
|
$ docker run -it myimage
|
||||||
|
|
||||||
The bits that make this automation possible are discussed in details
|
The bits that make this automation possible are discussed in details
|
||||||
below. All the images generated in this way will be based on
|
below. All the images generated in this way will be based on
|
||||||
@ -305,3 +312,57 @@ following ``Dockerfile``:
|
|||||||
Spack can also produce Singularity definition files to build the image. The
|
Spack can also produce Singularity definition files to build the image. The
|
||||||
minimum version of Singularity required to build a SIF (Singularity Image Format)
|
minimum version of Singularity required to build a SIF (Singularity Image Format)
|
||||||
from them is ``3.5.3``.
|
from them is ``3.5.3``.
|
||||||
|
|
||||||
|
--------------
|
||||||
|
Best Practices
|
||||||
|
--------------
|
||||||
|
|
||||||
|
^^^
|
||||||
|
MPI
|
||||||
|
^^^
|
||||||
|
Due to the dependency on Fortran for OpenMPI, which is the spack default
|
||||||
|
implementation, consider adding ``gfortran`` to the ``apt-get install`` list.
|
||||||
|
|
||||||
|
Recent versions of OpenMPI will require you to pass ``--allow-run-as-root``
|
||||||
|
to your ``mpirun`` calls if started as root user inside Docker.
|
||||||
|
|
||||||
|
For execution on HPC clusters, it can be helpful to import the docker
|
||||||
|
image into Singularity in order to start a program with an *external*
|
||||||
|
MPI. Otherwise, also add ``openssh-server`` to the ``apt-get install`` list.
|
||||||
|
|
||||||
|
^^^^
|
||||||
|
CUDA
|
||||||
|
^^^^
|
||||||
|
Starting from CUDA 9.0, Nvidia provides minimal CUDA images based on
|
||||||
|
Ubuntu. Please see `their instructions <https://hub.docker.com/r/nvidia/cuda/>`_.
|
||||||
|
Avoid double-installing CUDA by adding, e.g.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
packages:
|
||||||
|
cuda:
|
||||||
|
externals:
|
||||||
|
- spec: "cuda@9.0.176%gcc@5.4.0 arch=linux-ubuntu16-x86_64"
|
||||||
|
prefix: /usr/local/cuda
|
||||||
|
buildable: False
|
||||||
|
|
||||||
|
to your ``spack.yaml``.
|
||||||
|
|
||||||
|
Users will either need ``nvidia-docker`` or e.g. Singularity to *execute*
|
||||||
|
device kernels.
|
||||||
|
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
Docker on Windows and OSX
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
On Mac OS and Windows, docker runs on a hypervisor that is not allocated much
|
||||||
|
memory by default, and some spack packages may fail to build due to lack of
|
||||||
|
memory. To work around this issue, consider configuring your docker installation
|
||||||
|
to use more of your host memory. In some cases, you can also ease the memory
|
||||||
|
pressure on parallel builds by limiting the parallelism in your config.yaml.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
config:
|
||||||
|
build_jobs: 2
|
||||||
|
|
||||||
|
|||||||
@ -1,41 +0,0 @@
|
|||||||
.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
|
|
||||||
Spack Project Developers. See the top-level COPYRIGHT file for details.
|
|
||||||
|
|
||||||
SPDX-License-Identifier: (Apache-2.0 OR MIT)
|
|
||||||
|
|
||||||
.. _docker_for_developers:
|
|
||||||
|
|
||||||
=====================
|
|
||||||
Docker for Developers
|
|
||||||
=====================
|
|
||||||
|
|
||||||
This guide is intended for people who want to use our prepared docker
|
|
||||||
environments to work on developing Spack or working on spack packages. It is
|
|
||||||
meant to serve as the companion documentation for the :ref:`packaging-guide`.
|
|
||||||
|
|
||||||
--------
|
|
||||||
Overview
|
|
||||||
--------
|
|
||||||
|
|
||||||
To get started, all you need is the latest version of ``docker``.
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ cd share/spack/docker
|
|
||||||
$ source config/ubuntu.bash
|
|
||||||
$ ./run-image.sh
|
|
||||||
|
|
||||||
This command should drop you into an interactive shell where you can run spack
|
|
||||||
within an isolated docker container running ubuntu. The copy of spack being
|
|
||||||
used should be tied to the working copy of your cloned git repo, so any changes
|
|
||||||
you make should be immediately reflected in the running docker container. Feel
|
|
||||||
free to add or modify any packages or to hack on spack, itself. Your contained
|
|
||||||
copy of spack should immediately reflect all changes.
|
|
||||||
|
|
||||||
To work within a container running a different linux distro, source one of the
|
|
||||||
other environment files under ``config``.
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ source config/fedora.bash
|
|
||||||
$ ./run-image.sh
|
|
||||||
@ -85,7 +85,6 @@ or refer to the full manual below.
|
|||||||
packaging_guide
|
packaging_guide
|
||||||
build_systems
|
build_systems
|
||||||
developer_guide
|
developer_guide
|
||||||
docker_for_developers
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|||||||
@ -1034,171 +1034,6 @@ The main points that are implemented below:
|
|||||||
- make -j 2
|
- make -j 2
|
||||||
- make test
|
- make test
|
||||||
|
|
||||||
.. _workflow_create_docker_image:
|
|
||||||
|
|
||||||
-----------------------------------
|
|
||||||
Using Spack to Create Docker Images
|
|
||||||
-----------------------------------
|
|
||||||
|
|
||||||
Spack can be the ideal tool to set up images for Docker (and Singularity).
|
|
||||||
|
|
||||||
An example ``Dockerfile`` is given below, downloading the latest spack
|
|
||||||
version.
|
|
||||||
|
|
||||||
The following functionality is prepared:
|
|
||||||
|
|
||||||
#. Base image: the example starts from a minimal ubuntu.
|
|
||||||
|
|
||||||
#. Pre-install the spack dependencies.
|
|
||||||
Package installs are followed by a clean-up of the system package index,
|
|
||||||
to avoid outdated information and it saves space.
|
|
||||||
|
|
||||||
#. Install spack in ``/usr/local``.
|
|
||||||
Add ``setup-env.sh`` to profile scripts, so commands in *login* shells
|
|
||||||
can use the whole spack functionality, including modules.
|
|
||||||
|
|
||||||
#. Install an example package (``tar``).
|
|
||||||
As with system package managers above, ``spack install`` commands should be
|
|
||||||
concatenated with a ``&& spack clean -a`` in order to keep image sizes small.
|
|
||||||
|
|
||||||
#. Add a startup hook to an *interactive login shell* so spack modules will be
|
|
||||||
usable.
|
|
||||||
|
|
||||||
In order to build and run the image, execute:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
docker build -t spack .
|
|
||||||
docker run -it spack
|
|
||||||
|
|
||||||
.. code-block:: docker
|
|
||||||
|
|
||||||
FROM ubuntu:16.04
|
|
||||||
MAINTAINER Your Name <someone@example.com>
|
|
||||||
|
|
||||||
# general environment for docker
|
|
||||||
ENV DEBIAN_FRONTEND=noninteractive \
|
|
||||||
SPACK_ROOT=/usr/local
|
|
||||||
|
|
||||||
# install minimal spack dependencies
|
|
||||||
RUN apt-get update \
|
|
||||||
&& apt-get install -y --no-install-recommends \
|
|
||||||
autoconf \
|
|
||||||
build-essential \
|
|
||||||
ca-certificates \
|
|
||||||
coreutils \
|
|
||||||
curl \
|
|
||||||
environment-modules \
|
|
||||||
git \
|
|
||||||
python \
|
|
||||||
unzip \
|
|
||||||
vim \
|
|
||||||
&& rm -rf /var/lib/apt/lists/*
|
|
||||||
|
|
||||||
# load spack environment on login
|
|
||||||
RUN echo "source $SPACK_ROOT/share/spack/setup-env.sh" \
|
|
||||||
> /etc/profile.d/spack.sh
|
|
||||||
|
|
||||||
# spack settings
|
|
||||||
# note: if you wish to change default settings, add files alongside
|
|
||||||
# the Dockerfile with your desired settings. Then uncomment this line
|
|
||||||
#COPY packages.yaml modules.yaml $SPACK_ROOT/etc/spack/
|
|
||||||
|
|
||||||
# install spack
|
|
||||||
RUN curl -s -L https://api.github.com/repos/spack/spack/tarball \
|
|
||||||
| tar xzC $SPACK_ROOT --strip 1
|
|
||||||
# note: at this point one could also run ``spack bootstrap`` to avoid
|
|
||||||
# parts of the long apt-get install list above
|
|
||||||
|
|
||||||
# install software
|
|
||||||
RUN spack install tar \
|
|
||||||
&& spack clean -a
|
|
||||||
|
|
||||||
# need the executables from a package already during image build?
|
|
||||||
#RUN /bin/bash -l -c ' \
|
|
||||||
# spack load tar \
|
|
||||||
# && which tar'
|
|
||||||
|
|
||||||
# image run hook: the -l will make sure /etc/profile environments are loaded
|
|
||||||
CMD /bin/bash -l
|
|
||||||
|
|
||||||
^^^^^^^^^^^^^^
|
|
||||||
Best Practices
|
|
||||||
^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
"""
|
|
||||||
MPI
|
|
||||||
"""
|
|
||||||
Due to the dependency on Fortran for OpenMPI, which is the spack default
|
|
||||||
implementation, consider adding ``gfortran`` to the ``apt-get install`` list.
|
|
||||||
|
|
||||||
Recent versions of OpenMPI will require you to pass ``--allow-run-as-root``
|
|
||||||
to your ``mpirun`` calls if started as root user inside Docker.
|
|
||||||
|
|
||||||
For execution on HPC clusters, it can be helpful to import the docker
|
|
||||||
image into Singularity in order to start a program with an *external*
|
|
||||||
MPI. Otherwise, also add ``openssh-server`` to the ``apt-get install`` list.
|
|
||||||
|
|
||||||
""""
|
|
||||||
CUDA
|
|
||||||
""""
|
|
||||||
Starting from CUDA 9.0, Nvidia provides minimal CUDA images based on
|
|
||||||
Ubuntu.
|
|
||||||
Please see `their instructions <https://hub.docker.com/r/nvidia/cuda/>`_.
|
|
||||||
Avoid double-installing CUDA by adding, e.g.
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
packages:
|
|
||||||
cuda:
|
|
||||||
externals:
|
|
||||||
- spec: "cuda@9.0.176%gcc@5.4.0 arch=linux-ubuntu16-x86_64"
|
|
||||||
prefix: /usr/local/cuda
|
|
||||||
buildable: False
|
|
||||||
|
|
||||||
to your ``packages.yaml``.
|
|
||||||
Then ``COPY`` in that file into the image as in the example above.
|
|
||||||
|
|
||||||
Users will either need ``nvidia-docker`` or e.g. Singularity to *execute*
|
|
||||||
device kernels.
|
|
||||||
|
|
||||||
"""""""""""
|
|
||||||
Singularity
|
|
||||||
"""""""""""
|
|
||||||
Importing and running the image created above into
|
|
||||||
`Singularity <http://singularity.lbl.gov/>`_ works like a charm.
|
|
||||||
Just use the `docker bootstraping mechanism <http://singularity.lbl.gov/quickstart#bootstrap-recipes>`_:
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
Bootstrap: docker
|
|
||||||
From: registry/user/image:tag
|
|
||||||
|
|
||||||
%runscript
|
|
||||||
exec /bin/bash -l
|
|
||||||
|
|
||||||
""""""""""""""""""""""
|
|
||||||
Docker for Development
|
|
||||||
""""""""""""""""""""""
|
|
||||||
|
|
||||||
For examples of how we use docker in development, see
|
|
||||||
:ref:`docker_for_developers`.
|
|
||||||
|
|
||||||
"""""""""""""""""""""""""
|
|
||||||
Docker on Windows and OSX
|
|
||||||
"""""""""""""""""""""""""
|
|
||||||
|
|
||||||
On Mac OS and Windows, docker runs on a hypervisor that is not allocated much
|
|
||||||
memory by default, and some spack packages may fail to build due to lack of
|
|
||||||
memory. To work around this issue, consider configuring your docker installation
|
|
||||||
to use more of your host memory. In some cases, you can also ease the memory
|
|
||||||
pressure on parallel builds by limiting the parallelism in your config.yaml.
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
config:
|
|
||||||
build_jobs: 2
|
|
||||||
|
|
||||||
------------------
|
------------------
|
||||||
Upstream Bug Fixes
|
Upstream Bug Fixes
|
||||||
------------------
|
------------------
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user