diff --git a/doc/builders/images/dockertools.section.md b/doc/builders/images/dockertools.section.md index 7ff4b2aeb369..8baf9a97fdab 100644 --- a/doc/builders/images/dockertools.section.md +++ b/doc/builders/images/dockertools.section.md @@ -292,7 +292,44 @@ The parameters relative to the base image have the same synopsis as described in The `name` argument is the name of the derivation output, which defaults to `fromImage.name`. -## shadowSetup {#ssec-pkgs-dockerTools-shadowSetup} +## Environment Helpers {#ssec-pkgs-dockerTools-helpers} + +Some packages expect certain files to be available globally. +When building an image from scratch (i.e. without `fromImage`), these files are missing. +`pkgs.dockerTools` provides some helpers to set up an environment with the necessary files. +You can include them in `copyToRoot` like this: + +```nix +buildImage { + name = "environment-example"; + copyToRoot = with pkgs.dockerTools; [ + usrBinEnv + binSh + caCertificates + fakeNss + ]; +} +``` + +### usrBinEnv {#sssec-pkgs-dockerTools-helpers-usrBinEnv} + +This provides the `env` utility at `/usr/bin/env`. + +### binSh {#sssec-pkgs-dockerTools-helpers-binSh} + +This provides `bashInteractive` at `/bin/sh`. + +### caCertificates {#sssec-pkgs-dockerTools-helpers-caCertificates} + +This sets up `/etc/ssl/certs/ca-certificates.crt`. + +### fakeNss {#sssec-pkgs-dockerTools-helpers-fakeNss} + +Provides `/etc/passwd` and `/etc/group` that contain root and nobody. +Useful when packaging binaries that insist on using nss to look up +username/groups (like nginx). + +### shadowSetup {#ssec-pkgs-dockerTools-shadowSetup} This constant string is a helper for setting up the base files for managing users and groups, only if such files don't exist already. It is suitable for being used in a [`buildImage` `runAsRoot`](#ex-dockerTools-buildImage-runAsRoot) script for cases like in the example below: