`streamLayeredImage` Configuration: Scripting, Root Operations, and Nix Store Management

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 chunk details additional configuration attributes for `streamLayeredImage`. It reiterates the `maxLayers` attribute (defaulting to 100) and then introduces `extraCommands` for running bash scripts within the content layer. `fakeRootCommands` allows for privileged file operations, such as `chown`, within a `fakeroot` environment during layer generation, with `enableFakechroot` offering a more comprehensive `proot`-based chroot. The `includeStorePaths` attribute controls whether actual files or just links to Nix store paths are embedded in the image, defaulting to `true` for proper functionality. `includeNixDB` enables populating the Nix database for in-container Nix commands, though with warnings regarding `fromImage` compatibility and dependency registration. Finally, `passthru` is an attribute set for passing custom attributes to the resulting derivation, and the section notes that `streamLayeredImage` also defines its own `passthru` outputs.