Guix Machines

• Repository Structure
  • User Supplied Files Required for Push Based Deployment
  • Guix Channel Files
    • Updating guix channels used for deployment
  • guix-machines the Guix Channel
• Push Deployment with guix deploy
• Pull Based Deployment
• Using Local Sources
  • Building Operating System Configuration
  • Running Operating System in VM for testing
  • Generating the OS service extension graph
  • Generating the shepherd service graph
  • Push Based Deployments
  • Pull Based Deployments
• Footnotes

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

Repository Structure

channels*.scm

Guix channel files

deploy/

Folder containing all guix deploy configurations

.gitignore

Files ignored by git

.guix/

Guix channel directory

.guix-authorizations

Guix authorizations file²

.guix-channel

Guix channel file³

.pub-keys/

Folder containing public key files used by Guix configurations

README.org

Org-mode⁴ 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⁵ allow for Guix to be customized and extended. They are also critical for replicating a Guix system⁶. 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.

  guix time-machine -- describe -f channels > channels.scm

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⁷. 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).

  guix time-machine -C channels.scm -- deploy deploy/<hostname>.scm

Note: Deploy files in /rekahsoft/guix-machines/src/commit/462ab6ac3d4ad41ea326718c0c3a5cacb2657636/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.

  curl -O https://git.home.rekahsoft.ca/rekahsoft-public/guix-machines/raw/branch/master/channels.scm

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

  sudo -i guix pull -C $(realpath channels.scm)

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

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

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

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

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.

  git clone https://git.home.rekahsoft.ca/rekahsoft-public/guix-machines.git

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.

Building Operating System Configuration

Many times its useful to verify that a change to a system configuration will build correctly, prior to deploying it. guix system build is meant for exactly this, and can be run as follows.

  guix time-machine -C channels.scm -- system build -L .guix -e '(@ (rekahsoft guix-config <vms|manual> <target>) %system)'

Running Operating System in VM for testing

  $(guix time-machine -C channels.scm -- system vm -e '(@ (rekahsoft guix-config <vms|manual> <target>) %system)') -m 2G -smp 2 -nic user,model=virtio-net-pci

Generating the OS service extension graph

  guix time-machine -C channels.scm -- system extension-graph -e '(@ (rekahsoft guix-config <vms|manual> <target>) %system)' | guix shell xdot -- xdot -

Generating the shepherd service graph

  guix time-machine -C channels.scm -- system shepherd-graph -e '(@ (rekahsoft guix-config <vms|manual> <target>) %system)' | guix shell xdot -- xdot -

Push Based Deployments

  guix time-machine -C channels.scm -- deploy -L ./.guix deploy/<hostname>.scm

See the Push Deployment with guix deploy section for more details.

Pull Based Deployments

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

See the Pull Based Deployment section for more details.

Footnotes

---

¹

https://guix.gnu.org/manual/en/html_node/Invoking-guix-deploy.html

²

https://guix.gnu.org/manual/en/html_node/Channel-Authentication.html

³

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

⁴

https://orgmode.org/

⁵

https://guix.gnu.org/manual/en/html_node/Channels.html

⁶

https://guix.gnu.org/manual/en/html_node/Replicating-Guix.html

⁷

Only available in my internal home-network