Added first pass at guix installation for linode.

1 files changed, 178 insertions, 123 deletions

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index b04ca538abd..c75e6b0e153 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -2877,68 +2877,123 @@ Copy into it the output of:
 cat ~/.ssh/<username>_rsa.pub
 @end example
 
-Power the Linode down.
+Power the Linode down. We will install Guix as follows.
 
-In the Linode's Storage tab, resize the Debian disk to be smaller.
-30 GB free space is recommended.  Then click "Add a disk", and fill
-out the form with the following:
+@enumerate
+@item
+Add a new virtual disk device to store a bootable Guix image.
 
-@itemize @bullet
 @item
-Label: "Guix"
+Install Guix as ``foreign distro'' using the default Debian operating
+system.
 
 @item
-Filesystem: ext4
+Use the foreign distro to create a bootable version of Guix in the disk
+created for the bootable Guix image.
 
 @item
-Set it to the remaining size
-@end itemize
+Configure the Linode to boot from our bootable Guix image instead of the
+default Debian.
 
-In the Configurations tab, press "Edit" on the default Debian profile.
-Under "Block Device Assignment" click "Add a Device". It should be
-@file{/dev/sdc} and you can select the "Guix" disk. Save Changes.
+@item
+Remove the default Debian disk, and save the Guix Linode as an image
+which can be used to other linodes with Guix.
+@end enumerate
+
+In this example, we will assume that the default Debian image looks
+something like the following:
 
-Now "Add a Configuration", with the following:
 @itemize @bullet
 @item
-Label: Guix
+Kernel: ``GRUB2''
 
 @item
