pkgs.dockerTools.buildImage: Additional Configuration Details

Those functions allow scripts to be run as root without access to the `kvm` device. ::: :::{.note} At the time the script in `runAsRoot` is run, the files specified directly in `copyToRoot` will be present in the VM, but their dependencies might not be there yet. Copying their dependencies into the generated image is a step that happens after `runAsRoot` finishes running. ::: _Default value:_ `null`. `extraCommands` (String; _optional_) : A bash script that will run before the layer created by `buildImage` is finalised. The script will be run on some (opaque) working directory which will become `/` once the layer is created. This is similar to `runAsRoot`, but the script specified in `extraCommands` is **not** run as root, and does not involve creating a VM. It is simply run as part of building the derivation that outputs the layer created by `buildImage`. See [](#ex-dockerTools-buildImage-extraCommands) for how to work with this attribute, and subtle differences compared to `runAsRoot`. _Default value:_ `""`. `config` (Attribute Set or Null; _optional_) : Used to specify the configuration of the containers that will be started off the generated image. Must be an attribute set, with each attribute as listed in the [Docker Image Specification v1.3.0](https://github.com/moby/moby/blob/46f7ab808b9504d735d600e259ca0723f76fb164/image/spec/spec.md#image-json-field-descriptions). _Default value:_ `null`. `architecture` (String; _optional_) : Used to specify the image architecture. This is useful for multi-architecture builds that don't need cross compiling. If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties), which should still be compatible with Docker. 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:_ the same value from `pkgs.go.GOARCH`. `diskSize` (Number; _optional_) : Controls the disk size (in megabytes) of the VM used to run the script specified in `runAsRoot`. This attribute is ignored if `runAsRoot` is `null`. _Default value:_ 1024. `buildVMMemorySize` (Number; _optional_) : Controls the amount of memory (in megabytes) provisioned for the VM used to run the script specified in `runAsRoot`. This attribute is ignored if `runAsRoot` is `null`. _Default value:_ 512. `created` (String; _optional_) : Specifies the time of creation of the generated image. This should be either a date and time formatted according to [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) or `"now"`, in which case `buildImage` will use the current date. See [](#ex-dockerTools-buildImage-creatednow) for how to use `"now"`. :::{.caution} Using `"now"` means that the generated image will not be reproducible anymore (because the date will always change whenever it's built). ::: _Default value:_ `"1970-01-01T00:00:01Z"`. `uid` (Number; _optional_) : The uid of the user that will own the files packed in the new layer built by `buildImage`. _Default value:_ 0. `gid` (Number; _optional_) : The gid of the group that will own the files packed in the new layer built by `buildImage`. _Default value:_ 0. `compressor` (String; _optional_) : Selects the algorithm used to compress the image. _Default value:_ `"gz"`.\ _Possible values:_ `"none"`, `"gz"`, `"zstd"`. `includeNixDB` (Boolean; _optional_) : Populate the nix database in the image with the dependencies of `copyToRoot`. The main purpose is to be able to use nix commands in the container. :::{.caution} Be careful since this doesn't work well in combination with `fromImage`. In particular, in a multi-layered image, only the Nix paths from the lower image will be in the database. This also neglects to register the store paths that are pulled into the image as a dependency of one of the other values, but aren't a dependency of `copyToRoot`.

This section continues detailing advanced configuration options for `pkgs.dockerTools.buildImage`. `extraCommands` executes a script before finalizing the layer, without root access or a VM. `config` specifies container configurations following the Docker Image Specification. `architecture` defines the image's architecture, useful for multi-architecture builds. `diskSize` and `buildVMMemorySize` control VM resources for `runAsRoot`. `created` sets the image creation timestamp (using "now" makes builds non-reproducible). `uid` and `gid` define file ownership in the new layer. `compressor` selects the image compression algorithm. `includeNixDB` populates the Nix database with dependencies of `copyToRoot`, enabling Nix commands in the container, but has caveats when used with `fromImage` or unregistered store paths.