Docker image with Nix and Guix

We want to compare how to build a Docker image using Nix and Guix. We want to make it simple, thereof a simple example:

🐋 Docker

When the docker-compose up is executed and Docker images are missing, they are built from corresponding Dockerfiles. We are going to build them using Nix and Guix before the execution, so docker-compose up can use them.

Main difference between using Dockerfile and Nix or Guix is that Dockerfile contains commands to execute (to build Docker image) but relevant files of Nix or Guix contain relations of creation (of Docker image).

The steps to follow are in the damn-docker-nix-guix repository, here are notes about Nix and Guix approach.

❄ Nix

There are conventions about flake.nix content; there are many things flake.nix may contain. We are here today to see how Docker image is built, so I will skip explanation of Nix language oddities and rather aim on the goal. I wrote about Nix already:

Therefore, we need to add docker output. The function to create a docker image is buildImage from the dockerTools package.

Recall the steps from the Dockerfile: clone repo, install requirements, set working directory, set default command.

Then, we need to use this input in the attribute set parameter of the outputs function.

Setting default Cmd is copying the CMD from Dockerfile and removing commas.

followed by Python packages to install. Exact versions of Python packages and damn-server input are stored in flake.lock.

🦬 Guix

Because of the last point, we start our tour of Guix’s manifest in manifest.scm from the bottom line, respective from the beginning of the last expression.

is how a manifest is created from the list of packages, here only a single package stored in the damn-server variable.

Because Guix’s manifest is a list of packages and nothing more, we need to describe repository cloning as a package.

is where the repository is cloned. We can see that we need to specify the hash of the result. channels.scm keeps track of current Guix state, but not the state of our new package.

describes how to build the package. In our case, “to build package” means “to copy content of cloned repository somewhere”, therefore (build-system copy-build-system).

That (arguments ... expression is a bit cryptic, though. Let’s say that #:install-plan is a keyword argument for the copy-build-system and that its value, '(("." ".")), describes copying the content of the cloned repo (first ".") into manifest’s base directory (second ".").

(A manifest’s base directory is not. The true is that the second "." is a profile’s base directory and that Guix’s manifest is not just a list of packages, but a thing from which a profile with a list of packages available is created. However, I’m not yet ready to say what that means.)

Recall the steps from the Dockerfile: clone repo, install requirements, set working directory, set default command.

First two are described in manifest.scm. Last two need to be described as command line arguments, because Guix’s manifest only specifies a list of packages.

means that the result of subshell evaluation $( ... is loaded as Docker image.

is a combination of guix time-machine – the utility for reproducible builds, which uses channels.scm created earlier, and guix pack – the utility for bundling together Guix packages.

says that guix pack utility should use Guix’s manifest we created earlier as the source for a list of packages to bundle.

specifies the output format of the bundle – it will be Docker image; then Docker image name and Docker image entrypoint with entrypoint’s arguments.

creates symlink from /damn_server to the damn_server in the manifest’s base directory. We need this because / is Docker image’s working directory.

☯ Conclusion

We compare two approaches to build Docker image – Nix and Guix. Our use-case is to replace a Dockerfile in the working docker-compose up deployment.

We use Nix flake to specify how Docker image is built; there is a dedicated function to build a Docker image. We specify desired Git repository as input and use it directly as Docker image’s working directory.

Guix’s manifest is a list of packages. Therefore, we need to make new package from desired Git repository; new package describes cloning and copying the repository content. Then, new package is converted to Guix’s manifest.

Installing the requirements – Python packages – means, at the end, enumerating them for both, Nix and Guix. For Nix, it needs to be specified that the packages should be copied into the Docker image.

For Guix, the list of packages is converted to manifest. Then, both manifests, requirements’ and new package’s, are concatenated.

flake.nix:

{
  inputs.damn-server = {
      url = "git+https://git.sr.ht/~qeef/damn-server";
      flake = false;
  };

  outputs = {self, nixpkgs, damn-server}: let
    system = "x86_64-linux";
    pkgs = nixpkgs.legacyPackages.${system};
  in
    {
      docker =
        pkgs.dockerTools.buildImage
        {
          name = "damn-docker-nix-guix_api";
          tag = "latest";
          config = {
            Cmd = [
              "uvicorn"
              "damn_server.api:app"
              "--host" "0.0.0.0"
              "--port" "80"
            ];
            WorkingDir = damn-server;
            ExposedPorts = {
              "80/tcp" = {};
            };
          };
          copyToRoot =
            pkgs.buildEnv
            {
              name = "run-damn-server";
              paths = [
                (pkgs.python3.withPackages
                  (pypkgs: with pypkgs; [
                    uvicorn
                    fastapi
                    pyjwt
                    requests-oauthlib
                    itsdangerous
                    asyncpg
                  ]))
              ];
            };
        };
    };
}

manifest.scm:

(use-modules (guix packages)
             (guix git-download)
             (guix build-system copy)
             (guix licenses))

(define damn-server
  (package
    (name "damn-server")
    (version "master")
    (source
      (origin
        (method git-fetch)
        (uri
          (git-reference
            (url "https://git.sr.ht/~qeef/damn-server")
            (commit version)))
        (sha256
          (base32 "06wdh66phmccllf9m085br5zld773663w9bnkbfq45yihb3a88ws"))))
    (build-system copy-build-system)
    (arguments
      '(#:install-plan '(("." "."))))
    (synopsis "server part of the damn project")
    (description "server part of the damn project")
    (home-page "https://damn-project.org/")
    (license agpl3)))

(concatenate-manifests
  (list
    (specifications->manifest
      (list "python"
            "python-uvicorn"
            "python-fastapi"
            "python-pyjwt"
            "python-requests-oauthlib"
            "python-asyncpg"))
    (packages->manifest
      (list damn-server))))

No arguments are needed for Nix to build Docker image, all is in flake.nix. Also, flake.lock for pinning Nix package versions is used automatically.

Guix needs to know what to do with the manifest, the list of packages: pack them into Docker image format. It also needs Docker image-specific options like image name or entrypoint to be given as arguments. I did not find out how to set Docker image’s working directory, it’s /. And pinning of the Guix package versions needs to be done manually.

for Nix:

nix build .#docker
docker load < result
docker-compose up

for Guix:

docker load < $( \
  guix time-machine -C channels.scm -- pack \
  -m manifest.scm \
  -f docker \
  --image-tag=damn-docker-nix-guix_api \
  --entry-point=bin/uvicorn \
  -A 'damn_server.api:app' \
  -A '--host' -A '0.0.0.0' \
  -A '--port' -A '80' \
  -S /damn_server=damn_server)
docker-compose up

At the end, I am not saying if Nix or Guix is better. But I have opinion on which one feels better.