pkgs.dockerTools.buildImage: Advanced Configuration Options

If specified, the layer created by `buildImage` will be appended to the layers defined in the base image, resulting in an image with at least two layers (one or more layers from the base image, and the layer created by `buildImage`). Otherwise, the resulting image with contain the single layer created by `buildImage`. :::{.note} Only **Env** configuration is inherited from the base image. ::: _Default value:_ `null`. `fromImageName` (String or Null; _optional_) : Used to specify the image within the repository tarball in case it contains multiple images. A value of `null` means that `buildImage` will use the first image available in the repository. :::{.note} This must be used with `fromImageTag`. Using only `fromImageName` without `fromImageTag` will make `buildImage` use the first image available in the repository. ::: _Default value:_ `null`. `fromImageTag` (String or Null; _optional_) : Used to specify the image within the repository tarball in case it contains multiple images. A value of `null` means that `buildImage` will use the first image available in the repository. :::{.note} This must be used with `fromImageName`. Using only `fromImageTag` without `fromImageName` will make `buildImage` use the first image available in the repository ::: _Default value:_ `null`. `copyToRoot` (Path, List of Paths, or Null; _optional_) : Files to add to the generated image. Anything that coerces to a path (e.g. a derivation) can also be used. This can be seen as an equivalent of `ADD contents/ /` in a `Dockerfile`. _Default value:_ `null`. `keepContentsDirlinks` (Boolean; _optional_) : When adding files to the generated image (as specified by `copyToRoot`), this attribute controls whether to preserve symlinks to directories. If `false`, the symlinks will be transformed into directories. This behaves the same as `rsync -k` when `keepContentsDirlinks` is `false`, and the same as `rsync -K` when `keepContentsDirlinks` is `true`. _Default value:_ `false`. `runAsRoot` (String or Null; _optional_) : A bash script that will run as root inside a VM that contains the existing layers of the base image and the new generated layer (including the files from `copyToRoot`). The script will be run with a working directory of `/`. This can be seen as an equivalent of `RUN ...` in a `Dockerfile`. A value of `null` means that this step in the image generation process will be skipped. See [](#ex-dockerTools-buildImage-runAsRoot) for how to work with this attribute. :::{.caution} Using this attribute requires the `kvm` device to be available, see [`system-features`](https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-system-features). If the `kvm` device isn't available, you should consider using [`buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage) or [`streamLayeredImage`](#ssec-pkgs-dockerTools-streamLayeredImage) instead. 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:_ `""`.

This section details advanced configuration options for `pkgs.dockerTools.buildImage`. `fromImageName` and `fromImageTag` specify images within a repository tarball, requiring each other. `copyToRoot` adds files to the image, like `ADD` in Dockerfiles. `keepContentsDirlinks` determines if symlinks to directories are preserved. `runAsRoot` executes a bash script as root in a VM, similar to `RUN` in Dockerfiles, requiring the `kvm` device. Note that dependencies may not be present in the VM during the execution of `runAsRoot`. `extraCommands` runs a non-root bash script before the layer is finalized.