Final review and adjustments; sending for review blog-article

1 files changed, 112 insertions, 112 deletions

diff --git a/docs/blog-Tennnessee-build-farm.org b/docs/blog-Tennnessee-build-farm.org
index 664c168..f612de2 100644
--- a/docs/blog-Tennnessee-build-farm.org
+++ b/docs/blog-Tennnessee-build-farm.org
@@ -74,9 +74,9 @@ packages (either in addition to GNU Guix, or a subset thereof).
 
 For more details, see the [[https://guix.gnu.org/cuirass/manual/cuirass.html#Specifications][Specifications section]] of the Cuirass Manual.
 
-Further measurement and analysis of exactly the hardware requirements for building GNU Guix
-and its various packages would be valuable to the Guix community, but we have not yet done
-such an analysis using our build farm.
+Further measurement and analysis to more precisely determine hardware requirements for
+building GNU Guix and its various packages would be valuable to the Guix community, but we
+have not yet done such an analysis using our build farm.
 
 * Components of the Guix Build Farm
 
@@ -142,7 +142,7 @@ which is used in the ~services~ field of ~operating-system~ definition.
 
 Similar to Cuirass, access to guix-publish will be provided through nginx as a reverse proxy.
 
-** Anonomizing IPs (anonip)
+** Anonomizing IPs in logs using anonip
 
 Guix users care about their privacy, and though this is not necessarily a requirement,
 anonymizing nginx access logs using the anonip is implemented by all public Guix sponsored
@@ -191,7 +191,7 @@ corresponding anonip-service. This can be added to the ~services~ field of our
   (map anonip-service %anonip-nginx-log-files)
 #+end_src
 
-** Providing web access - Nginx Reverse Proxy
+** ProvidIng Web Access - Nginx Reverse Proxy
 
 Nginx is arguably the most complicated part of the setup. This section touches on the
 essential details of configuring nginx to act as a reverse proxy for both guix-publish, and
@@ -362,7 +362,7 @@ nginx-location-configuration in the list that will be returned from our function
   manually fetch a substitute. Here we will continue, using the provided hash to query to
   query the substitute server for a corresponding ~.narinfo~ file.
 
-  #+begin_src shell :results output :eval no-export
+  #+begin_src shell :results output :exports both :eval no-export
     curl https://cuirass.genenetwork.org/8bjy9g0cssjrw9ljz2r8ww1sma95isfj.narinfo
   #+end_src
 
@@ -477,7 +477,7 @@ function.
 - ~/~
 
   Cuirass and its routes should be accessible, which exactly what the below
-  nginx-configuration does! It proxies traffic to the ~guix-publish~ service (which is
+  nginx-configuration does! It proxies traffic to the ~cuirass~ service (which is
   assumed to be running at its default location).
 
   #+begin_src scheme
@@ -623,7 +623,7 @@ our log files through anonip which we previously configured.
      "proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;")))
 #+end_src
 
-Our last ~nginx-server-configuration~ configures nginx to liston for HTTPS traffic on its
+Our last ~nginx-server-configuration~ configures nginx to listen for HTTPS traffic on its
 default port (443); it is nearly identical to the previous ~nginx-server-configuration~, but
 makes use of the ~le~ lets encrypt helper function we defined earlier to lookup the
 appropriate ssh certificate or key.
@@ -810,97 +810,76 @@ defaults.
                                                  #:build-accounts-to-max-jobs-ratio 5)))
 #+end_src
 
