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 @@
-
- pkgs.dockerTools
-
-
- pkgs.dockerTools is a set of functions for creating and
- manipulating Docker images according to the
-
- Docker Image Specification v1.2.0 . Docker itself is not used to
- perform any of the operations done by these functions.
-
-
-
-
- The dockerTools API is unstable and may be subject to
- backwards-incompatible changes in the future.
-
-
-
-
- buildImage
-
-
- This function is analogous to the docker build 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 docker load.
-
-
-
- The parameters of buildImage with relative example
- values are described below:
-
-
-
- Docker build
-
-buildImage {
- name = "redis";
- tag = "latest";
-
- fromImage = someBaseImage;
- fromImageName = null;
- fromImageTag = "latest";
-
- contents = pkgs.redis;
- runAsRoot = ''
- #!${stdenv.shell}
- mkdir -p /data
- '';
-
- config = {
- Cmd = [ "/bin/redis-server" ];
- WorkingDir = "/data";
- Volumes = {
- "/data" = {};
- };
- };
-}
-
-
-
-
- The above example will build a Docker image redis/latest
- from the given base image. Loading and running this image in Docker results
- in redis-server being started automatically.
-
-
-
-
-
- name specifies the name of the resulting image. This
- is the only required argument for buildImage.
-
-
-
-
- tag specifies the tag of the resulting image. By
- default it's null, which indicates that the nix output
- hash will be used as tag.
-
-
-
-
- fromImage is the repository tarball containing the
- base image. It must be a valid Docker image, such as exported by
- docker save. By default it's null,
- which can be seen as equivalent to FROM scratch of a
- Dockerfile.
-
-
-
-
- fromImageName can be used to further specify the base
- image within the repository, in case it contains multiple images. By
- default it's null, in which case
- buildImage will peek the first image available in the
- repository.
-
-
-
-
- fromImageTag 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 null, in which case
- buildImage will peek the first tag available for the
- base image.
-
-
-
-
- contents is a derivation that will be copied in the
- new layer of the resulting image. This can be similarly seen as
- ADD contents/ / in a Dockerfile.
- By default it's null.
-
-
-
-
- runAsRoot 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
- contents derivation. This can be similarly seen as
- RUN ... in a Dockerfile.
-
-
- Using this parameter requires the kvm device to be
- available.
-
-
-
-
-
-
- config 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
-
- Docker Image Specification v1.2.0 .
-
-
-
-
-
- After the new layer has been created, its closure (to which
- contents, config and
- runAsRoot contribute) will be copied in the layer
- itself. Only new dependencies that are not already in the existing layers
- will be copied.
-
-
-
- At the end of the process, only one new single layer will be produced and
- added to the resulting image.
-
-
-
- The resulting repository will only list the single image
- image/tag. In the case of
- it would be
- redis/latest.
-
-
-
- It is possible to inspect the arguments with which an image was built using
- its buildArgs attribute.
-
-
-
-
- If you see errors similar to getProtocolByName: does not exist
- (no such protocol name: tcp) you may need to add
- pkgs.iana-etc to contents.
-
-
-
-
-
- If you see errors similar to Error_Protocol ("certificate has
- unknown CA",True,UnknownCa) you may need to add
- pkgs.cacert to contents.
-
-
-
-
- Impurely Defining a Docker Layer's Creation Date
-
- By default buildImage will use a static
- date of one second past the UNIX Epoch. This allows
- buildImage to produce binary reproducible
- images. When listing images with docker list
- images, the newly created images will be listed like
- this:
-
-
-
- You can break binary reproducibility but have a sorted,
- meaningful CREATED column by setting
- created to now.
-
-
-
- and now the Docker CLI will display a reasonable date and
- sort the images as expected:
-
- however, the produced images will not be binary reproducible.
-
-
-
-
-
- buildLayeredImage
-
-
- Create a Docker image with many of the store paths being on their own layer
- to improve sharing between images.
-
-
-
-
-
- name
-
-
-
- The name of the resulting image.
-
-
-
-
-
- tagoptional
-
-
-
- Tag of the generated image.
-
-
- Default: the output path's hash
-
-
-
-
-
- contentsoptional
-
-
-
- Top level paths in the container. Either a single derivation, or a list
- of derivations.
-
-
- Default:[]
-
-
-
-
-
- configoptional
-
-
-
- Run-time configuration of the container. A full list of the options are
- available at in the
-
- Docker Image Specification v1.2.0 .
-
-
- Default:{}
-
-
-
-
-
- createdoptional
-
-
-
- Date and time the layers were created. Follows the same
- now exception supported by
- buildImage.
-
-
- Default:1970-01-01T00:00:01Z
-
-
-
-
-
- maxLayersoptional
-
-
-
- Maximum number of layers to create.
-
-
- Default:24
-
-
-
-
-
-
- Behavior of contents in the final image
-
-
- Each path directly listed in contents will have a
- symlink in the root of the image.
-
-
-
- For example:
-
- will create symlinks for all the paths in the hello
- package:
- /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
-]]>
-
-
-
-
- Automatic inclusion of config references
-
-
- The closure of config is automatically included in the
- closure of the final image.
-
-
-
- This allows you to make very simple Docker images with very little code.
- This container will start up and run hello:
-
-
-
-
-
- Adjusting maxLayers
-
-
- Increasing the maxLayers increases the number of layers
- which have a chance to be shared between different images.
-
-
-
- Modern Docker installations support up to 128 layers, however older
- versions support as few as 42.
-
-
-
- If the produced image will not be extended by other Docker builds, it is
- safe to set maxLayers to 128.
- However it will be impossible to extend the image further.
-
-
-
- The first (maxLayers-2) most "popular" paths will have
- their own individual layers, then layer #maxLayers-1
- will contain all the remaining "unpopular" paths, and finally layer
- #maxLayers will contain the Image configuration.
-
-
-
- Docker's Layers are not inherently ordered, they are content-addressable
- and are not explicitly layered until they are composed in to an Image.
-
-
-
-
-
- pullImage
-
-
- This function is analogous to the docker pull command,
- in that can be used to pull a Docker image from a Docker registry. By
- default Docker Hub is
- used to pull images.
-
-
-
- Its parameters are described in the example below:
-
-
-
- Docker pull
-
-pullImage {
- imageName = "nixos/nix";
- imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b";
- finalImageTag = "1.11";
- sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8";
- os = "linux";
- arch = "x86_64";
-}
-
-
-
-
-
-
- imageName specifies the name of the image to be
- downloaded, which can also include the registry namespace (e.g.
- nixos). This argument is required.
-
-
-
-
- imageDigest specifies the digest of the image to be
- downloaded. Skopeo can be used to get the digest of an image, with its
- inspect subcommand. Since a given
- imageName 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.
-
-$ 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
-
- This argument is required.
-
-
-
-
- finalImageTag, 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
- latest.
-
-
-
-
- sha256 is the checksum of the whole fetched image.
- This argument is required.
-
-
-
-
- os, if specified, is the operating system of the
- fetched image. By default it's linux.
-
-
-
-
- arch, if specified, is the cpu architecture of the
- fetched image. By default it's x86_64.
-
-
-
-
-
-
- exportImage
-
-
- This function is analogous to the docker export 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
- docker import.
-
-
-
-
- Using this function requires the kvm device to be
- available.
-
-
-
-
- The parameters of exportImage are the following:
-
-
-
- Docker export
-
-exportImage {
- fromImage = someLayeredImage;
- fromImageName = null;
- fromImageTag = null;
-
- name = someLayeredImage.name;
-}
-
-
-
-
- The parameters relative to the base image have the same synopsis as
- described in , except
- that fromImage is the only required argument in this
- case.
-
-
-
- The name argument is the name of the derivation output,
- which defaults to fromImage.name.
-
-
-
-
- shadowSetup
-
-
- 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 runAsRoot
- script for cases like
- in the example below:
-
-
-
- Shadow base files
-
-buildImage {
- name = "shadow-basic";
-
- runAsRoot = ''
- #!${stdenv.shell}
- ${shadowSetup}
- groupadd -r redis
- useradd -r -g redis redis
- mkdir /data
- chown redis:redis /data
- '';
-}
-
-
-
-
- Creating base files like /etc/passwd or
- /etc/login.defs are necessary for shadow-utils to
- manipulate users and groups.
-
-
-
+
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 @@
+
+ pkgs.dockerTools
+
+
+ pkgs.dockerTools is a set of functions for creating and
+ manipulating Docker images according to the
+
+ Docker Image Specification v1.2.0 . Docker itself is not used to
+ perform any of the operations done by these functions.
+
+
+
+
+ The dockerTools API is unstable and may be subject to
+ backwards-incompatible changes in the future.
+
+
+
+
+ buildImage
+
+
+ This function is analogous to the docker build 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 docker load.
+
+
+
+ The parameters of buildImage with relative example
+ values are described below:
+
+
+
+ Docker build
+
+buildImage {
+ name = "redis";
+ tag = "latest";
+
+ fromImage = someBaseImage;
+ fromImageName = null;
+ fromImageTag = "latest";
+
+ contents = pkgs.redis;
+ runAsRoot = ''
+ #!${stdenv.shell}
+ mkdir -p /data
+ '';
+
+ config = {
+ Cmd = [ "/bin/redis-server" ];
+ WorkingDir = "/data";
+ Volumes = {
+ "/data" = {};
+ };
+ };
+}
+
+
+
+
+ The above example will build a Docker image redis/latest
+ from the given base image. Loading and running this image in Docker results
+ in redis-server being started automatically.
+
+
+
+
+
+ name specifies the name of the resulting image. This
+ is the only required argument for buildImage.
+
+
+
+
+ tag specifies the tag of the resulting image. By
+ default it's null, which indicates that the nix output
+ hash will be used as tag.
+
+
+
+
+ fromImage is the repository tarball containing the
+ base image. It must be a valid Docker image, such as exported by
+ docker save. By default it's null,
+ which can be seen as equivalent to FROM scratch of a
+ Dockerfile.
+
+
+
+
+ fromImageName can be used to further specify the base
+ image within the repository, in case it contains multiple images. By
+ default it's null, in which case
+ buildImage will peek the first image available in the
+ repository.
+
+
+
+
+ fromImageTag 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 null, in which case
+ buildImage will peek the first tag available for the
+ base image.
+
+
+
+
+ contents is a derivation that will be copied in the
+ new layer of the resulting image. This can be similarly seen as
+ ADD contents/ / in a Dockerfile.
+ By default it's null.
+
+
+
+
+ runAsRoot 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
+ contents derivation. This can be similarly seen as
+ RUN ... in a Dockerfile.
+
+
+ Using this parameter requires the kvm device to be
+ available.
+
+
+
+
+
+
+ config 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
+
+ Docker Image Specification v1.2.0 .
+
+
+
+
+
+ After the new layer has been created, its closure (to which
+ contents, config and
+ runAsRoot contribute) will be copied in the layer
+ itself. Only new dependencies that are not already in the existing layers
+ will be copied.
+
+
+
+ At the end of the process, only one new single layer will be produced and
+ added to the resulting image.
+
+
+
+ The resulting repository will only list the single image
+ image/tag. In the case of
+ it would be
+ redis/latest.
+
+
+
+ It is possible to inspect the arguments with which an image was built using
+ its buildArgs attribute.
+
+
+
+
+ If you see errors similar to getProtocolByName: does not exist
+ (no such protocol name: tcp) you may need to add
+ pkgs.iana-etc to contents.
+
+
+
+
+
+ If you see errors similar to Error_Protocol ("certificate has
+ unknown CA",True,UnknownCa) you may need to add
+ pkgs.cacert to contents.
+
+
+
+
+ Impurely Defining a Docker Layer's Creation Date
+
+ By default buildImage will use a static
+ date of one second past the UNIX Epoch. This allows
+ buildImage to produce binary reproducible
+ images. When listing images with docker list
+ images, the newly created images will be listed like
+ this:
+
+
+
+ You can break binary reproducibility but have a sorted,
+ meaningful CREATED column by setting
+ created to now.
+
+
+
+ and now the Docker CLI will display a reasonable date and
+ sort the images as expected:
+
+ however, the produced images will not be binary reproducible.
+
+
+
+
+
+ buildLayeredImage
+
+
+ Create a Docker image with many of the store paths being on their own layer
+ to improve sharing between images.
+
+
+
+
+
+ name
+
+
+
+ The name of the resulting image.
+
+
+
+
+
+ tagoptional
+
+
+
+ Tag of the generated image.
+
+
+ Default: the output path's hash
+
+
+
+
+
+ contentsoptional
+
+
+
+ Top level paths in the container. Either a single derivation, or a list
+ of derivations.
+
+
+ Default:[]
+
+
+
+
+
+ configoptional
+
+
+
+ Run-time configuration of the container. A full list of the options are
+ available at in the
+
+ Docker Image Specification v1.2.0 .
+
+
+ Default:{}
+
+
+
+
+
+ createdoptional
+
+
+
+ Date and time the layers were created. Follows the same
+ now exception supported by
+ buildImage.
+
+
+ Default:1970-01-01T00:00:01Z
+
+
+
+
+
+ maxLayersoptional
+
+
+
+ Maximum number of layers to create.
+
+
+ Default:24
+
+
+
+
+
+
+ Behavior of contents in the final image
+
+
+ Each path directly listed in contents will have a
+ symlink in the root of the image.
+
+
+
+ For example:
+
+ will create symlinks for all the paths in the hello
+ package:
+ /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
+]]>
+
+
+
+
+ Automatic inclusion of config references
+
+
+ The closure of config is automatically included in the
+ closure of the final image.
+
+
+
+ This allows you to make very simple Docker images with very little code.
+ This container will start up and run hello:
+
+
+
+
+
+ Adjusting maxLayers
+
+
+ Increasing the maxLayers increases the number of layers
+ which have a chance to be shared between different images.
+
+
+
+ Modern Docker installations support up to 128 layers, however older
+ versions support as few as 42.
+
+
+
+ If the produced image will not be extended by other Docker builds, it is
+ safe to set maxLayers to 128.
+ However it will be impossible to extend the image further.
+
+
+
+ The first (maxLayers-2) most "popular" paths will have
+ their own individual layers, then layer #maxLayers-1
+ will contain all the remaining "unpopular" paths, and finally layer
+ #maxLayers will contain the Image configuration.
+
+
+
+ Docker's Layers are not inherently ordered, they are content-addressable
+ and are not explicitly layered until they are composed in to an Image.
+
+
+
+
+
+ pullImage
+
+
+ This function is analogous to the docker pull command,
+ in that can be used to pull a Docker image from a Docker registry. By
+ default Docker Hub is
+ used to pull images.
+
+
+
+ Its parameters are described in the example below:
+
+
+
+ Docker pull
+
+pullImage {
+ imageName = "nixos/nix";
+ imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b";
+ finalImageTag = "1.11";
+ sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8";
+ os = "linux";
+ arch = "x86_64";
+}
+
+
+
+
+
+
+ imageName specifies the name of the image to be
+ downloaded, which can also include the registry namespace (e.g.
+ nixos). This argument is required.
+
+
+
+
+ imageDigest specifies the digest of the image to be
+ downloaded. Skopeo can be used to get the digest of an image, with its
+ inspect subcommand. Since a given
+ imageName 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.
+
+$ 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
+
+ This argument is required.
+
+
+
+
+ finalImageTag, 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
+ latest.
+
+
+
+
+ sha256 is the checksum of the whole fetched image.
+ This argument is required.
+
+
+
+
+ os, if specified, is the operating system of the
+ fetched image. By default it's linux.
+
+
+
+
+ arch, if specified, is the cpu architecture of the
+ fetched image. By default it's x86_64.
+
+
+
+
+
+
+ exportImage
+
+
+ This function is analogous to the docker export 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
+ docker import.
+
+
+
+
+ Using this function requires the kvm device to be
+ available.
+
+
+
+
+ The parameters of exportImage are the following:
+
+
+
+ Docker export
+
+exportImage {
+ fromImage = someLayeredImage;
+ fromImageName = null;
+ fromImageTag = null;
+
+ name = someLayeredImage.name;
+}
+
+
+
+
+ The parameters relative to the base image have the same synopsis as
+ described in , except
+ that fromImage is the only required argument in this
+ case.
+
+
+
+ The name argument is the name of the derivation output,
+ which defaults to fromImage.name.
+
+
+
+
+ shadowSetup
+
+
+ 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 runAsRoot
+ script for cases like
+ in the example below:
+
+
+
+ Shadow base files
+
+buildImage {
+ name = "shadow-basic";
+
+ runAsRoot = ''
+ #!${stdenv.shell}
+ ${shadowSetup}
+ groupadd -r redis
+ useradd -r -g redis redis
+ mkdir /data
+ chown redis:redis /data
+ '';
+}
+
+
+
+
+ Creating base files like /etc/passwd or
+ /etc/login.defs are necessary for shadow-utils to
+ manipulate users and groups.
+
+
+