hoardix

= Hoardix
:release-version: 0.1.0
:url-gh: https://github.com/simonswine
:url-repo: {url-gh}/hoardix
:url-cachix: https://cachix.org
:url-cache-nix: https://nixos.wiki/wiki/Binary_Cache
:image-url-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png

{url-repo}[Hoardix] is a {url-cachix}[Cachix] API compatible {url-cache-nix}[binary cache for Nix] derivations.

== Usage

=== Configuration

[source,yaml]
----
# base url of how the cache is reached
#
# Cachix will be using the subdomain api.$base_domain to communicate with the
# API, while every cache defined in caches, will be available under its
# subdomain. So for the cachix to be reached it is advised to create a wildcard
# dns record pointing at this cache *.$base_domain.
base_url: http://localhost:5000

# modify http listen port. default: 5000
listen_port: 5000

# modify metrics listen port. default:9500
metric_listen_port: 9500

# define underlying storage for the cache
storage:
  s3:
   bucket: my-nixos-cache
   region: eu-central-1
   access_key: AKIA..
   secret_key: <redacted>

# map of caches with the key being the subdomain of the cache.
caches:
  private-cache:
    # ed25519 private key which will be used to sign uploaded narinfo files.
    #
    # This key can be generated using:
    # $ nix-store \
    #   --generate-binary-cache-key private-cache.cachix.my-domain.com \
    #   /dev/stdout /dev/null
    private_key: "private-cache.cachix.my-domain.com-1:<redacted>"

    # public caches can be read without authentication. default: false
    public: false

    # priority defines the cache's priority, when looking for cached
    # derivations. default: 41
    priority: 41

    # substituters allows to define upstream caches, which should be ignored
    # while uploading derivations.
    #
    # This is example is the default upstream nixos binary cache.
    substituters:
      - url: "https://cache.nixos.org"
        public_key: cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=

# this section shows how read and write tokens can be configured, which will
# authorize requests.
tokens:
  - static:
      tokens:
        - insecure-write-token
      mappings:
        - caches:
            - private-cache
          permission: write
  - static:
      tokens:
        - insecure-read-token-1
        - insecure-read-token-2
      mappings:
        - caches:
            - private-cache
          permission: read
----

=== Docker

[subs="attributes"]
----
$ docker run -p 5000:5000 simonswine/hoardix:v{release-version}
----

==== Setup cache

// Tested these and the following steps using docker run -t -i --net host nixos/nix:2.3.11

[source,shell]
----
$ CACHIX_AUTH_TOKEN=insecure-write-token cachix --host http://localhost:5000 use my-cache
----

==== Build hello world derivation and push it to the cache

[source,shell]
----
$ cat > my-build.nix <<EOF
{ nixpkgs ? import <nixpkgs> {} }:
let
  inherit (nixpkgs) pkgs;
in
  pkgs.writeText "hello.txt" "hello-hoardix"
EOF

$ CACHIX_AUTH_TOKEN=insecure-write-token cachix --host http://localhost:5000 push my-cache $(nix-build --no-out-link my-build.nix)
----

==== Get derivation

[source,shell]
----
$ STORE_PATH=$(nix-build --no-out-link my-build.nix)

# Delete existing derivation
$ nix-store --delete $STORE_PATH
1 store paths deleted, 0.00 MiB freed

# Download it again from the cache
$ nix-store -r $STORE_PATH
these paths will be fetched (0.00 MiB download, 0.00 MiB unpacked):
  /nix/store/98mzbdzn6vi2r65l8lqfjpp4sqpqrrv6-hello.txt
copying path '/nix/store/98mzbdzn6vi2r65l8lqfjpp4sqpqrrv6-hello.txt' from 'http://my-cache.localhost:5000'...
warning: you did not specify '--add-root'; the result might be removed by the garbage collector
/nix/store/98mzbdzn6vi2r65l8lqfjpp4sqpqrrv6-hello.txt
----