[bug#36404,v4,4/4] doc: Add section for 'guix deploy'.

* doc/guix.texi: Add section "Invoking guix deploy".
---
 doc/guix.texi | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

Jakob L. Kreuze writes:

> * doc/guix.texi: Add section "Invoking guix deploy".
> ---
>  doc/guix.texi | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 107 insertions(+)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 9dc1d2a9c..0827a2bde 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -81,6 +81,7 @@ Documentation License''.
>  * guix gc: (guix)Invoking guix gc.            Reclaiming unused disk space.
>  * guix pull: (guix)Invoking guix pull.        Update the list of available packages.
>  * guix system: (guix)Invoking guix system.    Manage the operating system configuration.
> +* guix deploy: (guix)Invoking guix deploy.    Manage operating system configurations for remote hosts.
>  @end direntry
>  
>  @dircategory Software development
> @@ -269,6 +270,7 @@ System Configuration
>  * Initial RAM Disk::            Linux-Libre bootstrapping.
>  * Bootloader Configuration::    Configuring the boot loader.
>  * Invoking guix system::        Instantiating a system configuration.
> +* Invoking guix deploy::        Deploying a system configuration to a remote host.
>  * Running Guix in a VM::        How to run Guix System in a virtual machine.
>  * Defining Services::           Adding new service definitions.
>  
> @@ -10302,6 +10304,7 @@ instance to support new system services.
>  * Initial RAM Disk::            Linux-Libre bootstrapping.
>  * Bootloader Configuration::    Configuring the boot loader.
>  * Invoking guix system::        Instantiating a system configuration.
> +* Invoking guix deploy::        Deploying a system configuration to a remote host.
>  * Running Guix in a VM::        How to run Guix System in a virtual machine.
>  * Defining Services::           Adding new service definitions.
>  @end menu
> @@ -25335,6 +25338,110 @@ example graph.
>  
>  @end table
>  
> +@node Invoking guix deploy
> +@section Invoking @code{guix deploy}
> +
> +We've already seen @code{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.  @command{guix deploy} enables you to use those
> +same @code{operating-system} declarations to manage multiple remote hosts at
> +once as a logical ``deployment''.
> +
> +@example
> +guix deploy @var{file}
> +@end example
> +
> +Such an invocation will deploy the machines that the code within @var{file}
> +evaluates to.  As an example, @var{file} might contain a definition like this:
> +
> +@example
> +;; 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)
> +                (target "/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
> +       (system %system)
> +       (environment managed-host-environment-type)
> +       (configuration (machine-ssh-configuration
> +                       (host-name "localhost")
> +                       (identity "./id_rsa")
> +                       (port 2222)))))
> +@end example
> +
> +The file should evaluate to a list of @var{machine} objects.  This example,
> +upon being deployed, will create a new generation on the remote system
> +realizing the @code{operating-system} declaration @var{%system}.
> +@var{environment} and @var{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
> +@code{'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 VPS provider.  In such a case, a different @var{environment} type would be
> +used.
> +
> +@deftp {Data Type} machine
> +This is the data type representing a single machine in a heterogeneous Guix
> +deployment.
> +
> +@table @asis
> +@item @code{system}
> +The object of the operating system configuration to deploy.
> +
> +@item @code{environment}
> +An @code{environment-type} describing how the machine should be provisioned.
> +At the moment, the only supported value is
> +@code{managed-host-environment-type}.
> +
> +@item @code{configuration} (default: @code{#f})
> +An object describing the configuration for the machine's @code{environment}.
> +If the @code{environment} has a default configuration, @code{#f} maybe used.
> +If @code{#f} is used for an environment with no default configuration,
> +however, an error will be thrown.
> +@end table
> +@end deftp
> +
> +@deftp {Data Type} machine-ssh-configuration
> +This is the data type representing the SSH client parameters for a machine
> +with an @code{environment} of @code{managed-host-environment-type}.
> +
> +@table @asis
> +@item @code{host-name}
> +@item @code{port} (default: @code{22})
> +@item @code{user} (default: @code{"root"})
> +@item @code{identity} (default: @code{#f})
> +If specified, the path to the SSH private key to use to authenticate with the
> +remote host.
> +@end table
> +@end deftp
> +
>  @node Running Guix in a VM
>  @section Running Guix in a Virtual Machine

All looks good to me.

From my perspective, this is ready to merge.  Which means that we need
to merge Ludo's remote-eval too.

Of course others may catch things, but I'd say let's not take too
long... we should get this in and let people start playing with it. :)

Hi,

Christopher Lemmer Webber <cwebber@dustycloud.org> skribis:

> From my perspective, this is ready to merge.  Which means that we need
> to merge Ludo's remote-eval too.

Yes, sorry for the delay on this.  I started wondering about details of
the ‘lower-gexp’ API; I’ll try to get to it today…

Thanks,
Ludo’.

On Tue, Jul 2, 2019 at 1:58 PM Jakob L. Kreuze
<zerodaysfordays@sdf.lonestar.org> wrote:
>
> * doc/guix.texi: Add section "Invoking guix deploy".

Looks good to me.  Congratulations in advance for getting 'guix
deploy' to master!

- Dave

zerodaysfordays@sdf.lonestar.org (Jakob L. Kreuze) skribis:

> * doc/guix.texi: Add section "Invoking guix deploy".

Yay!

You can add a copyright line for you at the top of guix.texi.

> +@section Invoking @code{guix deploy}
> +
> +We've already seen @code{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.  @command{guix deploy} enables you to use those
> +same @code{operating-system} declarations to manage multiple remote hosts at
> +once as a logical ``deployment''.

Perhaps add something like:

  @quotation Note
  The functionality described in this section is still under development
  and is subject to change.  Get in touch with us on
  @email{guix-devel@@gnu.org}!
  @end quotation

That way, if we make a Guix release before this is all stabilized,
we make sure people have appropriate expectations.  :-)

> +complex deployment may involve, for example, starting virtual machines through
> +a VPS provider.  In such a case, a different @var{environment} type would be
     ^^^
I would write “Virtual Private Server (VPS)”.

I hope the nitpicking level is acceptable, let me know.  I’m really
excited to see this land in master!

Ludo’.