Updated working version of linode docs.

1 files changed, 70 insertions, 113 deletions

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index deb6c388471..4256957d3cf 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -2862,25 +2862,13 @@ before you execute slock.
 
 To run Guix on a server hosted by @uref{https://www.linode.com, Linode},
 start with a recommended Debian server.  We recommend using the default
-distro as a way to bootstrap Guix. Create your SSH keys.
-
-@example
-ssh-keygen
-@end example
-
-Be sure to add your SSH key for easy login to the remote server.
-This is trivially done via Linode's graphical interface for adding
-SSH keys.  Go to your profile and click add SSH Key.
-Copy into it the output of:
-
-@example
-cat ~/.ssh/<username>_rsa.pub
-@end example
-
-Power the Linode down. We will install Guix as follows.
+distro as a way to bootstrap Guix. The steps are outlined below.
 
 @enumerate
 @item
+Create a default Debian server.
+
+@item
 Add a new virtual disk device to store a bootable Guix image.
 
 @item
@@ -2896,10 +2884,29 @@ Configure the Linode to boot from our bootable Guix image instead of the
 default Debian.
 
 @item
-Remove the default Debian disk, and save the Guix Linode as an image
-which can be used to other linodes with Guix.
+Save the bootable Guix disk as an image.
+
+@item
+Boot from the Guix disk.
+
+@item
+[Optional] Use @code{guix deploy} to update your machine configuration.
 @end enumerate
 
+@subsection Creating a Default Debian Server
+
+Simply navigate to the ``Linodes'' page and press the ``Create Linode''
+command. Pick the recommended OS, which is likely Ubuntu.
+
+We recommend you create a pair of SSH keys if you haven't already for
+passwordless logins to this machine. These keys will also be useful for
+logging into the machine when it is running Guix.
+
+Try logging in and making sure the server works. Then power the Linode
+down.
+
+@subsection Creating a Disk to Boot Guix
+
 In this example, we will assume that the default Debian image looks
 something like the following:
 
@@ -2951,6 +2958,8 @@ Under "Block Device Assignment" click "Add a Device". It should be
 Now we want to restart our virtual machine to spin up our new virtual
 disk. Reboot the linode and log back in.
 
+@subsection Installing Guix as a Foreign Distro
+
 We are now ready to install Guix as a foreign distro. Follow the
 instructions in @pxref{Binary Installation,,, guix, GNU Guix}.
 
@@ -2978,12 +2987,19 @@ network
 @item
 ``Yes'' to permit pre-built package binaries from the build farm
 @item
-``No'' to customize user's bash shell to Guix.
+``Yes'' 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}.
+This process can take a bit. If you would like to save an image of
+this state to reboot from, navigate to ``Images'' and save a snapshot of
+the host.
+
+@subsection Creating a Bootable Guix
+
+We are now ready to create a bootable image in our new disk. To edit and
+resize disks, we need to shut down the Linode first. Then, create a Guix
+directory mounted on this new disk, which we assume here is
+@file{/dev/sdc}.
 
 @example
 mkdir /mnt/guix
@@ -2991,89 +3007,26 @@ 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.
+system init} to initialize the guix installation. Replace the authorized
+keys with the path to your keys.
 
 @lisp
-(use-modules (gnu)
-             (guix modules))
-(use-service-modules networking
-                     ssh)
-(use-package-modules admin
-                     package-management
-                     ssh
-                     tls)
-
-;; if you want to add new packages, services and users later, you can
-;; use "guix deploy"
-(operating-system
-  (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.
-  (bootloader (bootloader-configuration
-               (bootloader
-                (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 "/")
-                        (type "ext4"))
-                      %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))
-
-  (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)
-                       ;; adding authorized keys is optional
-                       ))
-             %base-services)))
+@include examples/cloud-guix.scm
 @end lisp
 
 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}.
-
-Due to the way we set up the bootloader section of the
-@file{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 maybe this would benefit from a derivation?
-@c ideally all of this goes away...
-@c the best way to do this would be to simply upload an image...
-@example
-cp -r /boot/grub/* /mnt/guix/boot/grub/ # extra grub files
-@end example
+example, we choose to call the file @file{cloud-guix.scm} and save it
+to @file{/tmp/cloud-guix.scm}.
 
 Now we are ready to install a guix system realizing this config to
 @file{/mnt/guix}.
 
 @example
-guix system init /tmp/linode-guix.scm /mnt/guix
+guix system init /tmp/cloud-guix.scm /mnt/guix
 @end example
 
+@subsection Configure Linode to Boot from Guix Image
+
 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.
@@ -3105,38 +3058,42 @@ Root device: @file{/dev/sda}
 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 are now ready to boot the Guix operating system.
+
+@subsection Saving the Bootable Image
+
+This step is optional, but helps save time when starting new guix
+machines. First, power down the Linode
 
 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.
 
-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.
+@subsection Booting Guix
 
-To add the SSH keys for normal login we use the ``LISH'' console. If
-that is buggy, reboot with the default Debian and place the authorized
-keys you want in @file{/root/.ssh/authorized_keys}. Now you are able to
-login with root over SSH as usual.
+Navigate to the ``Configurations'' tab, and select the ``boot'' option
+on your Guix configuration.
  
 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.
+was already 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.
+Update or remove the entry in the known hosts file to ignore this
+error. Check the host fingerprint to verify that there is not in fact a
+man in the middle attack being perpetrated.
 
-Set the root password if you would like to.
+If you would like, you can now delete your default Debian configuration.
 
-@example
-ssh root@@<remote ip address>
-passwd  # for the root password
-@end example
+@subsection (Optional) Updating with Guix Deploy
+
+To deploy a new configuration, follow the instructions in
+@pxref{Invoking guix deploy,,, guix, GNU Guix}.
+
+Note that your coordinator machine will have to generate a public key,
+which will be stored in @file{/etc/guix}. Copy that over to the target
+machine and authorize it before running the deployment.
+
+@subsection Notes
 
 Here are some other approaches that may work as well.
 @itemize