depot/third_party/nixpkgs/doc/builders/images/ocitools.xml

<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>