streamLayeredImage Configuration: fakeroot, chroot, Store Paths, Nix DB, and Passthru Attributes

If a `fromImage` was specified, the number of layers used by `fromImage` will be subtracted from `maxLayers` to ensure that the image generated will have at most `maxLayers`. :::{.caution} Depending on the tool/runtime where the image will be used, there might be a limit to the number of layers that an image can have. For Docker, see [this issue on GitHub](https://github.com/docker/docs/issues/8230). ::: _Default value:_ 100. `extraCommands` (String; _optional_) : A bash script that will run in the context of the layer created with the contents specified by `contents`. At the moment this script runs, only the contents directly specified by `contents` will be available as links. _Default value:_ `""`. `fakeRootCommands` (String; _optional_) : A bash script that will run in the context of the layer created with the contents specified by `contents`. During the process to generate that layer, the script in `extraCommands` will be run first, if specified. After that, a {manpage}`fakeroot(1)` environment will be entered. The script specified in `fakeRootCommands` runs inside the fakeroot environment, and the layer is then generated from the view of the files inside the fakeroot environment. This is useful to change the owners of the files in the layer (by running `chown`, for example), or performing any other privileged operations related to file manipulation (by default, all files in the layer will be owned by root, and the build environment doesn't have enough privileges to directly perform privileged operations on these files). For more details, see the manpage for {manpage}`fakeroot(1)`. :::{.caution} Due to how fakeroot works, static binaries cannot perform privileged file operations in `fakeRootCommands`, unless `enableFakechroot` is set to `true`. ::: _Default value:_ `""`. `enableFakechroot` (Boolean; _optional_) : By default, the script specified in `fakeRootCommands` only runs inside a fakeroot environment. If `enableFakechroot` is `true`, a more complete chroot environment will be created using [`proot`](https://proot-me.github.io/) before running the script in `fakeRootCommands`. Files in the Nix store will be available. This allows scripts that perform installation in `/` to work as expected. This can be seen as an equivalent of `RUN ...` in a `Dockerfile`. _Default value:_ `false` `includeStorePaths` (Boolean; _optional_) : The files specified in `contents` are put into layers in the generated image. If `includeStorePaths` is `false`, the actual files will not be included in the generated image, and only links to them will be added instead. It is **not recommended** to set this to `false` unless you have other tooling to insert the store paths via other means (such as bind mounting the host store) when running containers with the generated image. If you don't provide any extra tooling, the generated image won't run properly. See [](#ex-dockerTools-streamLayeredImage-exploringlayers) to understand the impact of setting `includeStorePaths` to `false`. _Default value:_ `true` `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`. ::: _Default value:_ `false`. `passthru` (Attribute Set; _optional_) : Use this to pass any attributes as [`passthru`](#chap-passthru) for the resulting derivation. _Default value:_ `{}` ### Passthru outputs {#ssec-pkgs-dockerTools-streamLayeredImage-passthru-outputs} `streamLayeredImage` also defines its own [`passthru`](#chap-passthru) attributes:

This section describes additional configuration options for `streamLayeredImage`. `fakeRootCommands` allows executing privileged file operations using a fakeroot environment. `enableFakechroot` enhances this by creating a more complete chroot environment using `proot`, enabling installation scripts in `/` to work. `includeStorePaths` determines whether actual files or just links are included in the image (defaults to true, highly recommended). `includeNixDB` populates the Nix database for using Nix commands within the container (caution advised when using with `fromImage`). Finally, `passthru` enables passing attributes directly to the resulting derivation, and describes the passthru outputs.