Home • Explore • Blog • CI
☰



nixpkgs
2nd chunk of `doc/build-helpers/images/ocitools.section.md`
2d0078c4a5b3eb4302d4b8bf0916882b7a2063d8f8522e7a0000000100000d66
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.
  :::

  :::{.note}
  `buildContainer` includes a minimal set of necessary filesystems to be mounted into the container, and this set can't be changed with the `mounts` attribute.
  :::

  _Default value:_ `{}`.

`readonly` (Boolean; _optional_)

: If `true`, sets the container's root filesystem as read-only.

  _Default value:_ `false`.

`os` **DEPRECATED**

: Specifies the operating system on which the container filesystem is based on.
  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
  According to the linked specification, all possible values for `$GOOS` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `darwin` or `linux`.

  _Default value:_ `"linux"`.

`arch` **DEPRECATED**

: Used to specify the architecture for which the binaries in the container filesystem have been compiled.
  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
  According to the linked specification, all possible values for `$GOARCH` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `386`, `amd64`, `arm`, or `arm64`.

  _Default value:_ `x86_64`.

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

::: {.example #ex-ociTools-buildContainer-bash}
# Creating an OCI runtime container that runs `bash`

This example uses `ociTools.buildContainer` to create a simple container that runs `bash`.

```nix
{
  ociTools,
  lib,
  bash,
}:
ociTools.buildContainer {
  args = [
    (lib.getExe bash)
  ];

  readonly = false;
}
```

As an example of how to run the container generated by this package, we'll use `runc` to start the container.
Any other tool that supports OCI containers could be used instead.

```shell
$ nix-build
(some output removed for clarity)
/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join

$ cd /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
$ nix-shell -p runc
[nix-shell:/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join]$ sudo runc run ocitools-example
help
GNU bash, version 5.2.26(1)-release (x86_64-pc-linux-gnu)
(some output removed for clarity)
```
:::
Title: buildContainer Inputs and Examples
Summary
The `buildContainer` function has limitations. It is not compatible with non-POSIX platforms like Windows without modification, and it does not create a user namespace, requiring the container to be run as root. The function accepts `args` (a list of strings to execute), an optional `mounts` attribute, which is ignored. Other attributes include `readonly`, `os` and `arch`, where `os` and `arch` are deprecated. An example demonstrates creating a container that runs bash, along with instructions on how to execute it using `runc`.