Interact with the docker registry and generate nix build instructions https://github.com/awakesecurity/hocker#readme

Latest on Hackage:1.0.5

This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow stackage.org to host generated Haddocks.

Apache-2.0 licensed by Awake Security


The hocker package provides a small set of utilities to fetch docker image artifacts from docker registries and produce Nix derivations marrying docker and Nix elegantly:

  • hocker-image for fetching a docker image
  • hocker-layer for fetching a docker image’s layers
  • hocker-config for fetching a docker image’s configuration JSON
  • hocker-manifest for fetching a docker registry image manifest
  • docker2nix for generating Nix expressions calling the fetchdocker derivations, given a docker registry image manifest

These tools only work with version 2 of the docker registry and docker (>=) v1.10.

The motivation for this tool came from a need to fetch docker image artifacts from a docker registry without the stock docker tooling designed to only work with the docker daemon.

Our use case (and the reason why this package exposes a docker2nix tool) is pulling docker images into a NixOS system’s store and loading those images from the store into the docker daemon running on that same system.

We desired this for two critical reasons:

  1. The docker daemon no longer required an internet connection in order to load the docker images
  2. By virtue of fetching the docker images at build-time as opposed to run-time, failures from non-existent images or image tags are caught earlier

We strived to make this tool useful outside of the context of Nix and NixOS, therefore all of these tools are usable without Nix in the workflow.

For high-level documentation of each utility, please refer to the README’s in their respective directories (links are in the above list).


Let’s first retrieve a docker registry image manifest for the debian:jessie docker image (note that we need the library/ repository prefix because we are pulling from the official debian repository!):

$ hocker-manifest library/debian jessie
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
   "config": {
      "mediaType": "application/vnd.docker.container.image.v1+json",
      "size": 1528,
      "digest": "sha256:054abe38b1e6f863befa4258cbfaf127b1cc9440d2e2e349b15d22e676b591e7"
   "layers": [
         "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
         "size": 52550276,
         "digest": "sha256:cd0a524342efac6edff500c17e625735bbe479c926439b263bbe3c8518a0849c"

Next, we can easily generate a fetchdocker derivation using docker2nix:

$ hocker-manifest library/debian jessie | docker2nix library/debian jessie
{ fetchDockerConfig, fetchDockerLayer, fetchdocker }:
fetchdocker rec {
    name = "debian";
    registry = "https://registry-1.docker.io/v2/";
    repository = "library";
    imageName = "debian";
    tag = "jessie";
    imageConfig = fetchDockerConfig {
      inherit tag registry repository imageName;
      sha256 = "1rwinmvfc8jxn54y7qnj82acrc97y7xcnn22zaz67y76n4wbwjh5";
    imageLayers = let
      layer0 = fetchDockerLayer {
        inherit registry repository imageName;
        layerDigest = "cd0a524342efac6edff500c17e625735bbe479c926439b263bbe3c8518a0849c";
        sha256 = "1744l0c8ag5y7ck9nhr6r5wy9frmaxi7xh80ypgnxb7g891m42nd";
      in [ layer0 ];

Private registries

We developed these tools with private registries in-mind and they currently support three modes of authentication:

  1. Nothing at all (simply do not supply --token or --username and --password)
  2. Bearer token-based authentication, you should retrieve a token and then give it via the --token flag
  3. Basic authentication with --username and --password (most common with nginx proxied registries providing basic auth protection; you should be careful to ensure you’re only sending requests to registries exposed via TLS or SSL!)

A caveat to #1 if you do not supply any authentication credential flags and you also do not supply a --registry flag then the tools assume you wish to make a request to the public docker hub registry, in which case they ask for a short-lived authentication token from the registry auth server and then make the request to the public docker hub registry.

How to build

Building (and developing a patch for) this project using cabal is straight-forward if we have Nix installed:

$ nix-shell
[nix-shell:]$ cabal --version
cabal-install version
compiled using version of the Cabal library

cabal and all of the package dependencies will be in the shell environment so that we can then:

[nix-shell:]$ cabal build

Alternatively we can nix-build the project, this is not recommended for development because Nix will not build the project incrementally:

$ nix-build --attr hocker release.nix
these derivations will be built:
building path(s) ‘/nix/store/g16mrfhlmb1z3qkdzr0diaqn2dhl8bv6-hocker-’





  • Add the golden test data to the source distribution by using data-files instead of the incorrect data-dir, this fixes the problem of cabal test failing when run outside of the repository root on an unpacked tarball of the source distribution from Hackage
  • The failing response integrity check in hocker-image by removing the check, the fix and its rationale are exactly the same as applied to hocker-config and hocker-layer in the 1.0.2 release
  • Incorrect serialization of the registry URI in the fetchImage function, resulting in a malformed repository string that docker load would fail to import



  • Switched to the nix-paths library which provides compile-time constants for the Nix executables instead of relying on findexec and hoping Nix is on the PATH



  • readField implementations for the custom ParseField instances to accommodate a minor API change in optparse-generic version 1.2.3



  • hocker-config and hocker-layer fail the response integrity check (#23)
  • Missing test/data directory in cabal source distribution



  • hocker-manifest said it accepted the manifest list media type when requesting an image manifest for a docker image but it doesn’t know what to do with that, the manifest list accepts string has been removed


  • Initial release
comments powered byDisqus