diff --git a/doc/builders/images.xml b/doc/builders/images.xml index b72fe094db15..d7d250291893 100644 --- a/doc/builders/images.xml +++ b/doc/builders/images.xml @@ -7,6 +7,6 @@ </para> <xi:include href="images/appimagetools.xml" /> <xi:include href="images/dockertools.section.xml" /> - <xi:include href="images/ocitools.xml" /> + <xi:include href="images/ocitools.section.xml" /> <xi:include href="images/snaptools.xml" /> </chapter> diff --git a/doc/builders/images/ocitools.section.md b/doc/builders/images/ocitools.section.md new file mode 100644 index 000000000000..d3dee57ebac6 --- /dev/null +++ b/doc/builders/images/ocitools.section.md @@ -0,0 +1,37 @@ +# pkgs.ociTools {#sec-pkgs-ociTools} + +`pkgs.ociTools` is a set of functions for creating containers according to the [OCI container specification v1.0.0](https://github.com/opencontainers/runtime-spec). Beyond that it makes no assumptions about the container runner you choose to use to run the created container. + +## buildContainer {#ssec-pkgs-ociTools-buildContainer} + +This function creates a simple OCI container that runs a single command inside of it. An OCI container consists of a `config.json` and a rootfs directory.The nix store of the container will contain all referenced dependencies of the given command. + +The parameters of `buildContainer` with an example value are described below: + +```nix +buildContainer { + args = [ + (with pkgs; + writeScript "run.sh" '' + #!${bash}/bin/bash + exec ${bash}/bin/bash + '').outPath + ]; + + mounts = { + "/data" = { + type = "none"; + source = "/var/lib/mydata"; + options = [ "bind" ]; + }; + }; + + readonly = false; +} +``` + +- `args` specifies a set of arguments to run inside the container. This is the only required argument for `buildContainer`. All referenced packages inside the derivation will be made available inside the container + +- `mounts` specifies additional mount points chosen by the user. By default only a minimal set of necessary filesystems are mounted into the container (e.g procfs, cgroupfs) + +- `readonly` makes the container\'s rootfs read-only if it is set to true. The default value is false `false`. diff --git a/doc/builders/images/ocitools.xml b/doc/builders/images/ocitools.xml deleted file mode 100644 index f26ed8644276..000000000000 --- a/doc/builders/images/ocitools.xml +++ /dev/null @@ -1,61 +0,0 @@ -<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-ociTools"> - <title>pkgs.ociTools</title> - - <para> - <varname>pkgs.ociTools</varname> is a set of functions for creating containers according to the <link xlink:href="https://github.com/opencontainers/runtime-spec">OCI container specification v1.0.0</link>. Beyond that it makes no assumptions about the container runner you choose to use to run the created container. - </para> - - <section xml:id="ssec-pkgs-ociTools-buildContainer"> - <title>buildContainer</title> - - <para> - This function creates a simple OCI container that runs a single command inside of it. An OCI container consists of a <varname>config.json</varname> and a rootfs directory.The nix store of the container will contain all referenced dependencies of the given command. - </para> - - <para> - The parameters of <varname>buildContainer</varname> with an example value are described below: - </para> - - <example xml:id='ex-ociTools-buildContainer'> - <title>Build Container</title> -<programlisting> -buildContainer { - args = [ (with pkgs; writeScript "run.sh" '' - #!${bash}/bin/bash - exec ${bash}/bin/bash - '').outPath ]; <co xml:id='ex-ociTools-buildContainer-1' /> - - mounts = { - "/data" = { - type = "none"; - source = "/var/lib/mydata"; - options = [ "bind" ]; - }; - };<co xml:id='ex-ociTools-buildContainer-2' /> - - readonly = false; <co xml:id='ex-ociTools-buildContainer-3' /> -} -</programlisting> - <calloutlist> - <callout arearefs='ex-ociTools-buildContainer-1'> - <para> - <varname>args</varname> specifies a set of arguments to run inside the container. This is the only required argument for <varname>buildContainer</varname>. All referenced packages inside the derivation will be made available inside the container - </para> - </callout> - <callout arearefs='ex-ociTools-buildContainer-2'> - <para> - <varname>mounts</varname> specifies additional mount points chosen by the user. By default only a minimal set of necessary filesystems are mounted into the container (e.g procfs, cgroupfs) - </para> - </callout> - <callout arearefs='ex-ociTools-buildContainer-3'> - <para> - <varname>readonly</varname> makes the container's rootfs read-only if it is set to true. The default value is false <literal>false</literal>. - </para> - </callout> - </calloutlist> - </example> - </section> -</section>