about summary refs log tree commit diff
path: root/third_party/nix/doc/manual/advanced-topics/post-build-hook.xml
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/nix/doc/manual/advanced-topics/post-build-hook.xml')
-rw-r--r--third_party/nix/doc/manual/advanced-topics/post-build-hook.xml160
1 files changed, 0 insertions, 160 deletions
diff --git a/third_party/nix/doc/manual/advanced-topics/post-build-hook.xml b/third_party/nix/doc/manual/advanced-topics/post-build-hook.xml
deleted file mode 100644
index 3dc43ee795b1..000000000000
--- a/third_party/nix/doc/manual/advanced-topics/post-build-hook.xml
+++ /dev/null
@@ -1,160 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      xml:id="chap-post-build-hook"
-      version="5.0"
-      >
-
-<title>Using the <xref linkend="conf-post-build-hook" /></title>
-<subtitle>Uploading to an S3-compatible binary cache after each build</subtitle>
-
-
-<section xml:id="chap-post-build-hook-caveats">
-  <title>Implementation Caveats</title>
-  <para>Here we use the post-build hook to upload to a binary cache.
-  This is a simple and working example, but it is not suitable for all
-  use cases.</para>
-
-  <para>The post build hook program runs after each executed build,
-  and blocks the build loop. The build loop exits if the hook program
-  fails.</para>
-
-  <para>Concretely, this implementation will make Nix slow or unusable
-  when the internet is slow or unreliable.</para>
-
-  <para>A more advanced implementation might pass the store paths to a
-  user-supplied daemon or queue for processing the store paths outside
-  of the build loop.</para>
-</section>
-
-<section>
-  <title>Prerequisites</title>
-
-  <para>
-    This tutorial assumes you have configured an S3-compatible binary cache
-    according to the instructions at
-    <xref linkend="ssec-s3-substituter-authenticated-writes" />, and
-    that the <literal>root</literal> user's default AWS profile can
-    upload to the bucket.
-  </para>
-</section>
-
-<section>
-  <title>Set up a Signing Key</title>
-  <para>Use <command>nix-store --generate-binary-cache-key</command> to
-  create our public and private signing keys. We will sign paths
-  with the private key, and distribute the public key for verifying
-  the authenticity of the paths.</para>
-
-  <screen>
-# nix-store --generate-binary-cache-key example-nix-cache-1 /etc/nix/key.private /etc/nix/key.public
-# cat /etc/nix/key.public
-example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
-</screen>
-
-<para>Then, add the public key and the cache URL to your
-<filename>nix.conf</filename>'s <xref linkend="conf-trusted-public-keys" />
-and <xref linkend="conf-substituters" /> like:</para>
-
-<programlisting>
-substituters = https://cache.nixos.org/ s3://example-nix-cache
-trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
-</programlisting>
-
-<para>we will restart the Nix daemon a later step.</para>
-</section>
-
-<section>
-  <title>Implementing the build hook</title>
-  <para>Write the following script to
-  <filename>/etc/nix/upload-to-cache.sh</filename>:
-  </para>
-
-  <programlisting>
-#!/bin/sh
-
-set -eu
-set -f # disable globbing
-export IFS=' '
-
-echo "Signing paths" $OUT_PATHS
-nix sign-paths --key-file /etc/nix/key.private $OUT_PATHS
-echo "Uploading paths" $OUT_PATHS
-exec nix copy --to 's3://example-nix-cache' $OUT_PATHS
-</programlisting>
-
-  <note>
-    <title>Should <literal>$OUT_PATHS</literal> be quoted?</title>
-    <para>
-      The <literal>$OUT_PATHS</literal> variable is a space-separated
-      list of Nix store paths. In this case, we expect and want the
-      shell to perform word splitting to make each output path its
-      own argument to <command>nix sign-paths</command>. Nix guarantees
-      the paths will not contain any spaces, however a store path
-      might contain glob characters. The <command>set -f</command>
-      disables globbing in the shell.
-    </para>
-  </note>
-  <para>
-    Then make sure the hook program is executable by the <literal>root</literal> user:
-    <screen>
-# chmod +x /etc/nix/upload-to-cache.sh
-</screen></para>
-</section>
-
-<section>
-  <title>Updating Nix Configuration</title>
-
-  <para>Edit <filename>/etc/nix/nix.conf</filename> to run our hook,
-  by adding the following configuration snippet at the end:</para>
-
-  <programlisting>
-post-build-hook = /etc/nix/upload-to-cache.sh
-</programlisting>
-
-<para>Then, restart the <command>nix-daemon</command>.</para>
-</section>
-
-<section>
-  <title>Testing</title>
-
-  <para>Build any derivation, for example:</para>
-
-  <screen>
-$ nix-build -E '(import &lt;nixpkgs&gt; {}).writeText "example" (builtins.toString builtins.currentTime)'
-these derivations will be built:
-  /nix/store/s4pnfbkalzy5qz57qs6yybna8wylkig6-example.drv
-building '/nix/store/s4pnfbkalzy5qz57qs6yybna8wylkig6-example.drv'...
-running post-build-hook '/home/grahamc/projects/github.com/NixOS/nix/post-hook.sh'...
-post-build-hook: Signing paths /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
-post-build-hook: Uploading paths /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
-/nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
-</screen>
-
-  <para>Then delete the path from the store, and try substituting it from the binary cache:</para>
-  <screen>
-$ rm ./result
-$ nix-store --delete /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
-</screen>
-
-<para>Now, copy the path back from the cache:</para>
-<screen>
-$ nix store --realize /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
-copying path '/nix/store/m8bmqwrch6l3h8s0k3d673xpmipcdpsa-example from 's3://example-nix-cache'...
-warning: you did not specify '--add-root'; the result might be removed by the garbage collector
-/nix/store/m8bmqwrch6l3h8s0k3d673xpmipcdpsa-example
-</screen>
-</section>
-<section>
-  <title>Conclusion</title>
-  <para>
-    We now have a Nix installation configured to automatically sign and
-    upload every local build to a remote binary cache.
-  </para>
-
-  <para>
-    Before deploying this to production, be sure to consider the
-    implementation caveats in <xref linkend="chap-post-build-hook-caveats" />.
-  </para>
-</section>
-</chapter>