nixpkgs/doc/functions/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
    ${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>