guix-machines/README.org

#+TITLE: Guix Machines
#+AUTHOR: Collin J. Doering

#+BEGIN_EXPORT html
<p><a href="https://guix-ci.home.rekahsoft.ca/jobset/guix-machines"><img src="https://guix-ci.home.rekahsoft.ca/jobset/guix-machines/badge.svg?type=0" alt="Cuirass Status"></a></p>
#+END_EXPORT

#+begin_abstract
Guix configurations for all Guix powered systems privately managed by the author. This
includes all virtual machines for my home network, cloud/vps instances, as well as personal
computers. Due to the variety of types of systems managed via this repository, two mutable
deployment methodologies are supported:

1. A push based model, using ~guix deploy~[fn:1] to remotely deploy changes (useful for example
   from ci/cd).
2. A pull based model, using ~guix~ directly from the target, along with either the entire
   repository, or its channel file.

Immutable deployment is not yet supported, but is certainly possible given Guix's ability to
build an ~operating-system~ configuration into a image.
#+end_abstract

* Repository Structure

- ~channels*.scm~        :: [[*Guix Channel Files][Guix channel files]]
- ~deploy/~              :: Folder containing all ~guix deploy~ configurations
- ~.gitignore~           :: Files ignored by git
- ~.guix/~               :: Guix channel directory
- ~.guix-authorizations~ :: Guix authorizations file[fn:2]
- ~.guix-channel~        :: Guix channel file[fn:3]
- ~.pub-keys/~           :: Folder containing public key files used by Guix configurations
- ~README.org~           :: Org-mode[fn:4] documentation
- ~TODO.org~             :: Org-mode todo's, known issues and future aspirations
- ~unguix/~              :: Docker/docker-compose files used on deployed instances, managed
  outside of guix. Once better support for running docker/docker-compose via shepherd,
  specified declaratively via Guix configuration has been implemented, this directory and all
  files within it should be able to be removed.

** User Supplied Files Required for Push Based Deployment

- ~.deploy-key~ :: Private ssh key used to deploy changes to the target.

** Guix Channel Files

Guix channels[fn:5] allow for Guix to be customized and extended. They are also critical for
replicating a Guix system[fn:6]. As mentioned above, there are two primary classes of
deployments that are managed using this repository, push based and pull based. In both cases,
what specific versions of software that will be installed during deployment depends on the
guix channels in use. To ensure reproducibility, a ~channels.scm~ file is provided in this
repository that is expected to be used during deployment. It pins external guix channels to
specific versions.

If for some reason channels need to be pinned for a specific deployment, a new channel file
named ~channels-<hostname>.scm~ can be created and used in place of normally used channel
file.

*** TODO Updating guix channels used for deployment

**This doesn't work right unless your channels match what is expected by this repository.**

#+begin_src shell
  guix time-machine -- describe -f channels > channels.scm
#+end_src

** ~guix-machines~ the Guix Channel

This repository is itself a Guix channel, which allows operating-system configurations to
come directly from the channel, and the version of this configuration be managed just like
any other guix channel. It also facilitates CI, allowing for changes this channel be
evaluated by Cuirass at [[https://guix-ci.home.rekahsoft.ca]][fn:7]. This channel does not define
any packages, only system configurations and machine specifications for deployment.

At a later date, this also will allow for building of machine images for immutable
deployment, bootstrapping and more.

* Push Deployment with ~guix deploy~

Push based mutable deployment is the default deployment methodology for the majority of
systems managed by this repository. This is particularity safe because Guix changes are done
as transactions, and thus can easily be rolled back.

To deploy a system use the following (substituting ~<hostname>~ with the appropriate deploy
file).

#+begin_src shell
  guix time-machine -C channels.scm -- deploy deploy/<hostname>.scm
#+end_src

**Note:** Deploy files in [[./deploy]] are named after the hostname that would be used to ssh to
the machine.

* Pull Based Deployment

Pull based mutable deployment is the default deployment methodology for personal computers,
where using a push based method doesn't make sense. It also serves as a secondary deployment
mechanism for systems normally maintained using the push deployment model; for example, this
becomes necessary when facing ~guix deploy~ bugs.

First, fetch the most recent channel file from the target machine.

#+begin_src shell
  curl -O https://git.home.rekahsoft.ca/rekahsoft-public/guix-machines/raw/branch/master/channels.scm
#+end_src

Once the channel file is available on the target, update guix to use these channels.

#+begin_src shell
  sudo -i guix pull -C $(realpath channels.scm)
#+end_src

Once channels have been updated successfully, use the following to reconfigure the system.

#+begin_src shell
  sudo -i guix system reconfigure -e '(@ (rekahsoft guix-config <vms|manual> <target>) %system)'
#+end_src

Alternatively, the same effect can be achieved without first pulling the appropriate channels
by instead using ~guix time-machine~ as follows.

#+begin_src shell
  sudo -i guix time-machine -C $(realpath channels.scm) -- system reconfigure -e '(@ (rekahsoft guix-config <vms|manual> <target>) %system)'
#+end_src

* Using Local Sources

Regardless of the deployment methodology used, sometimes it is useful to deploy changes that
have not yet been committed. This should be done sparingly, as it can be slightly confusing
if forgotten; that being said, Guix makes this a semi-reasonable thing to do, as how the
system changes is tracked very explicitly by guix generations local to the target.

To manually deploy using local sources, the local sources must exist on the working machine
(of course). The easiest way to do this is via git, from the working machine like so.

#+begin_src shell
  git clone https://git.home.rekahsoft.ca/rekahsoft-public/guix-machines.git
#+end_src

Once a copy of the sources are available on the working machine, all that remains is
following the normal deployment steps, but with a slight modification; use the
~-l|--load-path~ argument to specify the current working sources, effectively overriding what
is in the ~guix-machines~ channel.

** Push Based Deployments

#+begin_src shell
  guix time-machine -C channels.scm -- deploy -L ./.guix deploy/<hostname>.scm
#+end_src

See the [[*Push Deployment with ~guix deploy~][Push Deployment with ~guix deploy~]] section for more details.

** Pull Based Deployments

#+begin_src shell
  sudo -i guix time-machine -C $(realpath channels.scm) -- system reconfigure -L $(realpath ./.guix) -e '(@ (rekahsoft guix-config <vms|manual> <target>) %system)'
#+end_src

See the [[*Pull Based Deployment][Pull Based Deployment]] section for more details.

* Footnotes

[fn:1] https://guix.gnu.org/manual/en/html_node/Invoking-guix-deploy.html

[fn:2] https://guix.gnu.org/manual/en/html_node/Channel-Authentication.html

[fn:3] https://guix.gnu.org/manual/en/html_node/Package-Modules-in-a-Sub_002ddirectory.html

[fn:4] https://orgmode.org/

[fn:5] https://guix.gnu.org/manual/en/html_node/Channels.html

[fn:6] https://guix.gnu.org/manual/en/html_node/Replicating-Guix.html

[fn:7] Only available in my internal home-network