1 files changed, 65 insertions, 0 deletions
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..c57b063
--- /dev/null
+++ b/README.org
@@ -0,0 +1,65 @@
+#+TITLE: Guix North America
+#+AUTHOR: Collin J. Doering
+
+#+begin_abstract
+This repository contains setup and management instructions for a Guix North American Build
+Farm.
+#+end_abstract
+
+* Using Substitutes from cuirass.genenetwork.org
+
+** On Guix System
+
+If you're using Guix System, you can use the cuirass.genenetwork.org substitute
+server completing the following:
+
+1. Add ~https://cuirass.genenetwork.org~ to the list of substitute servers (using the
+   ~substitute-urls~ field of ~guix-configuration~ passed to the ~guix-daemon~ service).
+
+2. Adjust guix-daemon ACLs to include the following public key (using the
+   ~authorized-keys~ field of ~guix-configuration~ passed to the ~guix-daemon~ service).
+
+   #+begin_src scheme
+   (public-key
+    (ecc
+     (curve Ed25519)
+     (q #9578AD6CDB23BA51F9C4185D5D5A32A7EEB47ACDD55F1CCB8CEE4E0570FBF961#)
+     )
+   )
+   #+end_src
+
+   In the future, we hope to work with Guix maintainers to include this substitute
+   server as one of the provided Guix System defaults.
+
+** On Foreign Distributions
+
+When using Guix on a foreign distribution, you'll need to do the following to enable
+substitutes from cuirass.genenetwork.org:
+
+1. Add the public key (provided above) for cuirass.genenetwork.org to the guix-daemon ACLs.
+
+   #+begin_src shell
+     sudo guix archive --authorize < cuirass.genenetwork.org.pub
+   #+end_src
+
+2. Add the substitute url using the ~--substitute-urls~ option to guix-daemon. Assuming your
+   foreign distribution uses systemd, this can be done using the following.
+
+   #+begin_src shell
+     sudo systemctl edit --full guix-daemon
+   #+end_src
+
+   If you want to just use ci.guix.gnu.org, or cuirass.genenetwork.org for that matter,
+   you'll need to adjust the substitute URLs configuration for the guix-daemon to just refer
+   to the substitute servers you want to use. Once edited and saved, restart the guix daemon.
+
+   #+begin_src shell
+     sudo systemctl restart guix-daemon.service
+   #+end_src
+
+* Reference
+
+- [[./docs/initial-setup.org][Intial Setup Instructions]] :: Details the initial setup of a genenetwork.org sponsored,
+  single node build farm.
+- [[./docs/administration.org][Administration of cuirass.genenetwork.org]] :: details maintenance and administration of
+  cuirass.genenetwork.org