1 files changed, 62 insertions, 0 deletions
diff --git a/doc/builders/images/ocitools.xml b/doc/builders/images/ocitools.xml
new file mode 100644
index 00000000000..f61075b242f
--- /dev/null
+++ b/doc/builders/images/ocitools.xml
@@ -0,0 +1,62 @@
+<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
+    ${coreutils}/bin/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>