2022-03-21 02:31:46 +00:00
|
|
|
#+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).
|
2022-03-22 22:39:06 +00:00
|
|
|
2. A pull based model, using ~guix~ directly from the target, along with either the entire
|
|
|
|
repository, or its channel file.
|
2022-03-21 02:31:46 +00:00
|
|
|
|
|
|
|
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
|
2022-03-22 22:39:06 +00:00
|
|
|
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.
|
2022-03-21 02:31:46 +00:00
|
|
|
|
|
|
|
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
|
2022-03-22 22:39:06 +00:00
|
|
|
guix time-machine -- describe -f channels > channels.scm
|
2022-03-21 02:31:46 +00:00
|
|
|
#+end_src
|
|
|
|
|
|
|
|
** ~guix-machines~ the Guix Channel
|
|
|
|
|
2022-03-22 22:39:06 +00:00
|
|
|
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.
|
2022-03-21 02:31:46 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2022-03-22 22:39:06 +00:00
|
|
|
To deploy a system use the following (substituting ~<hostname>~ with the appropriate deploy
|
|
|
|
file).
|
|
|
|
|
2022-03-21 02:31:46 +00:00
|
|
|
#+begin_src shell
|
2022-03-22 22:39:06 +00:00
|
|
|
guix time-machine -C channels.scm -- deploy deploy/<hostname>.scm
|
2022-03-21 02:31:46 +00:00
|
|
|
#+end_src
|
|
|
|
|
2022-03-22 22:39:06 +00:00
|
|
|
**Note:** Deploy files in [[./deploy]] are named after the hostname that would be used to ssh to
|
|
|
|
the machine.
|
|
|
|
|
2022-03-21 02:31:46 +00:00
|
|
|
* 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.
|
|
|
|
|
2022-03-22 22:39:06 +00:00
|
|
|
First, fetch the most recent channel file from the target machine.
|
2022-03-21 02:31:46 +00:00
|
|
|
|
|
|
|
#+begin_src shell
|
2022-03-22 22:39:06 +00:00
|
|
|
curl -O https://git.home.rekahsoft.ca/rekahsoft-public/guix-machines/raw/branch/master/channels.scm
|
2022-03-21 02:31:46 +00:00
|
|
|
#+end_src
|
|
|
|
|
2022-03-22 22:39:06 +00:00
|
|
|
Once the channel file is available on the target, update guix to use these channels.
|
2022-03-21 02:31:46 +00:00
|
|
|
|
|
|
|
#+begin_src shell
|
2022-03-22 22:39:06 +00:00
|
|
|
sudo -i guix pull -C $(realpath channels.scm)
|
2022-03-21 02:31:46 +00:00
|
|
|
#+end_src
|
|
|
|
|
|
|
|
Once channels have been updated successfully, use the following to reconfigure the system.
|
|
|
|
|
|
|
|
#+begin_src shell
|
2022-03-22 23:04:39 +00:00
|
|
|
sudo -i guix system reconfigure -e '(@ (rekahsoft guix-config <vms|manual> <target>) %system)'
|
2022-03-21 02:31:46 +00:00
|
|
|
#+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
|
2022-03-22 23:04:39 +00:00
|
|
|
sudo -i guix time-machine -C $(realpath channels.scm) -- system reconfigure -e '(@ (rekahsoft guix-config <vms|manual> <target>) %system)'
|
2022-03-22 22:39:06 +00:00
|
|
|
#+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
|
2022-03-21 02:31:46 +00:00
|
|
|
#+end_src
|
|
|
|
|
2022-03-22 22:39:06 +00:00
|
|
|
See the [[*Push Deployment with ~guix deploy~][Push Deployment with ~guix deploy~]] section for more details.
|
|
|
|
|
|
|
|
** Pull Based Deployments
|
|
|
|
|
|
|
|
#+begin_src shell
|
2022-03-22 23:04:39 +00:00
|
|
|
sudo -i guix time-machine -C $(realpath channels.scm) -- system reconfigure -L $(realpath ./.guix) -e '(@ (rekahsoft guix-config <vms|manual> <target>) %system)'
|
2022-03-22 22:39:06 +00:00
|
|
|
#+end_src
|
|
|
|
|
|
|
|
See the [[*Pull Based Deployment][Pull Based Deployment]] section for more details.
|
|
|
|
|
2022-03-21 02:31:46 +00:00
|
|
|
* 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
|
2022-03-22 22:39:06 +00:00
|
|
|
|
|
|
|
[fn:7] Only available in my internal home-network
|