Update documentation

* README.org: Add new README that details how to use cuirass.genenetwork.org, and provides
links to other reference documents.
* docs/administration.org: Add a new, initially sparse, reference document detailing administration and
maintenance of cuirass.genenetwork.org.
* docs/initial-setup.org: Adjust abstract phrasing.

3 files changed, 100 insertions, 3 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
diff --git a/docs/administration.org b/docs/administration.org
new file mode 100644
index 0000000..8dd2b82
--- /dev/null
+++ b/docs/administration.org
@@ -0,0 +1,32 @@
+#+TITLE: Administration of cuirass.genenetwork.org
+#+AUTHOR: Collin J. Doering
+
+#+begin_abstract
+This document details maintenance and administration of cuirass.genenetwork.org.
+#+end_abstract
+
+* Updating cuirass.genenetwork.org
+
+1. Fetch the most recent channel file.
+
+   #+begin_src shell
+     curl -O https://git.genenetwork.org/guix-north-america/plain/channels.scm
+   #+end_src
+
+2. Update guix using the most recent channel file.
+
+   #+begin_src shell
+     sudo -i guix pull -C $(relapath channels.scm)
+   #+end_src
+
+3. Update the system.
+
+   #+begin_src shell
+     sudo guix system reconfigure -e '((@ (guix-na config balg02) balg02) %system)'
+   #+end_src
+
+4. Reboot.
+
+   #+begin_src shell
+     sudo reboot
+   #+end_src
diff --git a/docs/initial-setup.org b/docs/initial-setup.org
index 99c61a3..d7d2f28 100644
--- a/docs/initial-setup.org
+++ b/docs/initial-setup.org
@@ -1,9 +1,9 @@
-#+TITLE: Guix North America
+#+TITLE: Balg02 Initial Setup Instructions
 #+AUTHOR: Collin J. Doering
 
 #+begin_abstract
-This repository contains setup and management instructions for a Guix North American Build
-Farm.
+This document details the initial setup of a genenetwork.org sponsored server hosted at the
+University of Tennessee.
 #+end_abstract
 
 * Install Guix on debian to be used to bootstrap the Guix os installation