Invoking guix deploy (GNU Guix Reference Manual)

We’ve already seen operating-system declarations used to manage a machine’s configuration locally. Suppose you need to configure multiple machines, though—perhaps you’re managing a service on the web that’s comprised of several servers. guix deploy enables you to use those same operating-system declarations to manage multiple remote hosts at once as a logical “deployment”.

Such an invocation will deploy the machines that the code within file evaluates to. As an example, file might contain a definition like this:

;; This is a Guix deployment of a "bare bones" setup, with
;; no X11 display server, to a machine with an SSH daemon
;; listening on localhost:2222. A configuration such as this
;; may be appropriate for virtual machine with ports
;; forwarded to the host's loopback interface.

(use-service-modules networking ssh)
(use-package-modules bootloaders)

(define %system
  (operating-system
   (host-name "gnu-deployed")
   (timezone "Etc/UTC")
   (bootloader (bootloader-configuration
                (bootloader grub-bootloader)
                (targets '("/dev/vda"))
                (terminal-outputs '(console))))
   (file-systems (cons (file-system
                        (mount-point "/")
                        (device "/dev/vda1")
                        (type "ext4"))
                       %base-file-systems))
   (services
    (append (list (service dhcp-client-service-type)
                  (service openssh-service-type
                           (openssh-configuration
                            (permit-root-login #t)
                            (allow-empty-passwords? #t))))
            %base-services))))

(list (machine
       (operating-system %system)
       (environment managed-host-environment-type)
       (configuration (machine-ssh-configuration
                       (host-name "localhost")
                       (system "x86_64-linux")
                       (user "alice")
                       (identity "./id_rsa")
                       (port 2222)))))

The file should evaluate to a list of machine objects. This example, upon being deployed, will create a new generation on the remote system realizing the operating-system declaration %system. environment and configuration specify how the machine should be provisioned—that is, how the computing resources should be created and managed. The above example does not create any resources, as a 'managed-host is a machine that is already running the Guix system and available over the network. This is a particularly simple case; a more complex deployment may involve, for example, starting virtual machines through a Virtual Private Server (VPS) provider. In such a case, a different environment type would be used.

Do note that you first need to generate a key pair on the coordinator machine to allow the daemon to export signed archives of files from the store (see Invoking guix archive), though this step is automatic on Guix System:

Each target machine must authorize the key of the master machine so that it accepts store items it receives from the coordinator:

user, in this example, specifies the name of the user account to log in as to perform the deployment. Its default value is root, but root login over SSH may be forbidden in some cases. To work around this, guix deploy can log in as an unprivileged user and employ sudo to escalate privileges. This will only work if sudo is currently installed on the remote and can be invoked non-interactively as user. That is, the line in sudoers granting user the ability to use sudo must contain the NOPASSWD tag. This can be accomplished with the following operating system configuration snippet:

(use-modules ...
             (gnu system))               ;for %sudoers-specification

(define %user "username")

(operating-system
  ...
  (sudoers-file
     (plain-file "sudoers"
                 (string-append (plain-file-content %sudoers-specification)
                                (format #f "~a ALL = NOPASSWD: ALL~%"
                                        %user)))))

For more information regarding the format of the sudoers file, consult man sudoers.

Once you’ve deployed a system on a set of machines, you may find it useful to run a command on all of them. The --execute or -x option lets you do that; the example below runs uname -a on all the machines listed in the deployment file:

One thing you may often need to do after deployment is restart specific services on all the machines, which you can do like so:

The guix deploy -x command returns zero if and only if the command succeeded on all the machines.

10.16 Invoking guix deploy

10.16 Invoking `guix deploy`