### List Docker images Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Example output of the docker images command showing the created image. ```bash $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE hello latest 08c791c7846e 48 years ago 25.2MB ``` -------------------------------- ### Define a Docker image with buildImage Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Example configuration for building a Redis Docker image using buildImage. ```nix buildImage { name = "redis"; tag = "latest"; fromImage = someBaseImage; fromImageName = null; fromImageTag = "latest"; copyToRoot = pkgs.buildEnv { name = "image-root"; paths = [ pkgs.redis ]; pathsToLink = [ "/bin" ]; }; runAsRoot = '' #!${pkgs.runtimeShell} mkdir -p /data ''; config = { Cmd = [ "/bin/redis-server" ]; WorkingDir = "/data"; Volumes = { "/data" = { }; }; }; diskSize = 1024; buildVMMemorySize = 512; } ``` -------------------------------- ### Run the Docker Container Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Start an interactive session within the loaded Docker container. ```bash docker run -it hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz ``` -------------------------------- ### Build a Docker image with non-reproducible timestamp Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Example of setting the created attribute to 'now' to override the default static epoch timestamp. ```nix pkgs.dockerTools.buildImage { name = "hello"; tag = "latest"; created = "now"; copyToRoot = pkgs.buildEnv { name = "image-root"; paths = [ pkgs.hello ]; pathsToLink = [ "/bin" ]; }; config.Cmd = [ "/bin/hello" ]; } ``` -------------------------------- ### Get Image Parameters with nix-prefetch-docker Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Uses `nix-prefetch-docker` to obtain necessary parameters for pulling a Docker image, such as image name, tag, and digest. This command helps in gathering the required inputs for Nix functions. ```bash $ nix run nixpkgs.nix-prefetch-docker -c nix-prefetch-docker --image-name mysql --image-tag 5 ``` -------------------------------- ### Configure shadow-utils with shadowSetup Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Use shadowSetup within a runAsRoot script to initialize base files for user and group management. ```nix buildImage { name = "shadow-basic"; runAsRoot = '' #!${pkgs.runtimeShell} ${pkgs.dockerTools.shadowSetup} groupadd -r redis useradd -r -g redis redis mkdir /data chown redis:redis /data ''; } ``` -------------------------------- ### Configure image command execution Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Demonstrates how to set the Cmd configuration to run a specific binary within the container. ```nix pkgs.dockerTools.buildLayeredImage { name = "hello"; config.Cmd = [ "${pkgs.hello}/bin/hello" ]; } ``` -------------------------------- ### Include Environment Helpers in buildImage Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Demonstrates how to include essential environment helper utilities like `usrBinEnv`, `binSh`, `caCertificates`, and `fakeNss` within a `buildImage` derivation. These are necessary when building an image from scratch. ```nix buildImage { name = "environment-example"; copyToRoot = with pkgs.dockerTools; [ usrBinEnv binSh caCertificates fakeNss ]; } ``` -------------------------------- ### Specify OS and Architecture with nix-prefetch-docker Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Demonstrates how to use `nix-prefetch-docker` to specify the desired operating system and architecture for pulling a Docker image. This is useful when an image name refers to a manifest list supporting multiple platforms. ```bash $ nix-prefetch-docker --image-name mysql --image-tag 5 --arch x86_64 --os linux ``` -------------------------------- ### Environment Helpers Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Provides utility files like `env`, `bashInteractive`, CA certificates, and fake NSS databases to set up a basic environment for images built from scratch. ```APIDOC ## Environment Helpers ### Description 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` This provides the `env` utility at `/usr/bin/env`. ### `binSh` This provides `bashInteractive` at `/bin/sh`. ### `caCertificates` This sets up `/etc/ssl/certs/ca-certificates.crt`. ### `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). ``` -------------------------------- ### Build the Nix Derivation Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Execute the build process for the defined Nix shell image. ```bash nix-build hello.nix ``` -------------------------------- ### Verify Build Result Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Execute the built binary to verify the build was successful. ```bash $out/bin/hello ``` -------------------------------- ### Create a basic layered Docker image Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Defines a simple Docker image using the buildLayeredImage function with a single package in the contents. ```nix pkgs.dockerTools.buildLayeredImage { name = "hello"; contents = [ pkgs.hello ]; } ``` -------------------------------- ### Stream Docker Image for Skopeo Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Streams a Docker image as a gzipped tarball to stdout, suitable for piping into `skopeo` to copy to a registry. This is an alternative to `docker load` for registry operations. ```bash $(nix-build) | gzip --fast | skopeo copy docker-archive:/dev/stdin docker://some_docker_registry/myimage:tag ``` -------------------------------- ### Define a Nix Shell Image Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Use buildNixShellImage to create a container environment for a specific derivation. ```nix with import {}; dockerTools.buildNixShellImage { drv = hello; } ``` -------------------------------- ### Load the Docker Image Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Import the resulting tarball into the local Docker daemon. ```bash docker load -i result ``` -------------------------------- ### Provide user lookups with fakeNss Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Include fakeNss in the container root to provide basic /etc/passwd, /etc/group, and /etc/nsswitch.conf files. ```nix buildImage { name = "shadow-basic"; copyToRoot = pkgs.buildEnv { name = "image-root"; paths = [ binSh pkgs.fakeNss ]; pathsToLink = [ "/bin" "/etc" "/var" ]; }; } ``` -------------------------------- ### Set Final Image Name and Tag with nix-prefetch-docker Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Shows how to set the desired final image name and tag when using `nix-prefetch-docker`. These arguments control the name and tag of the image created in the Nix store, not for fetching. ```bash $ nix-prefetch-docker --image-name mysql --image-tag 5 --final-image-name eu.gcr.io/my-project/mysql --final-image-tag prod ``` -------------------------------- ### Export Docker Image Configuration Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Defines parameters for exporting a Docker image, analogous to `docker export`. This function flattens an image with multiple layers into a single tarball suitable for `docker import`. Requires the `kvm` device. ```nix exportImage { fromImage = someLayeredImage; fromImageName = null; fromImageTag = null; name = someLayeredImage.name; } ``` -------------------------------- ### Execute Build inside Container Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Run the buildDerivation command within the running container environment. ```bash buildDerivation ``` -------------------------------- ### Pull Docker Image Configuration Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Defines parameters for pulling a Docker image from a registry, analogous to `docker pull`. Specify image name, digest, desired final name and tag, checksum, OS, and architecture. ```nix pullImage { imageName = "nixos/nix"; imageDigest = "sha256:473a2b527958665554806aea24d0131bacec46d23af09fef4598eeab331850fa"; finalImageName = "nix"; finalImageTag = "2.11.1"; sha256 = "sha256-qvhj+Hlmviz+KEBVmsyPIzTB3QlVAFzwAY1zDPIBGxc="; os = "linux"; arch = "x86_64"; } ``` -------------------------------- ### buildLayeredImage Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Creates a Docker image where store paths are placed in their own layers to improve image sharing efficiency. ```APIDOC ## buildLayeredImage ### Description Creates a Docker image with many of the store paths being on their own layer to improve sharing between images. The image is realized into the Nix store as a gzipped tarball. ### Parameters #### Request Body - **name** (string) - Required - The name of the resulting image. - **tag** (string) - Optional - Tag of the generated image. Default: output path's hash. - **fromImage** (path) - Optional - The repository tarball containing the base image. Default: null. - **contents** (list) - Optional - Top-level paths in the container. Default: []. - **config** (object) - Optional - Run-time configuration of the container. Default: {}. - **architecture** (string) - Optional - Image architecture. Default: hostPlatform. - **created** (string) - Optional - Date and time the layers were created. Default: 1970-01-01T00:00:01Z. - **maxLayers** (integer) - Optional - Maximum number of layers to create. Default: 100, Max: 125. - **extraCommands** (string) - Optional - Shell commands to run while building the final layer. - **fakeRootCommands** (string) - Optional - Shell commands to run while creating the archive for the final layer in a fakeroot environment. - **enableFakechroot** (boolean) - Optional - Whether to run in fakeRootCommands in fakechroot. Default: false. ``` -------------------------------- ### buildImage Function Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools The buildImage function creates a Docker-compatible repository tarball. It supports various parameters to customize the image, including name, tag, base image, copied files, root execution scripts, configuration, and VM settings. ```APIDOC ## buildImage ### Description This function is analogous to the `docker build` command, in that it can be used to build a Docker-compatible repository tarball containing a single image with one or multiple layers. As such, the result is suitable for being loaded in Docker with `docker load`. ### Parameters * **name** (string) - Required - Specifies the name of the resulting image. * **tag** (string) - Optional - Specifies the tag of the resulting image. By default it's `null`, which indicates that the nix output hash will be used as tag. * **fromImage** (image tarball) - Optional - The repository tarball containing the base image. It must be a valid Docker image, such as exported by `docker save`. By default it's `null`, which can be seen as equivalent to `FROM scratch` of a `Dockerfile`. * **fromImageName** (string) - Optional - Can be used to further specify the base image within the repository, in case it contains multiple images. By default it's `null`, in which case `buildImage` will peek the first image available in the repository. * **fromImageTag** (string) - Optional - Can be used to further specify the tag of the base image within the repository, in case an image contains multiple tags. By default it's `null`, in which case `buildImage` will peek the first tag available for the base image. * **copyToRoot** (derivation) - Optional - A derivation that will be copied in the new layer of the resulting image. This can be similarly seen as `ADD contents/ /` in a `Dockerfile`. By default it's `null`. * **runAsRoot** (string) - Optional - A bash script that will run as root in an environment that overlays the existing layers of the base image with the new resulting layer, including the previously copied `contents` derivation. This can be similarly seen as `RUN ...` in a `Dockerfile`. * **config** (object) - Optional - Used to specify the configuration of the containers that will be started off the built image in Docker. The available options are listed in the Docker Image Specification v1.2.0. * **architecture** (string) - Optional - Used to specify the image architecture, this is useful for multi-architecture builds that don't need cross compiling. If not specified it will default to `hostPlatform`. * **diskSize** (integer) - Optional - Used to specify the disk size of the VM used to build the image in megabytes. By default it's 1024 MiB. * **buildVMMemorySize** (integer) - Optional - Used to specify the memory size of the VM to build the image in megabytes. By default it's 512 MiB. * **created** (string) - Optional - Allows setting a custom creation date for the image. Setting it to `"now"` provides a human-readable date, otherwise it defaults to a static date for binary reproducibility. ### Request Example ```nix buildImage { name = "redis"; tag = "latest"; fromImage = someBaseImage; fromImageName = null; fromImageTag = "latest"; copyToRoot = pkgs.buildEnv { name = "image-root"; paths = [ pkgs.redis ]; pathsToLink = [ "/bin" ]; }; runAsRoot = '' #!${pkgs.runtimeShell} mkdir -p /data ''; config = { Cmd = [ "/bin/redis-server" ]; WorkingDir = "/data"; Volumes = { "/data" = { }; }; }; diskSize = 1024; buildVMMemorySize = 512; } ``` ### Response * **image tarball** - A Docker-compatible repository tarball containing the built image. ### Notes * Using the `runAsRoot` parameter requires the `kvm` device to be available. * If you encounter errors like `getProtocolByName: does not exist (no such protocol name: tcp)`, you may need to add `pkgs.iana-etc` to `contents`. * If you encounter errors like `Error_Protocol ("certificate has unknown CA",True,UnknownCa)`, you may need to add `pkgs.cacert` to `contents`. * The resulting image will have a single layer and will be named `image/tag` (e.g., `redis/latest`). * The `created` field can be set to `"now"` to display a human-readable creation date in `docker images`, otherwise it defaults to a static date for binary reproducibility. ``` -------------------------------- ### Stream Docker Image as Tarball Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Builds a script to stream an uncompressed tarball of a Docker image to stdout. This method saves IO and disk space by not realizing the image into the Nix store. The output can be piped directly to `docker load`. ```bash $(nix-build) | docker load ``` -------------------------------- ### Extend buildNixShellImage derivation Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Modify the derivation used by buildNixShellImage by overriding nativeBuildInputs. ```nix buildNixShellImage { drv = someDrv.overrideAttrs (old: { nativeBuildInputs = old.nativeBuildInputs or [] ++ [ somethingExtra ]; }); # ... } ``` -------------------------------- ### streamLayeredImage Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Builds a script that streams an uncompressed tarball of a Docker image to stdout. This is useful for piping directly into `docker load` or other tools like `skopeo`. ```APIDOC ## streamLayeredImage ### Description Builds a script which, when run, will stream an uncompressed tarball of a Docker image to stdout. The arguments to this function are as for `buildLayeredImage`. This method of constructing an image does not realize the image into the Nix store, so it saves on IO and disk/cache space, particularly with large images. ### Usage The image produced by running the output script can be piped directly into `docker load`, to load it into the local docker daemon: ```bash $(nix-build) | docker load ``` Alternatively, the image be piped via `gzip` into `skopeo`, e.g., to copy it into a registry: ```bash $(nix-build) | gzip --fast | skopeo copy docker-archive:/dev/stdin docker://some_docker_registry/myimage:tag ``` ``` -------------------------------- ### Define image contents symlinks Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Shows the resulting symlinks created in the root of the image when using the buildLayeredImage function. ```text /bin/hello -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/bin/hello /share/info/hello.info -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/info/hello.info /share/locale/bg/LC_MESSAGES/hello.mo -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/locale/bg/LC_MESSAGES/hello.mo ``` -------------------------------- ### pullImage Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Analogous to the `docker pull` command, this function pulls a Docker image from a registry. It allows specifying image name, digest, final name/tag, OS, and architecture. ```APIDOC ## pullImage ### Description This function is analogous to the `docker pull` command, in that it can be used to pull a Docker image from a Docker registry. By default Docker Hub is used to pull images. ### Parameters - `imageName` (string) - Required - Specifies the name of the image to be downloaded, which can also include the registry namespace (e.g. `nixos`). - `imageDigest` (string) - Required - Specifies the digest of the image to be downloaded. - `finalImageName` (string) - Optional - The name of the image to be created. By default it's equal to `imageName`. - `finalImageTag` (string) - Optional - The tag of the image to be created. By default it's `latest`. - `sha256` (string) - Required - The checksum of the whole fetched image. - `os` (string) - Optional - The operating system of the fetched image. By default it's `linux`. - `arch` (string) - Optional - The cpu architecture of the fetched image. By default it's `x86_64`. ### Example Usage ```nix pullImage { imageName = "nixos/nix"; imageDigest = "sha256:473a2b527958665554806aea24d0131bacec46d23af09fef4598eeab331850fa"; finalImageName = "nix"; finalImageTag = "2.11.1"; sha256 = "sha256-qvhj+Hlmviz+KEBVmsyPIzTB3QlVAFzwAY1zDPIBGxc="; os = "linux"; arch = "x86_64"; } ``` ### Nix Prefetch Docker The `nix-prefetch-docker` command can be used to get required image parameters: ```bash $ nix run nixpkgs.nix-prefetch-docker -c nix-prefetch-docker --image-name mysql --image-tag 5 ``` To specify OS and architecture: ```bash $ nix-prefetch-docker --image-name mysql --image-tag 5 --arch x86_64 --os linux ``` To set desired image name and tag: ```bash $ nix-prefetch-docker --image-name mysql --image-tag 5 --final-image-name eu.gcr.io/my-project/mysql --final-image-tag prod ``` ``` -------------------------------- ### exportImage Source: https://ryantm.github.io/nixpkgs/builders/images/dockertools Flattens a Docker image containing multiple layers into a single layer, suitable for importing into Docker using `docker import`. ```APIDOC ## exportImage ### Description This function is analogous to the `docker export` command, in that it can be used to flatten a Docker image that contains multiple layers. It is in fact the result of the merge of all the layers of the image. As such, the result is suitable for being imported in Docker with `docker import`. > **_NOTE:_** Using this function requires the `kvm` device to be available. ### Parameters - `fromImage` - Required - The layered image to export. - `fromImageName` (string) - Optional - The name of the source image. - `fromImageTag` (string) - Optional - The tag of the source image. - `name` (string) - Optional - The name of the derivation output, which defaults to `fromImage.name`. ### Example Usage ```nix exportImage { fromImage = someLayeredImage; fromImageName = null; fromImageTag = null; name = someLayeredImage.name; } ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.