-* Installation
-
-We've left out other aspects of defining our ~operating-system~ configuration, as its [[https://guix.gnu.org/manual/devel/en/html_node/operating_002dsystem-Reference.html][well
-documented]] by the Guix project, and varies depending on the specifics of your machine (for
-instance, file-systems, users/groups, initrd-modules, etc..). Once assembled, the
-~operating-system~ configuration can be placed in a file ~system.scm~, which defines a guix
-system configured with Cuirass, guix-publish, guix-daemon, and nginx, setup to act as a
-single-node build farm and substitute server! It can be trivially installed following the
-[[https://guix.gnu.org/manual/en/html_node/Proceeding-with-the-Installation.html][manual Guix System installation documentation]].
-
-#+begin_src shell :eval no
-  guix system init system.scm /mnt
-#+end_src
+* First Boot
 
-Here ~/mnt~ is where the target root file-system is mounted after being prepared for
-installation. See our [[https://git.genenetwork.org/guix-north-america/tree/docs/initial-setup.org][Initial Setup Documentation]] for the specifics of preparing the disks
-for Guix installation in our case.
+There are some opportunities to improve our deployment, as currently it requires manual
+intervention after the initial installation. Here we'll detail whats necessary.
 
-** Remotely Bootstrapping Guix from Debian
+** Setup dhparams
 
-In our case with the Tennessee Build Farm, physical access was inconvenient due to travel
-distance, so installation needed to be completed remotely. The target server already had
-Debian running on it, configured with serial access available out-of-band via [[https://en.wikipedia.org/wiki/Dell_DRAC][Dell iDRAC]] as
-well as ssh access to Debian. Another ssd was available for use, and was the target of our
-Guix installation.
+Earlier in [[*Configure Nginx Server Blocks][Configure Nginx Server Blocks]], we specified our own DH parameters, as suggested by
+https://weakdh.org/sysadmin.html. We need to create them after the first boot of our build farm.
 
-Guix can be [[https://guix.gnu.org/manual/en/html_node/Binary-Installation.html][installed on foreign distributions]], which is well documented, so its not covered
-here, but is the first step in bootstrapping Guix from Debian.
+#+begin_src shell :eval no
+  openssl dhparam -out /etc/dhparams.pem 2048
+#+end_src
 
-*** Guix Configuration as a Channel
+** Setup Certificate Authority and Client Certificates for Cuirass Administration
 
-Once Guix (the package manager) is installed on Debian, we need to ensure partition our
-drives as required (which again varies, so will not be covered here). Next we need to make
-our ~operating-system~ configuration available so we can complete bootstrapping Guix. The
-most straightforward way to do so is to just copy ~system.scm~ file we defined earlier.
-Another way is to capture the configuration in a git repository, and [[https://guix.gnu.org/manual/en/html_node/Creating-a-Channel.html][make it a Guix channel]].
-This enables great shared tracking of system changes over time (outside of [[https://guix.gnu.org/manual/en/html_node/Invoking-guix-system.html][guix system
-list-generations ...]]), and is what was done while bootstrapping our installation.
+Setup of SSL/TLS client side certificates is beyond the scope of this article, however we
+will briefly mention and demonstrate how the [[https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git/tree/etc/new-client-cert.scm][etc/new-client-cert.scm]] script that is part of
+the Cuirass repository (but not in the provided cuirass guix package) can be adjusted to fit
+the needs of most Cuirass deployments.
 
-We choose to include a ~channels.scm~ file as part of the configuration channel that pins the
-versions of software that will be used with our deployment. So, in order to boot the server
-using an ~operating-system~ defined in [[https://git.genenetwork.org/guix-north-america/][our configuration channel]], we first download the
-~channels.scm~ file.
+First fetch the script and make it executable.
 
 #+begin_src shell :eval no
-  curl -O https://git.genenetwork.org/guix-north-america/plain/channels.scm
+  curl -O https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git/tree/etc/new-client-cert.scm
+  chmod +x new-client-cert.scm
 #+end_src
 
-We then create a temporary ~bootstrap.scm~ file that contains a references to the
-~operating-system~ we defined in our configuration channel.
+This script leverages ~guix~ itself to be run, so its necessary to be running on a system
+with guix installed in order to use this script. For more details on how this is done, see
+the note on the [[https://guix.gnu.org/manual/devel/en/html_node/Invoking-guix-shell.html][Invoking guix shell]] documentation about "guix shell can also be used as a
+script interpreter".
 
-#+begin_src scheme
-  (@ (guix-na config balg02) balg02)
-#+end_src
+The script currently needs to be slightly adjusted to alter the ~subject-template~ being
+used, which by default is ~"/C=DE/ST=Berlin/L=Berlin/O=GNU Guix/OU=Cuirass/CN=~a"~ - this
+string defines the openssl subject name used when generating a CA and client certificates,
+where ~~a~ will be substituted for a name later on. Here you may want to adjust the location,
+organization, etc.. to suite your case.
 
-We then use ~guix time-machine~ to specify these channels when installing Guix onto the
-system.
+First a Certificate Authority needs to be generated. This should be done from the cuirass
+server itself so the CA key never leaves the server its being used on, and can be done with
+the ~new-client-cert.scm~ script as follows.
 
 #+begin_src shell :eval no
-  guix time-machine -C channels.scm -- system init bootstrap.scm /mnt
+  ./new-client-cert.scm --generate-ca
 #+end_src
 
-Subsequent updates to the system can be done without using the ~bootstrap.scm~ file. For
-instance, say the guix channel is updated in ~channels.scm~. To apply this change to the
-server, the new channels would need to be pulled, and the system reconfigured.
+By default, this generates a CA key ~/etc/ssl-ca/private/ca.key~ and certificate
+~/etc/ssl-ca/certs/ca.crt~, so is important to ensure these directories already exist and are
+writable by the user running the script.
 
 #+begin_src shell :eval no
-  sudo -i guix pull -C <(curl https://git.genenetwork.org/guix-north-america/plain/channels.scm)
-  sudo -i guix system reconfigure -e '(@ (guix-na config balg02) balg02)'
+  mkdir -p /etc/ssl-ca/{private,cert}
 #+end_src
 
-One caveat to using ~-e|--expression~ is that currently this expression is not stored along
-side the guix system generation, which makes it not possible to know which ~operating-system~
-configuration was used from a given channel (reported upstream as issue [[https://issues.guix.gnu.org/54631][#54631]]). To work
-around this for the time being, a file containing this expression can be used (just like was
-used for bootstrapping).
-
-* First Boot
-
-There are some opportunities to improve our deployment, as currently it requires manual
-intervention after the initial installation. Here we'll detail whats necessary.
-
-** Setup dhparams
-
-Earlier in [[*Configure Nginx Server Blocks][Configure Nginx Server Blocks]], we specified our own DH parameters, as suggested by
-https://weakdh.org/sysadmin.html. We need to create them after the first boot of our build farm.
+With the CA in place, one or more client certificates can now be generated. First, clients
+will need to supply a Certificate Signing Request (CSR), which should be placed in the
+current working directory and named ~<who>.csr~ where ~<who>~ should be the name of the
+certificate signing request (eg. ~collin.csr~). We can then run the following to generate a
+signed client certificate, which will be outputted as ~<who>.p12~ in the current working
+directory.
 
-#+begin_src shell :eval no
-  openssl dhparam -out /etc/dhparams.pem 2048
+#+begin_src shell
+  ./new-client-cert.scm collin
 #+end_src
 
+The ~collin.p12~ [[https://en.wikipedia.org/wiki/PKCS_12][PKCS 12]] formatted certificate file that was generated by the above command
+can now be provided back to the requester, to be installed in their browser or operating
+system, enabling administrative access to cuirass.
+
 ** Initial SSL/TLS Certificate/s Generation
 
 In order for the ~nginx-service~ to run successfully, it needs SSL/TLS certificates, which
@@ -932,61 +911,82 @@ setup earlier when setting up [[*Certbot][Certbot]]), and will use the new Let's
 
 If the cuirass service is still in a failing state, it can now be restarted.
 
-** Setup Certificate Authority and Client Certificates for Cuirass Administration
-
-Setup of SSL/TLS client side certificates is beyond the scope of this article, however we
-will briefly mention and demonstrate how the [[https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git/tree/etc/new-client-cert.scm][etc/new-client-cert.scm]] script that is part of
-the Cuirass repository (but not in the provided cuirass guix package) can be adjusted to fit
-the needs of most Cuirass deployments.
+* Installation
 
-First fetch the script and make it executable.
+We've left out other aspects of defining our ~operating-system~ configuration, as its [[https://guix.gnu.org/manual/devel/en/html_node/operating_002dsystem-Reference.html][well
+documented]] by the Guix project, and varies depending on the specifics of your machine (for
+instance, file-systems, users/groups, initrd-modules, etc..). Once assembled, the
+~operating-system~ configuration can be placed in a file ~system.scm~, which defines a guix
+system configured with Cuirass, guix-publish, guix-daemon, and nginx, setup to act as a
+single-node build farm and substitute server! It can be trivially installed following the
+[[https://guix.gnu.org/manual/en/html_node/Proceeding-with-the-Installation.html][manual Guix System installation documentation]].
 
 #+begin_src shell :eval no
-  curl -O https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git/tree/etc/new-client-cert.scm
-  chmod +x new-client-cert.scm
+  guix system init system.scm /mnt
 #+end_src
 
-This script leverages ~guix~ itself to be run, so its necessary to be running on a system
-with guix installed in order to use this script. For more details on how this is done, see
-the note on the [[https://guix.gnu.org/manual/devel/en/html_node/Invoking-guix-shell.html][Invoking guix shell]] documentation about "guix shell can also be used as a
-script interpreter".
+Here ~/mnt~ is where the target root file-system is mounted after being prepared for
+installation. See our [[https://git.genenetwork.org/guix-north-america/tree/docs/initial-setup.org][Initial Setup Documentation]] for the specifics of preparing the disks
+for Guix installation in our case.
 
-The script currently needs to be slightly adjusted to alter the ~subject-template~ being
-used, which by default is ~"/C=DE/ST=Berlin/L=Berlin/O=GNU Guix/OU=Cuirass/CN=~a"~ - this
-string defines the openssl subject name used when generating a CA and client certificates,
-where ~~a~ will be substituted for a name later on. Here you may want to adjust the location,
-organization, etc.. to suite your case.
+** Remotely Bootstrapping Guix from Debian
 
-First a Certificate Authority needs to be generated. This should be done from the cuirass
-server itself so the CA key never leaves the server its being used on, and can be done with
-the ~new-client-cert.scm~ script as follows.
+In our case with the Tennessee Build Farm, physical access was inconvenient due to travel
+distance, so installation needed to be completed remotely. The target server already had
+Debian running on it, configured with serial access available out-of-band via [[https://en.wikipedia.org/wiki/Dell_DRAC][Dell iDRAC]] as
+well as ssh access to Debian. Another ssd was available for use, and was the target of our
+Guix installation.
+
+Guix can be [[https://guix.gnu.org/manual/en/html_node/Binary-Installation.html][installed on foreign distributions]], which is well documented, so its not covered
+here, but is the first step in bootstrapping Guix from Debian.
+
+*** Guix Configuration as a Channel
+
+Once Guix (the package manager) is installed on Debian, we need to partition our drives as
+required (which again varies, so will not be covered here). Next we need to make our
+~operating-system~ configuration available so we can complete bootstrapping Guix. The most
+straightforward way to do so is to just copy the ~system.scm~ file we defined earlier.
+Another way is to capture the configuration in a git repository, and [[https://guix.gnu.org/manual/en/html_node/Creating-a-Channel.html][make it a Guix channel]].
+This enables great shared tracking of system changes over time (outside of [[https://guix.gnu.org/manual/en/html_node/Invoking-guix-system.html][guix system
+list-generations ...]]), and is what was done while bootstrapping our installation.
+
+We choose to include a ~channels.scm~ file as part of the configuration channel that pins the
+versions of software that will be used with our deployment. So, in order to boot the server
+using an ~operating-system~ defined in [[https://git.genenetwork.org/guix-north-america/][our configuration channel]], we first download the
+~channels.scm~ file.
 
 #+begin_src shell :eval no
-  ./new-client-cert.scm --generate-ca
+  curl -O https://git.genenetwork.org/guix-north-america/plain/channels.scm
 #+end_src
 
-By default, this generates a CA key ~/etc/ssl-ca/private/ca.key~ and certificate
-~/etc/ssl-ca/certs/ca.crt~, so is important to ensure these directories already exist and are
-writable by the user running the script.
+We then create a temporary ~bootstrap.scm~ file that contains a references to the
+~operating-system~ we defined in our configuration channel.
+
+#+begin_src scheme
+  (@ (guix-na config balg02) balg02)
+#+end_src
+
+We then use ~guix time-machine~ to specify these channels when installing Guix onto the
+system.
 
 #+begin_src shell :eval no
-  mkdir -p /etc/ssl-ca/{private,cert}
+  guix time-machine -C channels.scm -- system init bootstrap.scm /mnt
 #+end_src
 
-With the CA in place, one or more client certificates can now be generated. First, clients
-will need to supply a Certificate Signing Request (CSR), which should be placed in the
-current working directory and named ~<who>.csr~ where ~<who>~ should be the name of the
-certificate signing request (eg. ~collin.csr~). We can then run the following to generate a
-signed client certificate, which will be outputted as ~<who>.p12~ in the current working
-directory.
+Subsequent updates to the system can be done without using the ~bootstrap.scm~ file. For
+instance, say the guix channel is updated in ~channels.scm~. To apply this change to the
+server, the new channels would need to be pulled, and the system reconfigured.
 
-#+begin_src shell
-  ./new-client-cert.scm collin
+#+begin_src shell :eval no
+  sudo -i guix pull -C <(curl https://git.genenetwork.org/guix-north-america/plain/channels.scm)
+  sudo -i guix system reconfigure -e '(@ (guix-na config balg02) balg02)'
 #+end_src
 
-The ~collin.p12~ [[https://en.wikipedia.org/wiki/PKCS_12][PKCS 12]] formatted certificate file that was generated by the above command
-can now be provided back to the requester, to be installed in their browser or operating
-system, enabling administrative access to cuirass.
+One caveat to using ~-e|--expression~ is that currently this expression is not stored along
+side the guix system generation, which makes it not possible to know which ~operating-system~
+configuration was used from a given channel (reported upstream as issue [[https://issues.guix.gnu.org/54631][#54631]]). To work
+around this for the time being, a file containing this expression can be used (just like was
+used for bootstrapping).
 
 * Challenges and Lessons Learned