#+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~ along with this repository directly from the target
   machine.

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~ :: Folder expected to contain two files (a public and private ssh key, named
  ~key.pub~ and ~key~ respectively).

** 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, ~channel*.scm~ files are provided in this
repository that are expected to be used during deployment. However, multiple channel files
are provided as it makes sense to lock software versions across different sets of machines in
varying ways. For example, there is value in using the same channel file (and thus, same
software versions) across all virtual machines running on my home hypervisor cluster, but
there is no reason to explicitly lock my personal machines to the same software versions.
Further, cases could arise where my personal computer configuration/s or server
configuration/s need to be pinned to a specific set of software versions, and thus require a
individual channel file.

Though supporting a channel file per machine is possible, it would cause additional
maintenance overhead. So instead, two channel files are provided, that correspond to the two
classes of machines that are managed.

- ~channels-vms.scm~ :: Channel file used for push based deployments to vm's running on my
  home hypervisor cluster
- ~channels.scm :: Channel file used for pull based deployments of personal computers

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-vms.scm
#+end_src

** ~guix-machines~ the Guix Channel

This repository is itself a Guix channel, which facilitates CI, allowing for changes to it to
be evaluated by Cuirass at [[https://guix-ci.home.rekahsoft.ca]] (only available in my internal
home-network). This channel is not intended to be used directly from guix systems as it
doesn't provide any packages.

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.

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

* 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.

To manually deploy from the target, first the contents of this repository must be transferred
to the target machine. The easiest way to do this is via git, from the target like so.

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

Once this repository is on the target, pull the [[*Guix Channel Files][appropriate channels]] as root.

#+begin_src shell
  sudo -i guix pull -C $(realpath channels-<vms|manual>.scm)
#+end_src

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

#+begin_src shell
  sudo -i guix system reconfigure -L $(realpath .guix) -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-<vms|manual>.scm) -- system reconfigure -L $(realpath .guix) -e '(@ (rekahsoft guix-config <vms|manual> <target>) system)'
#+end_src

* 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