Guix Services (GNU Guix Reference Manual)

10.8.30 Guix Services

Guix Build Coordinator

The Guix Build Coordinator aids in distributing derivation builds among machines running an agent. The build daemon is still used to build the derivations, but the Guix Build Coordinator manages allocating builds and working with the results.

Note: This service is considered experimental. Configuration options may be changed in a backwards-incompatible manner, and not all features have been thorougly tested.

The Guix Build Coordinator consists of one coordinator, and one or more connected agent processes. The coordinator process handles clients submitting builds, and allocating builds to agents. The agent processes talk to a build daemon to actually perform the builds, then send the results back to the coordinator.

There is a script to run the coordinator component of the Guix Build Coordinator, but the Guix service uses a custom Guile script instead, to provide better integration with G-expressions used in the configuration.

Variable: Scheme Variable guix-build-coordinator-service-type: Service type for the Guix Build Coordinator. Its value must be a guix-build-coordinator-configuration object.

Data Type: guix-build-coordinator-configuration

Data type representing the configuration of the Guix Build Coordinator.

package (default: guix-build-coordinator): The Guix Build Coordinator package to use.
user (default: "guix-build-coordinator"): The system user to run the service as.
group (default: "guix-build-coordinator"): The system group to run the service as.
database-uri-string (default: "sqlite:///var/lib/guix-build-coordinator/guix_build_coordinator.db"): The URI to use for the database.
agent-communication-uri (default: "http://0.0.0.0:8745"): The URI describing how to listen to requests from agent processes.
client-communication-uri (default: "http://127.0.0.1:8746"): The URI describing how to listen to requests from clients. The client API allows submitting builds and currently isn’t authenticated, so take care when configuring this value.
allocation-strategy (default: #~basic-build-allocation-strategy): A G-expression for the allocation strategy to be used. This is a procedure that takes the datastore as an argument and populates the allocation plan in the database.
hooks (default: ’()): An association list of hooks. These provide a way to execute arbitrary code upon certain events, like a build result being processed.
guile (default: guile-3.0-latest): The Guile package with which to run the Guix Build Coordinator.

Variable: Scheme Variable guix-build-coordinator-agent-service-type: Service type for a Guix Build Coordinator agent. Its value must be a guix-build-coordinator-agent-configuration object.

Data Type: guix-build-coordinator-agent-configuration

Data type representing the configuration a Guix Build Coordinator agent.

package (default: guix-build-coordinator)

The Guix Build Coordinator package to use.

user (default: "guix-build-coordinator-agent")

The system user to run the service as.

coordinator (default: "http://localhost:8745")

The URI to use when connecting to the coordinator.

authentication

Record describing how this agent should authenticate with the coordinator. Possible record types are described below.

systems (default: #f)

The systems for which this agent should fetch builds. The agent process will use the current system it’s running on as the default.

max-parallel-builds (default: 1)

The number of builds to perform in parallel.

max-1min-load-average (default: #f)

Load average value to look at when considering starting new builds, if the 1 minute load average exceeds this value, the agent will wait before starting new builds.

This will be unspecified if the value is #f, and the agent will use the number of cores reported by the system as the max 1 minute load average.

derivation-substitute-urls (default: #f)

URLs from which to attempt to fetch substitutes for derivations, if the derivations aren’t already available.

non-derivation-substitute-urls (default: #f)

URLs from which to attempt to fetch substitutes for build inputs, if the input store items aren’t already available.

Data Type: guix-build-coordinator-agent-password-auth

Data type representing an agent authenticating with a coordinator via a UUID and password.

uuid: The UUID of the agent. This should be generated by the coordinator process, stored in the coordinator database, and used by the intended agent.
password: The password to use when connecting to the coordinator.

Data Type: guix-build-coordinator-agent-password-file-auth

Data type representing an agent authenticating with a coordinator via a UUID and password read from a file.

uuid: The UUID of the agent. This should be generated by the coordinator process, stored in the coordinator database, and used by the intended agent.
password-file: A file containing the password to use when connecting to the coordinator.

Data Type: guix-build-coordinator-agent-dynamic-auth

Data type representing an agent authenticating with a coordinator via a dynamic auth token and agent name.

agent-name: Name of an agent, this is used to match up to an existing entry in the database if there is one. When no existing entry is found, a new entry is automatically added.
token: Dynamic auth token, this is created and stored in the coordinator database, and is used by the agent to authenticate.

Data Type: guix-build-coordinator-agent-dynamic-auth-with-file

Data type representing an agent authenticating with a coordinator via a dynamic auth token read from a file and agent name.

agent-name: Name of an agent, this is used to match up to an existing entry in the database if there is one. When no existing entry is found, a new entry is automatically added.
token-file: File containing the dynamic auth token, this is created and stored in the coordinator database, and is used by the agent to authenticate.

The Guix Build Coordinator package contains a script to query an instance of the Guix Data Service for derivations to build, and then submit builds for those derivations to the coordinator. The service type below assists in running this script. This is an additional tool that may be useful when building derivations contained within an instance of the Guix Data Service.

Variable: Scheme Variable guix-build-coordinator-queue-builds-service-type: Service type for the guix-build-coordinator-queue-builds-from-guix-data-service script. Its value must be a guix-build-coordinator-queue-builds-configuration object.

Data Type: guix-build-coordinator-queue-builds-configuration

Data type representing the options to the queue builds from guix data service script.

package (default: guix-build-coordinator): The Guix Build Coordinator package to use.
user (default: "guix-build-coordinator-queue-builds"): The system user to run the service as.
coordinator (default: "http://localhost:8746"): The URI to use when connecting to the coordinator.
systems (default: #f): The systems for which to fetch derivations to build.
systems-and-targets (default: #f): An association list of system and target pairs for which to fetch derivations to build.
guix-data-service (default: "https://data.guix.gnu.org"): The Guix Data Service instance from which to query to find out about derivations to build.
processed-commits-file (default: "/var/cache/guix-build-coordinator-queue-builds/processed-commits"): A file to record which commits have been processed, to avoid needlessly processing them again if the service is restarted.

Guix Data Service

The Guix Data Service processes, stores and provides data about GNU Guix. This includes information about packages, derivations and lint warnings.

The data is stored in a PostgreSQL database, and available through a web interface.

Variable: Scheme Variable guix-data-service-type: Service type for the Guix Data Service. Its value must be a guix-data-service-configuration object. The service optionally extends the getmail service, as the guix-commits mailing list is used to find out about changes in the Guix git repository.

Data Type: guix-data-service-configuration

Data type representing the configuration of the Guix Data Service.

package (default: guix-data-service): The Guix Data Service package to use.
user (default: "guix-data-service"): The system user to run the service as.
group (default: "guix-data-service"): The system group to run the service as.
port (default: 8765): The port to bind the web service to.
host (default: "127.0.0.1"): The host to bind the web service to.
getmail-idle-mailboxes (default: #f): If set, this is the list of mailboxes that the getmail service will be configured to listen to.
commits-getmail-retriever-configuration (default: #f): If set, this is the getmail-retriever-configuration object with which to configure getmail to fetch mail from the guix-commits mailing list.
extra-options (default: ’()): Extra command line options for guix-data-service.
extra-process-jobs-options (default: ’()): Extra command line options for guix-data-service-process-jobs.