146 lines
6.6 KiB
Org Mode
146 lines
6.6 KiB
Org Mode
#+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
|