Home • Explore • Blog • CI
☰



nixpkgs
1st chunk of `doc/build-helpers/images/ocitools.section.md`
fd99687e5e2f374ea38a8a3adaceaf4950b450e56a30cf79000000010000092c
# pkgs.ociTools {#sec-pkgs-ociTools}

`pkgs.ociTools` is a set of functions for creating runtime container bundles according to the [OCI runtime specification v1.0.0](https://github.com/opencontainers/runtime-spec/blob/v1.0.0/spec.md).
It makes no assumptions about the container runner you choose to use to run the created container.

The set of functions in `pkgs.ociTools` currently does not handle the [OCI image specification](https://github.com/opencontainers/image-spec).

At a high-level an OCI implementation would download an OCI Image then unpack that image into an OCI Runtime filesystem bundle.
At this point the OCI Runtime Bundle would be run by an OCI Runtime.
`pkgs.ociTools` provides utilities to create OCI Runtime bundles.

## buildContainer {#ssec-pkgs-ociTools-buildContainer}

This function creates an OCI runtime container (consisting of a `config.json` and a root filesystem directory) that runs a single command inside of it.
The nix store of the container will contain all referenced dependencies of the given command.

This function has an assumption that the container will run on POSIX platforms, and sets configurations (such as the user running the process or certain mounts) according to this assumption.
Because of this, a container built with `buildContainer` will not work on Windows or other non-POSIX platforms without modifications to the container configuration.
These modifications aren't supported by `buildContainer`.

For `linux` platforms, `buildContainer` also configures the following namespaces (see {manpage}`unshare(1)`) to isolate the OCI container from the global namespace:
PID, network, mount, IPC, and UTS.

Note that no user namespace is created, which means that you won't be able to run the container unless you are the `root` user.

### Inputs {#ssec-pkgs-ociTools-buildContainer-inputs}

`buildContainer` expects an argument with the following attributes:

`args` (List of String)

: Specifies a set of arguments to run inside the container.
  Any packages referenced by `args` will be made available inside the container.

`mounts` (Attribute Set; _optional_)

: Would specify additional mounts that the runtime must make available to the container.

  :::{.warning}
  As explained in [issue #290879](https://github.com/NixOS/nixpkgs/issues/290879), this attribute is currently ignored.
Title: pkgs.ociTools: Creating OCI Runtime Container Bundles
Summary
The `pkgs.ociTools` module provides functions for creating OCI runtime container bundles, adhering to the OCI runtime specification v1.0.0. Currently, it focuses on creating runtime bundles and does not handle OCI image specifications. The `buildContainer` function specifically creates a container to run a single command, including its dependencies from the Nix store, with POSIX platform assumptions and namespace isolation (PID, network, mount, IPC, UTS) on Linux. Note that user namespace is not created, and the `mounts` attribute is currently ignored.