diff options
Diffstat (limited to 'doc/build-helpers/images/dockertools.section.md')
| -rw-r--r-- | doc/build-helpers/images/dockertools.section.md | 508 |
1 files changed, 376 insertions, 132 deletions
diff --git a/doc/build-helpers/images/dockertools.section.md b/doc/build-helpers/images/dockertools.section.md index 677b429ba3c0b..9317146b8f94e 100644 --- a/doc/build-helpers/images/dockertools.section.md +++ b/doc/build-helpers/images/dockertools.section.md @@ -1088,238 +1088,482 @@ If you don't specify a `name` attribute, you'll encounter an evaluation error an ## 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: +When building Docker images with Nix, you might also want to add certain files that are expected to be available globally by the software you're packaging. +Simple examples are the `env` utility in `/usr/bin/env`, or trusted root TLS/SSL certificates. +Such files will most likely not be included if you're building a Docker image from scratch with Nix, and they might also not be included if you're starting from a Docker image that doesn't include them. +The helpers in this section are packages that provide some of these commonly-needed global files. -```nix -buildImage { - name = "environment-example"; - copyToRoot = with pkgs.dockerTools; [ - usrBinEnv - binSh - caCertificates - fakeNss - ]; -} -``` +Most of these helpers are packages, which means you have to add them to the list of contents to be included in the image (this changes depending on the function you're using to build the image). +[](#ex-dockerTools-helpers-buildImage) and [](#ex-dockerTools-helpers-buildLayeredImage) show how to include these packages on `dockerTools` functions that build an image. +For more details on how that works, see the documentation for the function you're using. ### usrBinEnv {#sssec-pkgs-dockerTools-helpers-usrBinEnv} This provides the `env` utility at `/usr/bin/env`. +This is currently implemented by linking to the `env` binary from the `coreutils` package, but is considered an implementation detail that could change in the future. ### binSh {#sssec-pkgs-dockerTools-helpers-binSh} -This provides `bashInteractive` at `/bin/sh`. +This provides a `/bin/sh` link to the `bash` binary from the `bashInteractive` package. +Because of this, it supports cases such as running a command interactively in a container (for example by running `docker run -it <image_name>`). ### caCertificates {#sssec-pkgs-dockerTools-helpers-caCertificates} -This sets up `/etc/ssl/certs/ca-certificates.crt`. +This adds trusted root TLS/SSL certificates from the `cacert` package in multiple locations in an attempt to be compatible with binaries built for multiple Linux distributions. +The locations currently used are: + +- `/etc/ssl/certs/ca-bundle.crt` +- `/etc/ssl/certs/ca-certificates.crt` +- `/etc/pki/tls/certs/ca-bundle.crt` +[]{#ssec-pkgs-dockerTools-fakeNss} ### 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). +This is a re-export of the `fakeNss` package from Nixpkgs. +See [](#sec-fakeNss). ### 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: +This is a string containing a script that sets up files needed for [`shadow`](https://github.com/shadow-maint/shadow) to work (using the `shadow` package from Nixpkgs), and alters `PATH` to make all its utilities available in the same script. +It is intended to be used with other dockerTools functions in attributes that expect scripts. +After the script in `shadowSetup` runs, you'll then be able to add more commands that make use of the utilities in `shadow`, such as adding any extra users and/or groups. +See [](#ex-dockerTools-shadowSetup-buildImage) and [](#ex-dockerTools-shadowSetup-buildLayeredImage) to better understand how to use it. + +`shadowSetup` achieves a result similar to [`fakeNss`](#sssec-pkgs-dockerTools-helpers-fakeNss), but only sets up a `root` user with different values for the home directory and the shell to use, in addition to setting up files for [PAM](https://en.wikipedia.org/wiki/Linux_PAM) and a {manpage}`login.defs(5)` file. + +:::{.caution} +Using both `fakeNss` and `shadowSetup` at the same time will either cause your build to break or produce unexpected results. +Use either `fakeNss` or `shadowSetup` depending on your use case, but avoid using both. +::: + +:::{.note} +When used with [`buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage) or [`streamLayeredImage`](#ssec-pkgs-dockerTools-streamLayeredImage), you will have to set the `enableFakechroot` attribute to `true`, or else the script in `shadowSetup` won't run properly. +See [](#ex-dockerTools-shadowSetup-buildLayeredImage). +::: + +### Examples {#ssec-pkgs-dockerTools-helpers-examples} + +:::{.example #ex-dockerTools-helpers-buildImage} +# Using `dockerTools`'s environment helpers with `buildImage` + +This example adds the [`binSh`](#sssec-pkgs-dockerTools-helpers-binSh) helper to a basic Docker image built with [`dockerTools.buildImage`](#ssec-pkgs-dockerTools-buildImage). +This helper makes it possible to enter a shell inside the container. +This is the `buildImage` equivalent of [](#ex-dockerTools-helpers-buildLayeredImage). + +```nix +{ dockerTools, hello }: +dockerTools.buildImage { + name = "env-helpers"; + tag = "latest"; + + copyToRoot = [ + hello + dockerTools.binSh + ]; +``` + +After building the image and loading it in Docker, we can create a container based on it and enter a shell inside the container. +This is made possible by `binSh`. + +```shell +$ nix-build +(some output removed for clarity) +/nix/store/2p0i3i04cgjlk71hsn7ll4kxaxxiv4qg-docker-image-env-helpers.tar.gz +$ docker load -i /nix/store/2p0i3i04cgjlk71hsn7ll4kxaxxiv4qg-docker-image-env-helpers.tar.gz +(output removed for clarity) +$ docker run --rm -it env-helpers:latest /bin/sh +sh-5.2# help +GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu) +(rest of output removed for clarity) +``` +::: + +:::{.example #ex-dockerTools-helpers-buildLayeredImage} +# Using `dockerTools`'s environment helpers with `buildLayeredImage` + +This example adds the [`binSh`](#sssec-pkgs-dockerTools-helpers-binSh) helper to a basic Docker image built with [`dockerTools.buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage). +This helper makes it possible to enter a shell inside the container. +This is the `buildLayeredImage` equivalent of [](#ex-dockerTools-helpers-buildImage). ```nix -buildImage { +{ dockerTools, hello }: +dockerTools.buildLayeredImage { + name = "env-helpers"; + tag = "latest"; + + contents = [ + hello + dockerTools.binSh + ]; + + config = { + Cmd = [ "/bin/hello" ]; + }; +} +``` + +After building the image and loading it in Docker, we can create a container based on it and enter a shell inside the container. +This is made possible by `binSh`. + +```shell +$ nix-build +(some output removed for clarity) +/nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz +$ docker load -i /nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz +(output removed for clarity) +$ docker run --rm -it env-helpers:latest /bin/sh +sh-5.2# help +GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu) +(rest of output removed for clarity) +``` +::: + +:::{.example #ex-dockerTools-shadowSetup-buildImage} +# Using `dockerTools.shadowSetup` with `dockerTools.buildImage` + +This is an example that shows how to use `shadowSetup` with `dockerTools.buildImage`. +Note that the extra script in `runAsRoot` uses `groupadd` and `useradd`, which are binaries provided by the `shadow` package. +These binaries are added to the `PATH` by the `shadowSetup` script, but only for the duration of `runAsRoot`. + +```nix +{ dockerTools, hello }: +dockerTools.buildImage { name = "shadow-basic"; + tag = "latest"; + + copyToRoot = [ hello ]; runAsRoot = '' - #!${pkgs.runtimeShell} - ${pkgs.dockerTools.shadowSetup} - groupadd -r redis - useradd -r -g redis redis + ${dockerTools.shadowSetup} + groupadd -r hello + useradd -r -g hello hello mkdir /data - chown redis:redis /data + chown hello:hello /data ''; + + config = { + Cmd = [ "/bin/hello" ]; + WorkingDir = "/data"; + }; } ``` +::: + +:::{.example #ex-dockerTools-shadowSetup-buildLayeredImage} +# Using `dockerTools.shadowSetup` with `dockerTools.buildLayeredImage` + +It accomplishes the same thing as [](#ex-dockerTools-shadowSetup-buildImage), but using `buildLayeredImage` instead. -Creating base files like `/etc/passwd` or `/etc/login.defs` is necessary for shadow-utils to manipulate users and groups. +Note that the extra script in `fakeRootCommands` uses `groupadd` and `useradd`, which are binaries provided by the `shadow` package. +These binaries are added to the `PATH` by the `shadowSetup` script, but only for the duration of `fakeRootCommands`. -When using `buildLayeredImage`, you can put this in `fakeRootCommands` if you `enableFakechroot`: ```nix -buildLayeredImage { - name = "shadow-layered"; +{ dockerTools, hello }: +dockerTools.buildLayeredImage { + name = "shadow-basic"; + tag = "latest"; + + contents = [ hello ]; fakeRootCommands = '' - ${pkgs.dockerTools.shadowSetup} + ${dockerTools.shadowSetup} + groupadd -r hello + useradd -r -g hello hello + mkdir /data + chown hello:hello /data ''; enableFakechroot = true; + + config = { + Cmd = [ "/bin/hello" ]; + WorkingDir = "/data"; + }; } ``` +::: -## fakeNss {#ssec-pkgs-dockerTools-fakeNss} +[]{#ssec-pkgs-dockerTools-buildNixShellImage-arguments} +## buildNixShellImage {#ssec-pkgs-dockerTools-buildNixShellImage} -If your primary goal is providing a basic skeleton for user lookups to work, -and/or a lesser privileged user, adding `pkgs.fakeNss` to -the container image root might be the better choice than a custom script -running `useradd` and friends. +`buildNixShellImage` uses [`streamNixShellImage`](#ssec-pkgs-dockerTools-streamNixShellImage) underneath to build a compressed Docker-compatible repository tarball of an image that sets up an environment similar to that of running `nix-shell` on a derivation. +Basically, `buildNixShellImage` runs the script created by `streamNixShellImage` to save the compressed image in the Nix store. -It provides a `/etc/passwd` and `/etc/group`, containing `root` and `nobody` -users and groups. +`buildNixShellImage` supports the same options as `streamNixShellImage`, see [`streamNixShellImage`](#ssec-pkgs-dockerTools-streamNixShellImage) for details. -It also provides a `/etc/nsswitch.conf`, configuring NSS host resolution to -first check `/etc/hosts`, before checking DNS, as the default in the absence of -a config file (`dns [!UNAVAIL=return] files`) is quite unexpected. +[]{#ssec-pkgs-dockerTools-buildNixShellImage-example} +### Examples {#ssec-pkgs-dockerTools-buildNixShellImage-examples} -You can pair it with `binSh`, which provides `bin/sh` as a symlink -to `bashInteractive` (as `/bin/sh` is configured as a shell). +:::{.example #ex-dockerTools-buildNixShellImage-hello} +# Building a Docker image with `buildNixShellImage` with the build environment for the `hello` package -```nix -buildImage { - name = "shadow-basic"; +This example shows how to build the `hello` package inside a Docker container built with `buildNixShellImage`. +The Docker image generated will have a name like `hello-<version>-env` and tag `latest`. +This example is the `buildNixShellImage` equivalent of [](#ex-dockerTools-streamNixShellImage-hello). - copyToRoot = pkgs.buildEnv { - name = "image-root"; - paths = [ binSh pkgs.fakeNss ]; - pathsToLink = [ "/bin" "/etc" "/var" ]; - }; +```nix +{ dockerTools, hello }: +dockerTools.buildNixShellImage { + drv = hello; + tag = "latest"; } ``` -## buildNixShellImage {#ssec-pkgs-dockerTools-buildNixShellImage} +The result of building this package is a `.tar.gz` file that can be loaded into Docker: + +```shell +$ nix-build +(some output removed for clarity) +/nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz + +$ docker load -i /nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz +(some output removed for clarity) +Loaded image: hello-2.12.1-env:latest +``` -Create a Docker image that sets up an environment similar to that of running `nix-shell` on a derivation. -When run in Docker, this environment somewhat resembles the Nix sandbox typically used by `nix-build`, with a major difference being that access to the internet is allowed. -It additionally also behaves like an interactive `nix-shell`, running things like `shellHook` and setting an interactive prompt. -If the derivation is fully buildable (i.e. `nix-build` can be used on it), running `buildDerivation` inside such a Docker image will build the derivation, with all its outputs being available in the correct `/nix/store` paths, pointed to by the respective environment variables like `$out`, etc. +After starting an interactive container, the derivation can be built by running `buildDerivation`, and the output can be executed as expected: -::: {.warning} -The behavior doesn't match `nix-shell` or `nix-build` exactly and this function is known not to work correctly for e.g. fixed-output derivations, content-addressed derivations, impure derivations and other special types of derivations. +```shell +$ docker run -it hello-2.12.1-env:latest +[nix-shell:~]$ buildDerivation +Running phase: unpackPhase +unpacking source archive /nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz +source root is hello-2.12.1 +(some output removed for clarity) +Running phase: fixupPhase +shrinking RPATHs of ELF executables and libraries in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1 +shrinking /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin/hello +checking for references to /build/ in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1... +gzipping man pages under /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/share/man/ +patching script interpreter paths in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1 +stripping (with command strip and flags -S -p) in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin + +[nix-shell:~]$ $out/bin/hello +Hello, world! +``` ::: -### Arguments {#ssec-pkgs-dockerTools-buildNixShellImage-arguments} +## streamNixShellImage {#ssec-pkgs-dockerTools-streamNixShellImage} + +`streamNixShellImage` builds a **script** which, when run, will stream to stdout a Docker-compatible repository tarball of an image that sets up an environment similar to that of running `nix-shell` on a derivation. +This means that `streamNixShellImage` does not output an image into the Nix store, but only a script that builds the image, saving on IO and disk/cache space, particularly with large images. +See [](#ex-dockerTools-streamNixShellImage-hello) to understand how to load in Docker the image generated by this script. -`drv` +The environment set up by `streamNixShellImage` somewhat resembles the Nix sandbox typically used by `nix-build`, with a major difference being that access to the internet is allowed. +It also behaves like an interactive `nix-shell`, running things like `shellHook` (see [](#ex-dockerTools-streamNixShellImage-addingShellHook)) and setting an interactive prompt. +If the derivation is buildable (i.e. `nix-build` can be used on it), running `buildDerivation` in the container will build the derivation, with all its outputs being available in the correct `/nix/store` paths, pointed to by the respective environment variables (e.g. `$out`). -: The derivation on which to base the Docker image. +::: {.caution} +The environment in the image doesn't match `nix-shell` or `nix-build` exactly, and this function is known not to work correctly for fixed-output derivations, content-addressed derivations, impure derivations and other special types of derivations. +::: - Adding packages to the Docker image is possible by e.g. extending the list of `nativeBuildInputs` of this derivation like +### Inputs {#ssec-pkgs-dockerTools-streamNixShellImage-inputs} - ```nix - buildNixShellImage { - drv = someDrv.overrideAttrs (old: { - nativeBuildInputs = old.nativeBuildInputs or [] ++ [ - somethingExtra - ]; - }); - # ... - } - ``` +`streamNixShellImage` expects one argument with the following attributes: - Similarly, you can extend the image initialization script by extending `shellHook` +`drv` (Attribute Set) -`name` _optional_ +: The derivation for which the environment in the image will be set up. + Adding packages to the Docker image is possible by extending the list of `nativeBuildInputs` of this derivation. + See [](#ex-dockerTools-streamNixShellImage-extendingBuildInputs) for how to do that. + Similarly, you can extend the image initialization script by extending `shellHook`. + [](#ex-dockerTools-streamNixShellImage-addingShellHook) shows how to do that. -: The name of the resulting image. +`name` (String; _optional_) - *Default:* `drv.name + "-env"` +: The name of the generated image. -`tag` _optional_ + _Default value:_ the value of `drv.name + "-env"`. + +`tag` (String or Null; _optional_) : Tag of the generated image. + If `null`, the hash of the nix derivation that builds the Docker image will be used as the tag. - *Default:* the resulting image derivation output path's hash + _Default value:_ `null`. + +`uid` (Number; _optional_) + +: The user ID to run the container as. + This can be seen as a `nixbld` build user. + + _Default value:_ 1000. -`uid`/`gid` _optional_ +`gid` (Number; _optional_) -: The user/group ID to run the container as. This is like a `nixbld` build user. +: The group ID to run the container as. + This can be seen as a `nixbld` build group. - *Default:* 1000/1000 + _Default value:_ 1000. -`homeDirectory` _optional_ +`homeDirectory` (String; _optional_) -: The home directory of the user the container is running as +: The home directory of the user the container is running as. - *Default:* `/build` + _Default value:_ `/build`. -`shell` _optional_ +`shell` (String; _optional_) -: The path to the `bash` binary to use as the shell. This shell is started when running the image. +: The path to the `bash` binary to use as the shell. + This shell is started when running the image. + This can be seen as an equivalent of the `NIX_BUILD_SHELL` [environment variable](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#environment-variables) for {manpage}`nix-shell(1)`. - *Default:* `pkgs.bashInteractive + "/bin/bash"` + _Default value:_ the `bash` binary from the `bashInteractive` package. -`command` _optional_ +`command` (String or Null; _optional_) -: Run this command in the environment of the derivation, in an interactive shell. See the `--command` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options). +: If specified, this command will be run in the environment of the derivation in an interactive shell. + A call to `exit` will be added after the command if it is specified, so the shell will exit after it's finished running. + This can be seen as an equivalent of the `--command` option in {manpage}`nix-shell(1)`. - *Default:* (none) + _Default value:_ `null`. -`run` _optional_ +`run` (String or Null; _optional_) -: Same as `command`, but runs the command in a non-interactive shell instead. See the `--run` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options). +: Similar to the `command` attribute, but runs the command in a non-interactive shell instead. + A call to `exit` will be added after the command if it is specified, so the shell will exit after it's finished running. + This can be seen as an equivalent of the `--run` option in {manpage}`nix-shell(1)`. - *Default:* (none) + _Default value:_ `null`. -### Example {#ssec-pkgs-dockerTools-buildNixShellImage-example} +### Examples {#ssec-pkgs-dockerTools-streamNixShellImage-examples} -The following shows how to build the `pkgs.hello` package inside a Docker container built with `buildNixShellImage`. +:::{.example #ex-dockerTools-streamNixShellImage-hello} +# Building a Docker image with `streamNixShellImage` with the build environment for the `hello` package + +This example shows how to build the `hello` package inside a Docker container built with `streamNixShellImage`. +The Docker image generated will have a name like `hello-<version>-env` and tag `latest`. +This example is the `streamNixShellImage` equivalent of [](#ex-dockerTools-buildNixShellImage-hello). ```nix -with import <nixpkgs> {}; -dockerTools.buildNixShellImage { +{ dockerTools, hello }: +dockerTools.streamNixShellImage { drv = hello; + tag = "latest"; } ``` -Build the derivation: +The result of building this package is a script. +Running this script and piping it into `docker load` gives you the same image that was built in [](#ex-dockerTools-buildNixShellImage-hello). + +```shell +$ nix-build +(some output removed for clarity) +/nix/store/8vhznpz2frqazxnd8pgdvf38jscdypax-stream-hello-2.12.1-env + +$ /nix/store/8vhznpz2frqazxnd8pgdvf38jscdypax-stream-hello-2.12.1-env | docker load +(some output removed for clarity) +Loaded image: hello-2.12.1-env:latest +``` + +After starting an interactive container, the derivation can be built by running `buildDerivation`, and the output can be executed as expected: -```console -nix-build hello.nix +```shell +$ docker run -it hello-2.12.1-env:latest +[nix-shell:~]$ buildDerivation +Running phase: unpackPhase +unpacking source archive /nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz +source root is hello-2.12.1 +(some output removed for clarity) +Running phase: fixupPhase +shrinking RPATHs of ELF executables and libraries in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1 +shrinking /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin/hello +checking for references to /build/ in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1... +gzipping man pages under /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/share/man/ +patching script interpreter paths in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1 +stripping (with command strip and flags -S -p) in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin + +[nix-shell:~]$ $out/bin/hello +Hello, world! ``` +::: - these 8 derivations will be built: - /nix/store/xmw3a5ln29rdalavcxk1w3m4zb2n7kk6-nix-shell-rc.drv - ... - Creating layer 56 from paths: ['/nix/store/crpnj8ssz0va2q0p5ibv9i6k6n52gcya-stdenv-linux'] - Creating layer 57 with customisation... - Adding manifests... - Done. - /nix/store/cpyn1lc897ghx0rhr2xy49jvyn52bazv-hello-2.12-env.tar.gz +:::{.example #ex-dockerTools-streamNixShellImage-extendingBuildInputs} +# Adding extra packages to a Docker image built with `streamNixShellImage` -Load the image: +This example shows how to add extra packages to an image built with `streamNixShellImage`. +In this case, we'll add the `cowsay` package. +The Docker image generated will have a name like `hello-<version>-env` and tag `latest`. +This example uses [](#ex-dockerTools-streamNixShellImage-hello) as a starting point. -```console -docker load -i result +```nix +{ dockerTools, cowsay, hello }: +dockerTools.streamNixShellImage { + tag = "latest"; + drv = hello.overrideAttrs (old: { + nativeBuildInputs = old.nativeBuildInputs or [] ++ [ + cowsay + ]; + }); +} ``` - 0d9f4c4cd109: Loading layer [==================================================>] 2.56MB/2.56MB - ... - ab1d897c0697: Loading layer [==================================================>] 10.24kB/10.24kB - Loaded image: hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz +The result of building this package is a script which can be run and piped into `docker load` to load the generated image. -Run the container: +```shell +$ nix-build +(some output removed for clarity) +/nix/store/h5abh0vljgzg381lna922gqknx6yc0v7-stream-hello-2.12.1-env -```console -docker run -it hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz +$ /nix/store/h5abh0vljgzg381lna922gqknx6yc0v7-stream-hello-2.12.1-env | docker load +(some output removed for clarity) +Loaded image: hello-2.12.1-env:latest +``` + +After starting an interactive container, we can verify the extra package is available by running `cowsay`: + +```shell +$ docker run -it hello-2.12.1-env:latest +[nix-shell:~]$ cowsay "Hello, world!" + _______________ +< Hello, world! > + --------------- + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || ``` +::: - [nix-shell:/build]$ +:::{.example #ex-dockerTools-streamNixShellImage-addingShellHook} +# Adding a `shellHook` to a Docker image built with `streamNixShellImage` -In the running container, run the build: +This example shows how to add a `shellHook` command to an image built with `streamNixShellImage`. +In this case, we'll simply output the string `Hello, world!`. +The Docker image generated will have a name like `hello-<version>-env` and tag `latest`. +This example uses [](#ex-dockerTools-streamNixShellImage-hello) as a starting point. -```console -buildDerivation +```nix +{ dockerTools, hello }: +dockerTools.streamNixShellImage { + tag = "latest"; + drv = hello.overrideAttrs (old: { + shellHook = '' + ${old.shellHook or ""} + echo "Hello, world!" + ''; + }); +} ``` - unpacking sources - unpacking source archive /nix/store/8nqv6kshb3vs5q5bs2k600xpj5bkavkc-hello-2.12.tar.gz - ... - patching script interpreter paths in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12 - checking for references to /build/ in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12... +The result of building this package is a script which can be run and piped into `docker load` to load the generated image. -Check the build result: +```shell +$ nix-build +(some output removed for clarity) +/nix/store/iz4dhdvgzazl5vrgyz719iwjzjy6xlx1-stream-hello-2.12.1-env -```console -$out/bin/hello +$ /nix/store/iz4dhdvgzazl5vrgyz719iwjzjy6xlx1-stream-hello-2.12.1-env | docker load +(some output removed for clarity) +Loaded image: hello-2.12.1-env:latest ``` - Hello, world! +After starting an interactive container, we can see the result of the `shellHook`: + +```shell +$ docker run -it hello-2.12.1-env:latest +Hello, world! + +[nix-shell:~]$ +``` +::: |