nixpkgs docs: move dockertool to its own file

2 files changed, 567 insertions, 563 deletions

diff --git a/doc/functions.xml b/doc/functions.xml
index ac75c4fc10e4..4fc387f0fbd6 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -13,567 +13,5 @@
  <xi:include href="functions/debug.xml" />
  <xi:include href="functions/fhs-environments.xml" />
  <xi:include href="shell.section.xml" />
- <section xml:id="sec-pkgs-dockerTools">
-  <title>pkgs.dockerTools</title>
-
-  <para>
-   <varname>pkgs.dockerTools</varname> is a set of functions for creating and
-   manipulating Docker images according to the
-   <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120">
-   Docker Image Specification v1.2.0 </link>. Docker itself is not used to
-   perform any of the operations done by these functions.
-  </para>
-
-  <warning>
-   <para>
-    The <varname>dockerTools</varname> API is unstable and may be subject to
-    backwards-incompatible changes in the future.
-   </para>
-  </warning>
-
-  <section xml:id="ssec-pkgs-dockerTools-buildImage">
-   <title>buildImage</title>
-
-   <para>
-    This function is analogous to the <command>docker build</command> command,
-    in that can used to build a Docker-compatible repository tarball containing
-    a single image with one or multiple layers. As such, the result is suitable
-    for being loaded in Docker with <command>docker load</command>.
-   </para>
-
-   <para>
-    The parameters of <varname>buildImage</varname> with relative example
-    values are described below:
-   </para>
-
-   <example xml:id='ex-dockerTools-buildImage'>
-    <title>Docker build</title>
-<programlisting>
-buildImage {
-  name = "redis"; <co xml:id='ex-dockerTools-buildImage-1' />
-  tag = "latest"; <co xml:id='ex-dockerTools-buildImage-2' />
-
-  fromImage = someBaseImage; <co xml:id='ex-dockerTools-buildImage-3' />
-  fromImageName = null; <co xml:id='ex-dockerTools-buildImage-4' />
-  fromImageTag = "latest"; <co xml:id='ex-dockerTools-buildImage-5' />
-
-  contents = pkgs.redis; <co xml:id='ex-dockerTools-buildImage-6' />
-  runAsRoot = '' <co xml:id='ex-dockerTools-buildImage-runAsRoot' />
-    #!${stdenv.shell}
-    mkdir -p /data
-  '';
-
-  config = { <co xml:id='ex-dockerTools-buildImage-8' />
-    Cmd = [ "/bin/redis-server" ];
-    WorkingDir = "/data";
-    Volumes = {
-      "/data" = {};
-    };
-  };
-}
-</programlisting>
-   </example>
-
-   <para>
-    The above example will build a Docker image <literal>redis/latest</literal>
-    from the given base image. Loading and running this image in Docker results
-    in <literal>redis-server</literal> being started automatically.
-   </para>
-
-   <calloutlist>
-    <callout arearefs='ex-dockerTools-buildImage-1'>
-     <para>
-      <varname>name</varname> specifies the name of the resulting image. This
-      is the only required argument for <varname>buildImage</varname>.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-buildImage-2'>
-     <para>
-      <varname>tag</varname> specifies the tag of the resulting image. By
-      default it's <literal>null</literal>, which indicates that the nix output
-      hash will be used as tag.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-buildImage-3'>
-     <para>
-      <varname>fromImage</varname> is the repository tarball containing the
-      base image. It must be a valid Docker image, such as exported by
-      <command>docker save</command>. By default it's <literal>null</literal>,
-      which can be seen as equivalent to <literal>FROM scratch</literal> of a
-      <filename>Dockerfile</filename>.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-buildImage-4'>
-     <para>
-      <varname>fromImageName</varname> can be used to further specify the base
-      image within the repository, in case it contains multiple images. By
-      default it's <literal>null</literal>, in which case
-      <varname>buildImage</varname> will peek the first image available in the
-      repository.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-buildImage-5'>
-     <para>
-      <varname>fromImageTag</varname> can be used to further specify the tag of
-      the base image within the repository, in case an image contains multiple
-      tags. By default it's <literal>null</literal>, in which case
-      <varname>buildImage</varname> will peek the first tag available for the
-      base image.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-buildImage-6'>
-     <para>
-      <varname>contents</varname> is a derivation that will be copied in the
-      new layer of the resulting image. This can be similarly seen as
-      <command>ADD contents/ /</command> in a <filename>Dockerfile</filename>.
-      By default it's <literal>null</literal>.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-buildImage-runAsRoot'>
-     <para>
-      <varname>runAsRoot</varname> is a bash script that will run as root in an
-      environment that overlays the existing layers of the base image with the
-      new resulting layer, including the previously copied
-      <varname>contents</varname> derivation. This can be similarly seen as
-      <command>RUN ...</command> in a <filename>Dockerfile</filename>.
-      <note>
-       <para>
-        Using this parameter requires the <literal>kvm</literal> device to be
-        available.
-       </para>
-      </note>
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-buildImage-8'>
-     <para>
-      <varname>config</varname> is used to specify the configuration of the
-      containers that will be started off the built image in Docker. The
-      available options are listed in the
-      <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions">
-      Docker Image Specification v1.2.0 </link>.
-     </para>
-    </callout>
-   </calloutlist>
-
-   <para>
-    After the new layer has been created, its closure (to which
-    <varname>contents</varname>, <varname>config</varname> and
-    <varname>runAsRoot</varname> contribute) will be copied in the layer
-    itself. Only new dependencies that are not already in the existing layers
-    will be copied.
-   </para>
-
-   <para>
-    At the end of the process, only one new single layer will be produced and
-    added to the resulting image.
-   </para>
-
-   <para>
-    The resulting repository will only list the single image
-    <varname>image/tag</varname>. In the case of
-    <xref linkend='ex-dockerTools-buildImage'/> it would be
-    <varname>redis/latest</varname>.
-   </para>
-
-   <para>
-    It is possible to inspect the arguments with which an image was built using
-    its <varname>buildArgs</varname> attribute.
-   </para>
-
-   <note>
-    <para>
-     If you see errors similar to <literal>getProtocolByName: does not exist
-     (no such protocol name: tcp)</literal> you may need to add
-     <literal>pkgs.iana-etc</literal> to <varname>contents</varname>.
-    </para>
-   </note>
-
-   <note>
-    <para>
-     If you see errors similar to <literal>Error_Protocol ("certificate has
-     unknown CA",True,UnknownCa)</literal> you may need to add
-     <literal>pkgs.cacert</literal> to <varname>contents</varname>.
-    </para>
-   </note>
-
-   <example xml:id="example-pkgs-dockerTools-buildImage-creation-date">
-     <title>Impurely Defining a Docker Layer's Creation Date</title>
-     <para>
-       By default <function>buildImage</function> will use a static
-       date of one second past the UNIX Epoch. This allows
-       <function>buildImage</function> to produce binary reproducible
-       images. When listing images with <command>docker list
-       images</command>, the newly created images will be listed like
-       this:
-     </para>
-     <screen><![CDATA[
-$ docker image list
-REPOSITORY   TAG      IMAGE ID       CREATED        SIZE
-hello        latest   08c791c7846e   48 years ago   25.2MB
-]]></screen>
-     <para>
-       You can break binary reproducibility but have a sorted,
-       meaningful <literal>CREATED</literal> column by setting
-       <literal>created</literal> to <literal>now</literal>.
-     </para>
-     <programlisting><![CDATA[
-pkgs.dockerTools.buildImage {
-  name = "hello";
-  tag = "latest";
-  created = "now";
-  contents = pkgs.hello;
-
-  config.Cmd = [ "/bin/hello" ];
-}
-]]></programlisting>
-     <para>
-       and now the Docker CLI will display a reasonable date and
-       sort the images as expected:
-       <screen><![CDATA[
-$ docker image list
-REPOSITORY   TAG      IMAGE ID       CREATED              SIZE
-hello        latest   de2bf4786de6   About a minute ago   25.2MB
-]]></screen>
-       however, the produced images will not be binary reproducible.
-     </para>
-   </example>
-  </section>
-
-  <section xml:id="ssec-pkgs-dockerTools-buildLayeredImage">
-   <title>buildLayeredImage</title>
-
-   <para>
-    Create a Docker image with many of the store paths being on their own layer
-    to improve sharing between images.
-   </para>
-
-   <variablelist>
-    <varlistentry>
-     <term>
-      <varname>name</varname>
-     </term>
-     <listitem>
-      <para>
-       The name of the resulting image.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>
-      <varname>tag</varname> <emphasis>optional</emphasis>
-     </term>
-     <listitem>
-      <para>
-       Tag of the generated image.
-      </para>
-      <para>
-       <emphasis>Default:</emphasis> the output path's hash
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>
-      <varname>contents</varname> <emphasis>optional</emphasis>
-     </term>
-     <listitem>
-      <para>
-       Top level paths in the container. Either a single derivation, or a list
-       of derivations.
-      </para>
-      <para>
-       <emphasis>Default:</emphasis> <literal>[]</literal>
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>
-      <varname>config</varname> <emphasis>optional</emphasis>
-     </term>
-     <listitem>
-      <para>
-       Run-time configuration of the container. A full list of the options are
-       available at in the
-       <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions">
-       Docker Image Specification v1.2.0 </link>.
-      </para>
-      <para>
-       <emphasis>Default:</emphasis> <literal>{}</literal>
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>
-      <varname>created</varname> <emphasis>optional</emphasis>
-     </term>
-     <listitem>
-      <para>
-       Date and time the layers were created. Follows the same
-       <literal>now</literal> exception supported by
-       <literal>buildImage</literal>.
-      </para>
-      <para>
-       <emphasis>Default:</emphasis> <literal>1970-01-01T00:00:01Z</literal>
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>
-      <varname>maxLayers</varname> <emphasis>optional</emphasis>
-     </term>
-     <listitem>
-      <para>
-       Maximum number of layers to create.
-      </para>
-      <para>
-       <emphasis>Default:</emphasis> <literal>24</literal>
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-
-   <section xml:id="dockerTools-buildLayeredImage-arg-contents">
-    <title>Behavior of <varname>contents</varname> in the final image</title>
-
-    <para>
-     Each path directly listed in <varname>contents</varname> will have a
-     symlink in the root of the image.
-    </para>
-
-    <para>
-     For example:
-<programlisting><![CDATA[
-pkgs.dockerTools.buildLayeredImage {
-  name = "hello";
-  contents = [ pkgs.hello ];
-}
-]]></programlisting>
-     will create symlinks for all the paths in the <literal>hello</literal>
-     package:
-<screen><![CDATA[
-/bin/hello -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/bin/hello
-/share/info/hello.info -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/info/hello.info
-/share/locale/bg/LC_MESSAGES/hello.mo -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/locale/bg/LC_MESSAGES/hello.mo
-]]></screen>
-    </para>
-   </section>
-
-   <section xml:id="dockerTools-buildLayeredImage-arg-config">
-    <title>Automatic inclusion of <varname>config</varname> references</title>
-
-    <para>
-     The closure of <varname>config</varname> is automatically included in the
-     closure of the final image.
-    </para>
-
-    <para>
-     This allows you to make very simple Docker images with very little code.
-     This container will start up and run <command>hello</command>:
-<programlisting><![CDATA[
-pkgs.dockerTools.buildLayeredImage {
-  name = "hello";
-  config.Cmd = [ "${pkgs.hello}/bin/hello" ];
-}
-]]></programlisting>
-    </para>
-   </section>
-
-   <section xml:id="dockerTools-buildLayeredImage-arg-maxLayers">
-    <title>Adjusting <varname>maxLayers</varname></title>
-
-    <para>
-     Increasing the <varname>maxLayers</varname> increases the number of layers
-     which have a chance to be shared between different images.
-    </para>
-
-    <para>
-     Modern Docker installations support up to 128 layers, however older
-     versions support as few as 42.
-    </para>
-
-    <para>
-     If the produced image will not be extended by other Docker builds, it is
-     safe to set <varname>maxLayers</varname> to <literal>128</literal>.
-     However it will be impossible to extend the image further.
-    </para>
-
-    <para>
-     The first (<literal>maxLayers-2</literal>) most "popular" paths will have
-     their own individual layers, then layer #<literal>maxLayers-1</literal>
-     will contain all the remaining "unpopular" paths, and finally layer
-     #<literal>maxLayers</literal> will contain the Image configuration.
-    </para>
-
-    <para>
-     Docker's Layers are not inherently ordered, they are content-addressable
-     and are not explicitly layered until they are composed in to an Image.
-    </para>
-   </section>
-  </section>
-
-  <section xml:id="ssec-pkgs-dockerTools-fetchFromRegistry">
-   <title>pullImage</title>
-
-   <para>
-    This function is analogous to the <command>docker pull</command> command,
-    in that can be used to pull a Docker image from a Docker registry. By
-    default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is
-    used to pull images.
-   </para>
-
-   <para>
-    Its parameters are described in the example below:
-   </para>
-
-   <example xml:id='ex-dockerTools-pullImage'>
-    <title>Docker pull</title>
-<programlisting>
-pullImage {
-  imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' />
-  imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; <co xml:id='ex-dockerTools-pullImage-2' />
-  finalImageTag = "1.11";  <co xml:id='ex-dockerTools-pullImage-3' />
-  sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-4' />
-  os = "linux"; <co xml:id='ex-dockerTools-pullImage-5' />
-  arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' />
-}
-</programlisting>
-   </example>
-
-   <calloutlist>
-    <callout arearefs='ex-dockerTools-pullImage-1'>
-     <para>
-      <varname>imageName</varname> specifies the name of the image to be
-      downloaded, which can also include the registry namespace (e.g.
-      <literal>nixos</literal>). This argument is required.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-pullImage-2'>
-     <para>
-      <varname>imageDigest</varname> specifies the digest of the image to be
-      downloaded. Skopeo can be used to get the digest of an image, with its
-      <varname>inspect</varname> subcommand. Since a given
-      <varname>imageName</varname> may transparently refer to a manifest list
-      of images which support multiple architectures and/or operating systems,
-      supply the `--override-os` and `--override-arch` arguments to specify
-      exactly which image you want. By default it will match the OS and
-      architecture of the host the command is run on.
-<programlisting>
-$ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'"
-sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
-</programlisting>
-      This argument is required.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-pullImage-3'>
-     <para>
-      <varname>finalImageTag</varname>, if specified, this is the tag of the
-      image to be created. Note it is never used to fetch the image since we
-      prefer to rely on the immutable digest ID. By default it's
-      <literal>latest</literal>.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-pullImage-4'>
-     <para>
-      <varname>sha256</varname> is the checksum of the whole fetched image.
-      This argument is required.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-pullImage-5'>
-     <para>
-      <varname>os</varname>, if specified, is the operating system of the
-      fetched image. By default it's <literal>linux</literal>.
-     </para>
-    </callout>
-    <callout arearefs='ex-dockerTools-pullImage-6'>
-     <para>
-      <varname>arch</varname>, if specified, is the cpu architecture of the
-      fetched image. By default it's <literal>x86_64</literal>.
-     </para>
-    </callout>
-   </calloutlist>
-  </section>
-
-  <section xml:id="ssec-pkgs-dockerTools-exportImage">
-   <title>exportImage</title>
-
-   <para>
-    This function is analogous to the <command>docker export</command> command,
-    in that can used to flatten a Docker image that contains multiple layers.
-    It is in fact the result of the merge of all the layers of the image. As
-    such, the result is suitable for being imported in Docker with
-    <command>docker import</command>.
-   </para>
-
-   <note>
-    <para>
-     Using this function requires the <literal>kvm</literal> device to be
-     available.
-    </para>
-   </note>
-
-   <para>
-    The parameters of <varname>exportImage</varname> are the following:
-   </para>
-
-   <example xml:id='ex-dockerTools-exportImage'>
-    <title>Docker export</title>
-<programlisting>
-exportImage {
-  fromImage = someLayeredImage;
-  fromImageName = null;
-  fromImageTag = null;
-
-  name = someLayeredImage.name;
-}
-  </programlisting>
-   </example>
-
-   <para>
-    The parameters relative to the base image have the same synopsis as
-    described in <xref linkend='ssec-pkgs-dockerTools-buildImage'/>, except
-    that <varname>fromImage</varname> is the only required argument in this
-    case.
-   </para>
-
-   <para>
-    The <varname>name</varname> argument is the name of the derivation output,
-    which defaults to <varname>fromImage.name</varname>.
-   </para>
-  </section>
-
-  <section xml:id="ssec-pkgs-dockerTools-shadowSetup">
-   <title>shadowSetup</title>
-
-   <para>
-    This constant string is a helper for setting up the base files for managing
-    users and groups, only if such files don't exist already. It is suitable
-    for being used in a <varname>runAsRoot</varname>
-    <xref linkend='ex-dockerTools-buildImage-runAsRoot'/> script for cases like
-    in the example below:
-   </para>
-
-   <example xml:id='ex-dockerTools-shadowSetup'>
-    <title>Shadow base files</title>
-<programlisting>
-buildImage {
-  name = "shadow-basic";
-
-  runAsRoot = ''
-    #!${stdenv.shell}
-    ${shadowSetup}
-    groupadd -r redis
-    useradd -r -g redis redis
-    mkdir /data
-    chown redis:redis /data
-  '';
-}
-</programlisting>
-   </example>
-
-   <para>
-    Creating base files like <literal>/etc/passwd</literal> or
-    <literal>/etc/login.defs</literal> are necessary for shadow-utils to
-    manipulate users and groups.
-   </para>
-  </section>
- </section>
+ <xi:include href="functions/dockertools.xml" />
 </chapter>
diff --git a/doc/functions/dockertools.xml b/doc/functions/dockertools.xml
new file mode 100644
index 000000000000..8bfdb3c68d7a
--- /dev/null
+++ b/doc/functions/dockertools.xml
@@ -0,0 +1,566 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xml:id="sec-pkgs-dockerTools">
+  <title>pkgs.dockerTools</title>
+
+  <para>
+   <varname>pkgs.dockerTools</varname> is a set of functions for creating and
+   manipulating Docker images according to the
+   <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120">
+   Docker Image Specification v1.2.0 </link>. Docker itself is not used to
+   perform any of the operations done by these functions.
+  </para>
+
+  <warning>
+   <para>
+    The <varname>dockerTools</varname> API is unstable and may be subject to
+    backwards-incompatible changes in the future.
+   </para>
+  </warning>
+
+  <section xml:id="ssec-pkgs-dockerTools-buildImage">
+   <title>buildImage</title>
+
+   <para>
+    This function is analogous to the <command>docker build</command> command,
+    in that can used to build a Docker-compatible repository tarball containing
+    a single image with one or multiple layers. As such, the result is suitable
+    for being loaded in Docker with <command>docker load</command>.
+   </para>
+
+   <para>
+    The parameters of <varname>buildImage</varname> with relative example
+    values are described below:
+   </para>
+
+   <example xml:id='ex-dockerTools-buildImage'>
+    <title>Docker build</title>
+<programlisting>
+buildImage {
+  name = "redis"; <co xml:id='ex-dockerTools-buildImage-1' />
+  tag = "latest"; <co xml:id='ex-dockerTools-buildImage-2' />
+
+  fromImage = someBaseImage; <co xml:id='ex-dockerTools-buildImage-3' />
+  fromImageName = null; <co xml:id='ex-dockerTools-buildImage-4' />
+  fromImageTag = "latest"; <co xml:id='ex-dockerTools-buildImage-5' />
+
+  contents = pkgs.redis; <co xml:id='ex-dockerTools-buildImage-6' />
+  runAsRoot = '' <co xml:id='ex-dockerTools-buildImage-runAsRoot' />
+    #!${stdenv.shell}
+    mkdir -p /data
+  '';
+
+  config = { <co xml:id='ex-dockerTools-buildImage-8' />
+    Cmd = [ "/bin/redis-server" ];
+    WorkingDir = "/data";
+    Volumes = {
+      "/data" = {};
+    };
+  };
+}
+</programlisting>
+   </example>
+
+   <para>
+    The above example will build a Docker image <literal>redis/latest</literal>
+    from the given base image. Loading and running this image in Docker results
+    in <literal>redis-server</literal> being started automatically.
+   </para>
+
+   <calloutlist>
+    <callout arearefs='ex-dockerTools-buildImage-1'>
+     <para>
+      <varname>name</varname> specifies the name of the resulting image. This
+      is the only required argument for <varname>buildImage</varname>.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-buildImage-2'>
+     <para>
+      <varname>tag</varname> specifies the tag of the resulting image. By
+      default it's <literal>null</literal>, which indicates that the nix output
+      hash will be used as tag.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-buildImage-3'>
+     <para>
+      <varname>fromImage</varname> is the repository tarball containing the
+      base image. It must be a valid Docker image, such as exported by
+      <command>docker save</command>. By default it's <literal>null</literal>,
+      which can be seen as equivalent to <literal>FROM scratch</literal> of a
+      <filename>Dockerfile</filename>.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-buildImage-4'>
+     <para>
+      <varname>fromImageName</varname> can be used to further specify the base
+      image within the repository, in case it contains multiple images. By
+      default it's <literal>null</literal>, in which case
+      <varname>buildImage</varname> will peek the first image available in the
+      repository.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-buildImage-5'>
+     <para>
+      <varname>fromImageTag</varname> can be used to further specify the tag of
+      the base image within the repository, in case an image contains multiple
+      tags. By default it's <literal>null</literal>, in which case
+      <varname>buildImage</varname> will peek the first tag available for the
+      base image.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-buildImage-6'>
+     <para>
+      <varname>contents</varname> is a derivation that will be copied in the
+      new layer of the resulting image. This can be similarly seen as
+      <command>ADD contents/ /</command> in a <filename>Dockerfile</filename>.
+      By default it's <literal>null</literal>.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-buildImage-runAsRoot'>
+     <para>
+      <varname>runAsRoot</varname> is a bash script that will run as root in an
+      environment that overlays the existing layers of the base image with the
+      new resulting layer, including the previously copied
+      <varname>contents</varname> derivation. This can be similarly seen as
+      <command>RUN ...</command> in a <filename>Dockerfile</filename>.
+      <note>
+       <para>
+        Using this parameter requires the <literal>kvm</literal> device to be
+        available.
+       </para>
+      </note>
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-buildImage-8'>
+     <para>
+      <varname>config</varname> is used to specify the configuration of the
+      containers that will be started off the built image in Docker. The
+      available options are listed in the
+      <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions">
+      Docker Image Specification v1.2.0 </link>.
+     </para>
+    </callout>
+   </calloutlist>
+
+   <para>
+    After the new layer has been created, its closure (to which
+    <varname>contents</varname>, <varname>config</varname> and
+    <varname>runAsRoot</varname> contribute) will be copied in the layer
+    itself. Only new dependencies that are not already in the existing layers
+    will be copied.
+   </para>
+
+   <para>
+    At the end of the process, only one new single layer will be produced and
+    added to the resulting image.
+   </para>
+
+   <para>
+    The resulting repository will only list the single image
+    <varname>image/tag</varname>. In the case of
+    <xref linkend='ex-dockerTools-buildImage'/> it would be
+    <varname>redis/latest</varname>.
+   </para>
+
+   <para>
+    It is possible to inspect the arguments with which an image was built using
+    its <varname>buildArgs</varname> attribute.
+   </para>
+
+   <note>
+    <para>
+     If you see errors similar to <literal>getProtocolByName: does not exist
+     (no such protocol name: tcp)</literal> you may need to add
+     <literal>pkgs.iana-etc</literal> to <varname>contents</varname>.
+    </para>
+   </note>
+
+   <note>
+    <para>
+     If you see errors similar to <literal>Error_Protocol ("certificate has
+     unknown CA",True,UnknownCa)</literal> you may need to add
+     <literal>pkgs.cacert</literal> to <varname>contents</varname>.
+    </para>
+   </note>
+
+   <example xml:id="example-pkgs-dockerTools-buildImage-creation-date">
+     <title>Impurely Defining a Docker Layer's Creation Date</title>
+     <para>
+       By default <function>buildImage</function> will use a static
+       date of one second past the UNIX Epoch. This allows
+       <function>buildImage</function> to produce binary reproducible
+       images. When listing images with <command>docker list
+       images</command>, the newly created images will be listed like
+       this:
+     </para>
+     <screen><![CDATA[
+$ docker image list
+REPOSITORY   TAG      IMAGE ID       CREATED        SIZE
+hello        latest   08c791c7846e   48 years ago   25.2MB
+]]></screen>
+     <para>
+       You can break binary reproducibility but have a sorted,
+       meaningful <literal>CREATED</literal> column by setting
+       <literal>created</literal> to <literal>now</literal>.
+     </para>
+     <programlisting><![CDATA[
+pkgs.dockerTools.buildImage {
+  name = "hello";
+  tag = "latest";
+  created = "now";
+  contents = pkgs.hello;
+
+  config.Cmd = [ "/bin/hello" ];
+}
+]]></programlisting>
+     <para>
+       and now the Docker CLI will display a reasonable date and
+       sort the images as expected:
+       <screen><![CDATA[
+$ docker image list
+REPOSITORY   TAG      IMAGE ID       CREATED              SIZE
+hello        latest   de2bf4786de6   About a minute ago   25.2MB
+]]></screen>
+       however, the produced images will not be binary reproducible.
+     </para>
+   </example>
+  </section>
+
+  <section xml:id="ssec-pkgs-dockerTools-buildLayeredImage">
+   <title>buildLayeredImage</title>
+
+   <para>
+    Create a Docker image with many of the store paths being on their own layer
+    to improve sharing between images.
+   </para>
+
+   <variablelist>
+    <varlistentry>
+     <term>
+      <varname>name</varname>
+     </term>
+     <listitem>
+      <para>
+       The name of the resulting image.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <varname>tag</varname> <emphasis>optional</emphasis>
+     </term>
+     <listitem>
+      <para>
+       Tag of the generated image.
+      </para>
+      <para>
+       <emphasis>Default:</emphasis> the output path's hash
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <varname>contents</varname> <emphasis>optional</emphasis>
+     </term>
+     <listitem>
+      <para>
+       Top level paths in the container. Either a single derivation, or a list
+       of derivations.
+      </para>
+      <para>
+       <emphasis>Default:</emphasis> <literal>[]</literal>
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <varname>config</varname> <emphasis>optional</emphasis>
+     </term>
+     <listitem>
+      <para>
+       Run-time configuration of the container. A full list of the options are
+       available at in the
+       <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions">
+       Docker Image Specification v1.2.0 </link>.
+      </para>
+      <para>
+       <emphasis>Default:</emphasis> <literal>{}</literal>
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <varname>created</varname> <emphasis>optional</emphasis>
+     </term>
+     <listitem>
+      <para>
+       Date and time the layers were created. Follows the same
+       <literal>now</literal> exception supported by
+       <literal>buildImage</literal>.
+      </para>
+      <para>
+       <emphasis>Default:</emphasis> <literal>1970-01-01T00:00:01Z</literal>
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <varname>maxLayers</varname> <emphasis>optional</emphasis>
+     </term>
+     <listitem>
+      <para>
+       Maximum number of layers to create.
+      </para>
+      <para>
+       <emphasis>Default:</emphasis> <literal>24</literal>
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+
+   <section xml:id="dockerTools-buildLayeredImage-arg-contents">
+    <title>Behavior of <varname>contents</varname> in the final image</title>
+
+    <para>
+     Each path directly listed in <varname>contents</varname> will have a
+     symlink in the root of the image.
+    </para>
+
+    <para>
+     For example:
+<programlisting><![CDATA[
+pkgs.dockerTools.buildLayeredImage {
+  name = "hello";
+  contents = [ pkgs.hello ];
+}
+]]></programlisting>
+     will create symlinks for all the paths in the <literal>hello</literal>
+     package:
+<screen><![CDATA[
+/bin/hello -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/bin/hello
+/share/info/hello.info -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/info/hello.info
+/share/locale/bg/LC_MESSAGES/hello.mo -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/locale/bg/LC_MESSAGES/hello.mo
+]]></screen>
+    </para>
+   </section>
+
+   <section xml:id="dockerTools-buildLayeredImage-arg-config">
+    <title>Automatic inclusion of <varname>config</varname> references</title>
+
+    <para>
+     The closure of <varname>config</varname> is automatically included in the
+     closure of the final image.
+    </para>
+
+    <para>
+     This allows you to make very simple Docker images with very little code.
+     This container will start up and run <command>hello</command>:
+<programlisting><![CDATA[
+pkgs.dockerTools.buildLayeredImage {
+  name = "hello";
+  config.Cmd = [ "${pkgs.hello}/bin/hello" ];
+}
+]]></programlisting>
+    </para>
+   </section>
+
+   <section xml:id="dockerTools-buildLayeredImage-arg-maxLayers">
+    <title>Adjusting <varname>maxLayers</varname></title>
+
+    <para>
+     Increasing the <varname>maxLayers</varname> increases the number of layers
+     which have a chance to be shared between different images.
+    </para>
+
+    <para>
+     Modern Docker installations support up to 128 layers, however older
+     versions support as few as 42.
+    </para>
+
+    <para>
+     If the produced image will not be extended by other Docker builds, it is
+     safe to set <varname>maxLayers</varname> to <literal>128</literal>.
+     However it will be impossible to extend the image further.
+    </para>
+
+    <para>
+     The first (<literal>maxLayers-2</literal>) most "popular" paths will have
+     their own individual layers, then layer #<literal>maxLayers-1</literal>
+     will contain all the remaining "unpopular" paths, and finally layer
+     #<literal>maxLayers</literal> will contain the Image configuration.
+    </para>
+
+    <para>
+     Docker's Layers are not inherently ordered, they are content-addressable
+     and are not explicitly layered until they are composed in to an Image.
+    </para>
+   </section>
+  </section>
+
+  <section xml:id="ssec-pkgs-dockerTools-fetchFromRegistry">
+   <title>pullImage</title>
+
+   <para>
+    This function is analogous to the <command>docker pull</command> command,
+    in that can be used to pull a Docker image from a Docker registry. By
+    default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is
+    used to pull images.
+   </para>
+
+   <para>
+    Its parameters are described in the example below:
+   </para>
+
+   <example xml:id='ex-dockerTools-pullImage'>
+    <title>Docker pull</title>
+<programlisting>
+pullImage {
+  imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' />
+  imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; <co xml:id='ex-dockerTools-pullImage-2' />
+  finalImageTag = "1.11";  <co xml:id='ex-dockerTools-pullImage-3' />
+  sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-4' />
+  os = "linux"; <co xml:id='ex-dockerTools-pullImage-5' />
+  arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' />
+}
+</programlisting>
+   </example>
+
+   <calloutlist>
+    <callout arearefs='ex-dockerTools-pullImage-1'>
+     <para>
+      <varname>imageName</varname> specifies the name of the image to be
+      downloaded, which can also include the registry namespace (e.g.
+      <literal>nixos</literal>). This argument is required.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-pullImage-2'>
+     <para>
+      <varname>imageDigest</varname> specifies the digest of the image to be
+      downloaded. Skopeo can be used to get the digest of an image, with its
+      <varname>inspect</varname> subcommand. Since a given
+      <varname>imageName</varname> may transparently refer to a manifest list
+      of images which support multiple architectures and/or operating systems,
+      supply the `--override-os` and `--override-arch` arguments to specify
+      exactly which image you want. By default it will match the OS and
+      architecture of the host the command is run on.
+<programlisting>
+$ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'"
+sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
+</programlisting>
+      This argument is required.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-pullImage-3'>
+     <para>
+      <varname>finalImageTag</varname>, if specified, this is the tag of the
+      image to be created. Note it is never used to fetch the image since we
+      prefer to rely on the immutable digest ID. By default it's
+      <literal>latest</literal>.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-pullImage-4'>
+     <para>
+      <varname>sha256</varname> is the checksum of the whole fetched image.
+      This argument is required.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-pullImage-5'>
+     <para>
+      <varname>os</varname>, if specified, is the operating system of the
+      fetched image. By default it's <literal>linux</literal>.
+     </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-pullImage-6'>
+     <para>
+      <varname>arch</varname>, if specified, is the cpu architecture of the
+      fetched image. By default it's <literal>x86_64</literal>.
+     </para>
+    </callout>
+   </calloutlist>
+  </section>
+
+  <section xml:id="ssec-pkgs-dockerTools-exportImage">
+   <title>exportImage</title>
+
+   <para>
+    This function is analogous to the <command>docker export</command> command,
+    in that can used to flatten a Docker image that contains multiple layers.
+    It is in fact the result of the merge of all the layers of the image. As
+    such, the result is suitable for being imported in Docker with
+    <command>docker import</command>.
+   </para>
+
+   <note>
+    <para>
+     Using this function requires the <literal>kvm</literal> device to be
+     available.
+    </para>
+   </note>
+
+   <para>
+    The parameters of <varname>exportImage</varname> are the following:
+   </para>
+
+   <example xml:id='ex-dockerTools-exportImage'>
+    <title>Docker export</title>
+<programlisting>
+exportImage {
+  fromImage = someLayeredImage;
+  fromImageName = null;
+  fromImageTag = null;
+
+  name = someLayeredImage.name;
+}
+  </programlisting>
+   </example>
+
+   <para>
+    The parameters relative to the base image have the same synopsis as
+    described in <xref linkend='ssec-pkgs-dockerTools-buildImage'/>, except
+    that <varname>fromImage</varname> is the only required argument in this
+    case.
+   </para>
+
+   <para>
+    The <varname>name</varname> argument is the name of the derivation output,
+    which defaults to <varname>fromImage.name</varname>.
+   </para>
+  </section>
+
+  <section xml:id="ssec-pkgs-dockerTools-shadowSetup">
+   <title>shadowSetup</title>
+
+   <para>
+    This constant string is a helper for setting up the base files for managing
+    users and groups, only if such files don't exist already. It is suitable
+    for being used in a <varname>runAsRoot</varname>
+    <xref linkend='ex-dockerTools-buildImage-runAsRoot'/> script for cases like
+    in the example below:
+   </para>
+
+   <example xml:id='ex-dockerTools-shadowSetup'>
+    <title>Shadow base files</title>
+<programlisting>
+buildImage {
+  name = "shadow-basic";
+
+  runAsRoot = ''
+    #!${stdenv.shell}
+    ${shadowSetup}
+    groupadd -r redis
+    useradd -r -g redis redis
+    mkdir /data
+    chown redis:redis /data
+  '';
+}
+</programlisting>
+   </example>
+
+   <para>
+    Creating base files like <literal>/etc/passwd</literal> or
+    <literal>/etc/login.defs</literal> are necessary for shadow-utils to
+    manipulate users and groups.
+   </para>
+  </section>
+ </section>