{"id":14968027,"url":"https://github.com/awakesecurity/hocker","last_synced_at":"2025-04-12T16:39:36.939Z","repository":{"id":20747541,"uuid":"90800182","full_name":"awakesecurity/hocker","owner":"awakesecurity","description":"Utilities for interacting with the docker registry and generating nix build instructions","archived":false,"fork":false,"pushed_at":"2024-10-08T16:21:43.000Z","size":161,"stargazers_count":114,"open_issues_count":5,"forks_count":8,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-10-30T02:48:07.646Z","etag":null,"topics":["command-line","docker","docker-registry","docker-registry-v2","haskell","library","nix","nixos","nixpkgs"],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awakesecurity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-09T23:16:17.000Z","updated_at":"2024-10-22T07:49:23.000Z","dependencies_parsed_at":"2024-11-12T21:04:26.420Z","dependency_job_id":"4a0be057-fdd6-42c9-8650-936639cd8c5f","html_url":"https://github.com/awakesecurity/hocker","commit_stats":{"total_commits":56,"total_committers":11,"mean_commits":5.090909090909091,"dds":0.4285714285714286,"last_synced_commit":"c7485f35ae8846ad4a7d2c5d8afba37f2c45900e"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awakesecurity%2Fhocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awakesecurity%2Fhocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awakesecurity%2Fhocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awakesecurity%2Fhocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awakesecurity","download_url":"https://codeload.github.com/awakesecurity/hocker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248598252,"owners_count":21131051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","docker","docker-registry","docker-registry-v2","haskell","library","nix","nixos","nixpkgs"],"created_at":"2024-09-24T13:39:07.932Z","updated_at":"2025-04-12T16:39:36.917Z","avatar_url":"https://github.com/awakesecurity.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Welcome!\nThe `hocker` package provides a small set of utilities to fetch docker image\nartifacts from docker registries and produce Nix derivations marrying docker and\nNix elegantly:\n\n- [`hocker-image`](./hocker-image/README.md) for fetching a docker image\n- [`hocker-layer`](./hocker-layer/README.md) for fetching a docker image's layers\n- [`hocker-config`](./hocker-config/README.md) for fetching a docker image's configuration JSON\n- [`hocker-manifest`](./hocker-manifest/README.md) for fetching a docker registry image manifest\n- [`docker2nix`](./docker2nix/README.md) for generating Nix expressions calling the `fetchdocker`\n  derivations, given a docker registry image manifest\n  \nThese tools _only_ work with version 2 of the **docker registry** and **docker\n(\u003e=) v1.10**.\n\nThe motivation for this tool came from a need to fetch docker image artifacts\nfrom a docker registry without the stock docker tooling designed to only work\nwith the docker daemon.\n\nOur use case (and the reason why this package exposes a `docker2nix` tool) is pulling\ndocker images into a [NixOS system's store](https://nixos.org/nix/manual/#ch-about-nix) and \nloading those images from the store into the docker daemon running on that same system.\n\nWe desired this for two critical reasons:\n1. The docker daemon no longer required an internet connection in order to load\n   the docker images\n2. By virtue of fetching the docker images at build-time as opposed to run-time,\n   failures from non-existent images or image tags are caught earlier\n\nWe strived to make this tool useful outside of the context of Nix and NixOS,\ntherefore all of these tools are usable without Nix in the workflow.\n\nFor high-level documentation of each utility, please refer to the README's in\ntheir respective directories (links are in the above list).\n\n## Quickstart\nLet's first retrieve a docker registry image manifest for the `debian:jessie`\ndocker image (note that we need the `library/` repository prefix because we are\npulling from the official debian repository!):\n\n```shell\n$ hocker-manifest library/debian jessie\n{\n   \"schemaVersion\": 2,\n   \"mediaType\": \"application/vnd.docker.distribution.manifest.v2+json\",\n   \"config\": {\n      \"mediaType\": \"application/vnd.docker.container.image.v1+json\",\n      \"size\": 1528,\n      \"digest\": \"sha256:054abe38b1e6f863befa4258cbfaf127b1cc9440d2e2e349b15d22e676b591e7\"\n   },\n   \"layers\": [\n      {\n         \"mediaType\": \"application/vnd.docker.image.rootfs.diff.tar.gzip\",\n         \"size\": 52550276,\n         \"digest\": \"sha256:cd0a524342efac6edff500c17e625735bbe479c926439b263bbe3c8518a0849c\"\n      }\n   ]\n}\n```\n\nNext, we can easily generate a `fetchdocker` derivation using `docker2nix`:\n\n```shell\n$ hocker-manifest library/debian jessie | docker2nix library/debian jessie\n{ fetchDockerConfig, fetchDockerLayer, fetchdocker }:\nfetchdocker rec {\n    name = \"debian\";\n    registry = \"https://registry-1.docker.io/v2/\";\n    repository = \"library\";\n    imageName = \"debian\";\n    tag = \"jessie\";\n    imageConfig = fetchDockerConfig {\n      inherit tag registry repository imageName;\n      sha256 = \"1rwinmvfc8jxn54y7qnj82acrc97y7xcnn22zaz67y76n4wbwjh5\";\n    };\n    imageLayers = let\n      layer0 = fetchDockerLayer {\n        inherit registry repository imageName;\n        layerDigest = \"cd0a524342efac6edff500c17e625735bbe479c926439b263bbe3c8518a0849c\";\n        sha256 = \"1744l0c8ag5y7ck9nhr6r5wy9frmaxi7xh80ypgnxb7g891m42nd\";\n      };\n      in [ layer0 ];\n  }\n```\n\n## Private registries\nWe developed these tools with private registries in-mind and they currently\nsupport three modes of authentication:\n\n1. Nothing at all (simply do not supply `--token` or `--username` and\n   `--password`)\n2. Bearer token-based authentication, you should retrieve a token and then give\n   it via the `--token` flag\n3. Basic authentication with `--username` and `--password` (most common with\n   nginx proxied registries providing basic auth protection; you should be\n   careful to ensure you're only sending requests to registries exposed via TLS\n   or SSL!)\n\nA caveat to #1 if you do not supply any authentication credential flags and you\nalso do not supply a `--registry` flag then the tools assume you wish to make a\nrequest to the public docker hub registry, in which case they ask for a\nshort-lived authentication token from the registry auth server and then make the\nrequest to the public docker hub registry.\n\nBoth types of credential may instead be passed as file using `--credential-file`.\nThe credential file should contain either:\n```\nUSERNAME=\u003cusername\u003e\nPASSWORD=\u003cpassword\u003e\n```\nor\n```\nBEARER_TOKEN=\u003ctoken\u003e\n```\n\n## How to build\n\nBuilding (and developing a patch for) this project using `cabal` is\nstraight-forward if we have Nix installed:\n\n```bash\n$ nix-shell\n[nix-shell:]$ cabal --version\ncabal-install version 1.24.0.2\ncompiled using version 1.24.2.0 of the Cabal library\n```\n\n... `cabal` and all of the package dependencies will be in the shell environment\nso that we can then:\n\n```bash\n[nix-shell:]$ cabal build\n```\n\nAlternatively we can `nix-build` the project, this is not recommended for\ndevelopment because Nix will not build the project incrementally:\n\n```bash\n$ nix-build --attr hocker release.nix\nthese derivations will be built:\n  /nix/store/3dwvcm66360fpfqrrc4swp9y4q0jzvh9-hocker-0.1.0.0.drv\nbuilding path(s) ‘/nix/store/g16mrfhlmb1z3qkdzr0diaqn2dhl8bv6-hocker-0.1.0.0’\n...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawakesecurity%2Fhocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawakesecurity%2Fhocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawakesecurity%2Fhocker/lists"}