nix2container

To speed up build and push times, you can use the layers attribute in buildImage to specify a set of dependencies that should be isolated. If the dependencies in these layers do not change, the layers are not rebuilt or re-pushed.

Example: Isolating a script from its dependencies

{ pkgs }: 
let
  application = pkgs.writeScript "conversation" ''
    ${pkgs.hello}/bin/hello
    echo "Haaa aa... I'm dying!!!"
  '';
in
pkgs.nix2container.buildImage {
  name = "hello";
  config = {
    entrypoint = ["${pkgs.bash}/bin/bash" application];
  };
  layers = [
    (pkgs.nix2container.buildLayer { deps = [pkgs.bash pkgs.hello]; })
  ];
}

This configuration results in two layers: one containing the bash and hello closures, and a second containing only the script.

You can run the project's test suite using Nix. The tests build example images with Nix, load them with Skopeo, and run them with Podman to verify output logs. Note that these tests are not executed within the Nix sandbox due to current limitations regarding running containers in the sandbox.

To run all tests:

nix run .#tests.all

To run only the basic tests:

nix run .#tests.basic

To use nix2container, add it as an input to your Nix flake. You can then use nix2container.packages.<system>.nix2container.buildImage to define container images. Once defined, you can load the image into a container daemon (like Docker or Podman) using the .copyToDockerDaemon or .copyToPodman attributes provided by the package.

{
  inputs.nix2container.url = "github:nlewo/nix2container";

  outputs = { self, nixpkgs, nix2container }: let
    pkgs = import nixpkgs { system = "x86_64-linux"; };
    nix2containerPkgs = nix2container.packages.x86_64-linux;
  in {
    packages.x86_64-linux.hello = nix2containerPkgs.nix2container.buildImage {
      name = "hello";
      config = {
        entrypoint = ["${pkgs.hello}/bin/hello"];
      };
    };
  };
}

To load and run:

$ nix run .#hello.copyToDockerDaemon
$ docker run hello:latest

If using the Nix daemon for building, follow these steps to set up registry authentication:

1. Perform a docker login URL to the target registry.
2. Copy ~/.docker/config.json to /etc/nix/skopeo/auth.json.
3. Ensure the directory and files are readable by the nixbld group:

   sudo chmod -R g+rx /etc/nix/skopeo
   sudo chgrp -R nixbld /etc/nix/skopeo

4. Bind mount the file into the Nix build sandbox using the extra-sandbox-paths option:

   extra-sandbox-paths = /etc/skopeo/auth.json=/etc/nix/skopeo/auth.json

The nix2container.pullImage function pulls an image from a container registry by name and tag/digest, storing the manifest and layer tarballs in a single store path.

Arguments:

• imageName (required): The name of the image.
• imageDigest (required): The digest of the image.
• sha256 (required): The sha256 of the resulting fixed output derivation.
• os (default: linux)
• arch (default: x86_64)
• tlsVerify (default: true)

The nix2container.pullImageFromManifest function pulls a base image using a supplied manifest.json. This is more efficient than pullImage because:

• Each layer is in its own store path, allowing for natural deduplication across multiple base images.
• It avoids Nix-specific hashes, allowing updates by simply re-fetching the manifest.json.

Arguments:

• imageName (required): The name of the image.
• imageManifest (required): The manifest file path.
• imageTag (default: latest)
• os (default: linux)
• arch (default: x86_64)
• tlsVerify (default: true)
• registryUrl (default: registry.hub.docker.com)

Note: imageTag, os, and arch are used for manifest-selection logic in the included getManifest script and do not affect the pulled image content itself.

You can enable debug-level logging by using the --debug or -d flag. This will cause the application to output debug logs using logrus.

container2nix --debug
# or
container2nix -d

Both layers-from-reproducible-storepaths and layers-from-non-reproducible-storepaths support the following configuration flags to refine how layers are constructed:

Use the image-from-manifest command to write an image.json file from a raw Skopeo manifest and a JSON file containing blobs.

Arguments:

• OUTPUT-FILENAME: The path where the resulting image.json will be written.
• MANIFEST.JSON: The path to the manifest JSON file.
• BLOBS.JSON: The path to the blobs JSON file.

Example:

image-from-manifest output.json manifest.json blobs.json

image-from-manifest OUTPUT-FILENAME MANIFEST.JSON BLOBS.JSON