doc: cuirass: Update documentation.

* doc/guix.texi (Continuous Integration): Update Cuirass documentation.

1 files changed, 141 insertions, 55 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 096ffc7425..29c8a12ee3 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -27085,9 +27085,9 @@ The verbosity level of the daemon.
 @subsection Continuous Integration
 
 @cindex continuous integration
-@uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a
-continuous integration tool for Guix.  It can be used both for development and
-for providing substitutes to others (@pxref{Substitutes}).
+@uref{https://guix.gnu.org/cuirass/, Cuirass} is a continuous
+integration tool for Guix.  It can be used both for development and for
+providing substitutes to others (@pxref{Substitutes}).
 
 The @code{(gnu services cuirass)} module provides the following service.
 
@@ -27096,45 +27096,44 @@ The type of the Cuirass service.  Its value must be a
 @code{cuirass-configuration} object, as described below.
 @end defvr
 
-To add build jobs, you have to set the @code{specifications} field of the
-configuration.  Here is an example of a service that polls the Guix repository
-and builds the packages from a manifest.  Some of the packages are defined in
-the @code{"custom-packages"} input, which is the equivalent of
-@env{GUIX_PACKAGE_PATH}.
+To add build jobs, you have to set the @code{specifications} field of
+the configuration.  For instance, the following example will build all
+the packages provided by the @code{my-channel} channel.
 
 @lisp
 (define %cuirass-specs
-  #~(list
-     '((#:name . "my-manifest")
-       (#:load-path-inputs . ("guix"))
-       (#:package-path-inputs . ("custom-packages"))
-       (#:proc-input . "guix")
-       (#:proc-file . "build-aux/cuirass/gnu-system.scm")
-       (#:proc . cuirass-jobs)
-       (#:proc-args . ((subset . "manifests")
-                       (systems . ("x86_64-linux"))
-                       (manifests . (("config" . "guix/manifest.scm")))))
-       (#:inputs . (((#:name . "guix")
-                     (#:url . "git://git.savannah.gnu.org/guix.git")
-                     (#:load-path . ".")
-                     (#:branch . "master")
-                     (#:no-compile? . #t))
-                    ((#:name . "config")
-                     (#:url . "https://git.example.org/config.git")
-                     (#:load-path . ".")
-                     (#:branch . "master")
-                     (#:no-compile? . #t))
-                    ((#:name . "custom-packages")
-                     (#:url . "https://git.example.org/custom-packages.git")
-                     (#:load-path . ".")
-                     (#:branch . "master")
-                     (#:no-compile? . #t)))))))
+  #~(list (specification
+           (name "my-channel")
+           (build '(channels my-channel))
+           (channels
+            (cons (channel
+                   (name 'my-channel)
+                   (url "https://my-channel.git"))
+                  %default-channels)))))
 
 (service cuirass-service-type
          (cuirass-configuration
           (specifications %cuirass-specs)))
 @end lisp
 
+To build the @code{linux-libre} package defined by the default Guix
+channel, one can use the following configuration.
+
+@lisp
+(define %cuirass-specs
+  #~(list (specification
+           (name "my-linux")
+           (build '(packages "linux-libre")))))
+
+(service cuirass-service-type
+         (cuirass-configuration
+          (specifications %cuirass-specs)))
+@end lisp
+
+The other configuration possibilities, as well as the specification
+record itself are described in the Cuirass manual
+(@pxref{Specifications,,, cuirass, Cuirass}).
+
 While information related to build jobs is located directly in the
 specifications, global settings for the @command{cuirass} process are
 accessible in other @code{cuirass-configuration} fields.
@@ -27143,20 +27142,15 @@ accessible in other @code{cuirass-configuration} fields.
 Data type representing the configuration of Cuirass.
 
 @table @asis
+@item @code{cuirass} (default: @code{cuirass})
+The Cuirass package to use.
+
 @item @code{log-file} (default: @code{"/var/log/cuirass.log"})
 Location of the log file.
 
 @item @code{web-log-file} (default: @code{"/var/log/cuirass-web.log"})
 Location of the log file used by the web interface.
 
-@item @code{queries-log-file} (default: @code{#f})
-Location of the SQL queries log file.  By default, SQL queries logging is
-disabled.
-
-@item @code{web-queries-log-file} (default: @code{#f})
-Location of the web SQL queries log file.  By default, web SQL queries
-logging is disabled.
-
 @item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
 Location of the repository cache.
 
@@ -27170,17 +27164,19 @@ Owner's group of the @code{cuirass} process.
 Number of seconds between the poll of the repositories followed by the
 Cuirass jobs.
 
-@item @code{queue-size} (default: @code{1})
-Size of the database writer queue.
+@item @code{parameters} (default: @code{#f})
+Read parameters from the given @var{parameters} file.  The supported
+parameters are described here (@pxref{Parameters,,, cuirass, Cuirass}).
 
-@item @code{database} (default: @code{"/var/lib/cuirass/cuirass.db"})
-Location of sqlite database which contains the build results and previously
-added specifications.
+@item @code{remote-server} (default: @code{#f})
+A @code{cuirass-remote-server-configuration} record to use the build
+remote mechanism or @code{#f} to use the default build mechanism.
 
-@item @code{ttl} (default: @code{(* 30 24 3600)})
-Specifies the time-to-live (TTL) in seconds of garbage collector roots that
-are registered for build results.  This means that build results are protected
-from garbage collection for at least @var{ttl} seconds.
+@item @code{database} (default: @code{"dbname=cuirass host=/var/run/postgresql"})
+Use @var{database} as the database containing the jobs and the past
+build results. Since Cuirass uses PostgreSQL as a database engine,
+@var{database} must be a string such as @code{"dbname=cuirass
+host=localhost"}.
 
 @item @code{port} (default: @code{8081})
 Port number used by the HTTP server.
@@ -27190,11 +27186,9 @@ Listen on the network interface for @var{host}.  The default is to
 accept connections from localhost.
 
 @item @code{specifications} (default: @code{#~'()})
-A gexp (@pxref{G-Expressions}) that evaluates to a list of specifications,
-where a specification is an association list
-(@pxref{Associations Lists,,, guile, GNU Guile Reference Manual}) whose
-keys are keywords (@code{#:keyword-example}) as shown in the example
-above.
+A gexp (@pxref{G-Expressions}) that evaluates to a list of
+specifications records.  The specification record is described in the
+Cuirass manual (@pxref{Specifications,,, cuirass, Cuirass}).
 
 @item @code{use-substitutes?} (default: @code{#f})
 This allows using substitutes to avoid building every dependencies of a job
@@ -27210,8 +27204,100 @@ packages locally.
 @item @code{extra-options} (default: @code{'()})
 Extra options to pass when running the Cuirass processes.
 
+@end table
+@end deftp
+
+@cindex remote build
+@subsubheading Cuirass remote building
+
+Cuirass supports two mechanisms to build derivations.
+
+@itemize
+@item Using the local Guix daemon.
+This is the default build mechanism.  Once the build jobs are
+evaluated, they are sent to the local Guix daemon.  Cuirass then
+listens to the Guix daemon output to detect the various build events.
+
+@item Using the remote build mechanism.
+The build jobs are not submitted to the local Guix daemon.  Instead, a
+remote server dispatches build requests to the connect remote workers,
+according to the build priorities.
+
+@end itemize
+
+To enable this build mode a @code{cuirass-remote-server-configuration}
+record must be passed as @code{remote-server} argument of the
+@code{cuirass-configuration} record.  The
+@code{cuirass-remote-server-configuration} record is described below.
+
+This build mode scales way better than the default build mode.  This is
+the build mode that is used on the GNU Guix build farm at
+@url{https://ci.guix.gnu.org}.  It should be preferred when using
+Cuirass to build large amount of packages.
+
+@deftp {Data Type} cuirass-remote-server-configuration
+Data type representing the configuration of the Cuirass remote-server.
+
+@table @asis
+@item @code{backend-port} (default: @code{5555})
+The TCP port for communicating with @code{remote-worker} processes
+using ZMQ.  It defaults to @code{5555}.
+
+@item @code{log-port} (default: @code{5556})
+The TCP port of the log server.  It defaults to @code{5556}.
+
+@item @code{publish-port} (default: @code{5557})
+The TCP port of the publish server.  It defaults to @code{5557}.
+
+@item @code{log-file} (default: @code{"/var/log/cuirass-remote-server.log"})
+Location of the log file.
+
+@item @code{cache} (default: @code{"/var/cache/cuirass/remote"})
+Use @var{cache} directory to cache build log files.
+
+@item @code{trigger-url} (default: @code{#f})
+Once a substitute is successfully fetched, trigger substitute baking at
+@var{trigger-url}.
+
+@item @code{public-key}
+@item @code{private-key}
+Use the specific @var{file}s as the public/private key pair used to sign
+the store items being published.
+
+@end table
+@end deftp
+
+At least one remote worker must also be started on any machine of the
+local network to actually perform the builds and report their status.
+
+@deftp {Data Type} cuirass-remote-worker-configuration
+Data type representing the configuration of the Cuirass remote-worker.
+
+@table @asis
 @item @code{cuirass} (default: @code{cuirass})
 The Cuirass package to use.
+
+@item @code{workers} (default: @code{1})
+Start @var{workers} parallel workers.
+
+@item @code{server} (default: @code{#f})
+Do not use Avahi discovery and connect to the given @code{server} IP
+address instead.
+
+@item @code{systems} (default: @code{(list (%current-system))})
+Only request builds for the given @var{systems}.
+
+@item @code{log-file} (default: @code{"/var/log/cuirass-remote-worker.log"})
+Location of the log file.
+
+@item @code{publish-port} (default: @code{5558})
+The TCP port of the publish server.  It defaults to @code{5558}.
+
+@item @code{public-key}
+@item @code{private-key}
+Use the specific @var{file}s as the public/private key pair used to sign
+the store items being published.
+
 @end table
 @end deftp