-Kernel:GRUB 2 (it's at the bottom!  This step is @b{IMPORTANT!})
+@file{/dev/sda}: Some bootable Debian image (probably Ubuntu)
 
 @item
-Block device assignment:
+@file{/dev/sdb}: Swap Image
 
 @item
-@file{/dev/sda}: Guix
+Root Device: @file{/dev/sda}
+@end itemize
+
+We will create a bootable disk in @file{/dev/sdc}. If your machine
+configuration is slightly different, all the steps will be roughly the
+same, except you will have to replace the device file of your bootable
+disk from @file{/dev/sdc} to some other identifier.
+
+Let's begin my adding a new device to store a bootable Guix
+image. Navigate to the ``Storage'' tab.  We are going to create a disk
+with the ext4 filesystem that will hold a bootable Guix system. Resize
+the Debian disk to be 8GB smaller. Then click ``Add A Disk'', and fill
+out the form with the following:
 
+@itemize @bullet
 @item
-@file{/dev/sdb}: swap
+Label: "Guix"
 
 @item
-Root device: @file{/dev/sda}
+Filesystem: ``ext4'
 
 @item
-Turn off all the filesystem/boot helpers
+Size: Set it to the remaining size (approximately 8GB)
 @end itemize
 
-Now power it back up, booting with the Debian configuration.  Once it's
-running, ssh to your server via @code{ssh
-root@@@var{<your-server-IP-here>}}. (You can find your server IP address in
-your Linode Summary section.) Now you can run the "install guix from
-@pxref{Binary Installation,,, guix, GNU Guix}" steps:
+This device is not in the configuration for your machine yet. It is not
+a part of your Linode virtual machine until you add the disk to the
+default Debian configuration.
+
+Navigate to the ``Configurations'' tab.  Enter the ``Edit'' menu for the
+default Debian profile.
+Under "Block Device Assignment" click "Add a Device". It should be
+@file{/dev/sdc} and you can select the "Guix" disk. Save Changes.
+
+Now we want to restart our virtual machine to spin up our new virtual
+disk. Reboot the linode and log back in.
+
+We are now ready to install Guix as a foreign distro. Follow the
+instructions in @pxref{Binary Installation,,, guix, GNU Guix}.
+
+We paraphrase the instructions here. Note that you will likely have to
+install ``uidmap'' and ``nscd''. This may involve updating the default
+package manager in your default Debian distro.
 
 @example
-sudo apt-get install gpg
-wget https://sv.gnu.org/people/viewgpg.php?user_id=15145 -qO - | gpg --import -
 wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
 chmod +x guix-install.sh
 ./guix-install.sh
 guix pull
 @end example
 
-Now it's time to write out a config for the server.  The key information
-is below. Save the resulting file as @file{guix-config.scm}.
+If you run into errors, consult the linked documentation. In the
+installation script, we selected the following options.
+
+@itemize
+@item
+``Yes'' to using an App Armor profile. Selecting ``No'' failed at the
+@code{guix pull} step.
+@item
+``No'' to automatically discovering substitute servers on the local
+network
+@item
+``Yes'' to permit pre-built package binaries from the build farm
+@item
+``No'' to customize user's bash shell to Guix.
+@end itemize
+
+We are now ready to create a bootable image in our new disk. First,
+create a Guix directory mounted on this new disk, which we assume here
+is @file{/dev/sdc}.
+
+@example
+mkdir /mnt/guix
+mount /dev/sdc /mnt/guix
+@end example
+
+We take a moment to create a system definition before calling @code{guix
+system init} to initialize the guix installation. We only allow for a
+root user without any default SSH keys. This is so that the default
+image we may create later will not have any default users or SSH keys.
 
 @lisp
 (use-modules (gnu)
@@ -2950,9 +3005,11 @@ is below. Save the resulting file as @file{guix-config.scm}.
                      ssh
                      tls)
 
+;; if you want to add new packages, services and users later, you can
+;; use "guix deploy"
 (operating-system
-  (host-name "my-server")
-  (timezone "America/New_York")
+  (host-name "localhost")
+  (timezone "UTC")
   (locale "en_US.UTF-8")
   ;; This goofy code will generate the grub.cfg
   ;; without installing the grub bootloader on disk.
@@ -2961,6 +3018,9 @@ is below. Save the resulting file as @file{guix-config.scm}.
                 (bootloader
                  (inherit grub-bootloader)
                  (installer #~(const #true))))))
+
+  ;; we configure our bootable guix system to be on device "/dev/sda"
+  ;; if you want to use a different device, change it here
   (file-systems (cons (file-system
                         (device "/dev/sda")
                         (mount-point "/")
@@ -2968,134 +3028,129 @@ is below. Save the resulting file as @file{guix-config.scm}.
                       %base-file-systems))
 
 
+  ;; our swap is assumed to be /dev/sdb.
+  ;; if your vm will have a different swap device, change it here
   (swap-devices (list "/dev/sdb"))
 
-
   (initrd-modules (cons "virtio_scsi"    ; Needed to find the disk
                         %base-initrd-modules))
 
-  (users (cons (user-account
-                (name "janedoe")
-                (group "users")
-                ;; Adding the account to the "wheel" group
-                ;; makes it a sudoer.
-                (supplementary-groups '("wheel"))
-                (home-directory "/home/janedoe"))
-               %base-user-accounts))
-
   (packages (cons* openssh-sans-x
                    %base-packages))
 
+  ;; you will have to add add your ssh keys with lish or linode's
+  ;; ssh tool later
   (services (cons*
              (service dhcp-client-service-type)
              (service openssh-service-type
                       (openssh-configuration
                        (openssh openssh-sans-x)
-                       (password-authentication? #false)
-                       (authorized-keys
-                        `(("janedoe" ,(local-file "janedoe_rsa.pub"))
-                          ("root" ,(local-file "janedoe_rsa.pub"))))))
+                       (password-authentication? #false)))
              %base-services)))
 @end lisp
 
-Replace the following fields in the above configuration:
-@lisp
-(host-name "my-server")       ; replace with your server name
-; if you chose a linode server outside the U.S., then
-; use tzselect to find a correct timezone string
-(timezone "America/New_York") ; if needed replace timezone
-(name "janedoe")              ; replace with your username
-("janedoe" ,(local-file "janedoe_rsa.pub")) ; replace with your ssh key
-("root" ,(local-file "janedoe_rsa.pub")) ; replace with your ssh key
-@end lisp
-
-The last line in the above example lets you log into the server as root
-and set the initial root password (see the note at the end of this
-recipe about root login).  After you have done this, you may
-delete that line from your configuration and reconfigure to prevent root
-login.
-
-Copy your ssh public key (eg: @file{~/.ssh/id_rsa.pub}) as
-@file{@var{<your-username-here>}_rsa.pub} and put
-@file{guix-config.scm} in the same directory.  In a new terminal run
-these commands.
+Copy this to your linode in whatever directory you choose. In this
+example, we choose to call the file @file{linode-guix.scm} and save it
+to @file{/tmp/linode-guix.scm}. Now we install a guix system
+realizing this config to /mnt/guix.
 
 @example
-sftp root@@<remote server ip address>
-put /path/to/files/<username>_rsa.pub .
-put /path/to/files/guix-config.scm .
+guix system init guix-config.scm /mnt/guix
 @end example
 
-In your first terminal, mount the guix drive:
+@c TODO: check grub files are installed by above config
 
-@example
-mkdir /mnt/guix
-mount /dev/sdc /mnt/guix
-@end example
+@c Due to the way we set up the bootloader section of the guix-config.scm,
+@c only the grub configuration file will be installed.  So, we need to copy
+@c over some of the other GRUB stuff already installed on the Debian system:
 
-Due to the way we set up the bootloader section of the guix-config.scm,
-only the grub configuration file will be installed.  So, we need to copy
-over some of the other GRUB stuff already installed on the Debian system:
+@c @example
+@c mkdir -p /mnt/guix/boot/grub
+@c cp -r /boot/grub/* /mnt/guix/boot/grub/
+@c @end example
 
-@example
-mkdir -p /mnt/guix/boot/grub
-cp -r /boot/grub/* /mnt/guix/boot/grub/
-@end example
+@c Now initialize the Guix installation:
 
-Now initialize the Guix installation:
+@c @example
+@c guix system init guix-config.scm /mnt/guix
+@c @end example
 
-@example
-guix system init guix-config.scm /mnt/guix
-@end example
+Now that our Guix disk is fully populated, we are ready to power down
+the linode and configure a new virtual machine which boots from the Guix
+disk.
 
-Ok, power it down!
-Now from the Linode console, select boot and select "Guix".
+Navigate to the ``Configurations'' tab and click "Add a
+Configuration". Fill out the new configuration with the following
+information.
 
-Once it boots, you should be able to log in via SSH!  (The server config
-will have changed though.)  You may encounter an error like:
+@itemize @bullet
+@item
+Label: Guix
 
-@example
-$ ssh root@@<server ip address>
-@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
-@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
-Someone could be eavesdropping on you right now (man-in-the-middle attack)!
-It is also possible that a host key has just been changed.
-The fingerprint for the ECDSA key sent by the remote host is
-SHA256:0B+wp33w57AnKQuHCvQP0+ZdKaqYrI/kyU7CfVbS7R4.
-Please contact your system administrator.
-Add correct host key in /home/joshua/.ssh/known_hosts to get rid of this message.
-Offending ECDSA key in /home/joshua/.ssh/known_hosts:3
-ECDSA host key for 198.58.98.76 has changed and you have requested strict checking.
-Host key verification failed.
-@end example
+@item
+Kernel:GRUB 2 (it's at the bottom!  This step is @b{IMPORTANT!})
+
+@item
+Block device assignment:
+
+@item
+@file{/dev/sda}: Guix (was @file{dev/sdc} in the default configuration)
+
+@item
+@file{/dev/sdb}: swap
 
-Either delete @file{~/.ssh/known_hosts} file, or delete the offending line
-starting with your server IP address.
+@item
+Root device: @file{/dev/sda}
 
-Be sure to set your password and root's password.
+@item
+Turn off all the filesystem/boot helpers
+@end itemize
+
+We are now ready to boot the Guix operating system.  First, power down
+the linode. Then boot from your Guix configuration.
+
+We cannot yet login over SSH because our configured system did not
+specify authorized keys. This is intentional, as we do not want our
+default system to have fixed SSH keys. Chances are we will build a
+linode image containing this default system, and we don't want to mix
+the system with the credentials.
+
+If you want to save an image of your Linode, now is the time to do
+it. Navigate to ``Images'', then ``Create Image'' and select your
+current compute instance.
+
+To add the SSH keys for normal login we use the ``LISH'' console. Append
+your public SSH keys to login to ``/root/.ssh/authorized_keys'' as
+usual. Now you are able to login with root over SSH as usual.
+ 
+The Guix installation will have generated new configs for the SSH server
+and you will encounter a scary man-in-the-middle warning if the server
+was alread a known host.
+
+Either delete @file{~/.ssh/known_hosts} file, or delete the offending
+line starting with your server IP address. Check the host fingerprint to
+be safe.
+
+Set the root password if you would like to.
 
 @example
 ssh root@@<remote ip address>
-passwd  ; for the root password
-passwd <username> ; for the user password
+passwd  # for the root password
 @end example
 
-You may not be able to run the above commands at this point.  If you
-have issues remotely logging into your linode box via SSH, then you may
-still need to set your root and user password initially by clicking on
-the ``Launch Console'' option in your linode.  Choose the ``Glish''
-instead of ``Weblish''.  Now you should be able to ssh into the machine.
-
-Hooray!  At this point you can shut down the server, delete the
-Debian disk, and resize the Guix to the rest of the size.
-Congratulations!
+Here are some other approaches that may work as well.
+@itemize
+@item
+Build a raw image for the linode using the @code{guix system image}
+command and a suitable image config. We simply could not get this to
+work with the configurations we tried. Linode expects a bootable raw
+``.img'' file in the ext4 file format, but maybe other things as well.
+@item
+Follow the instructions for uploading a custom distro in Linode from a
+bootable ISO 9660 image. This creates a raw image which is not
+resizeable.
+@end itemize
 
-By the way, if you save it as a disk image right at this point, you'll
-have an easy time spinning up new Guix images!  You may need to
-down-size the Guix image to 6144MB, to save it as an image.  Then you
-can resize it again to the max size.
 
 @node Running Guix on a Kimsufi Server
 @section Running Guix on a Kimsufi Server