6.1 Invoking cuirass register

The usual way to invoke cuirass registration process is as follows:

cuirass register --specifications specs

This starts a Cuirass registration instance building specs and storing the results using the default PostgreSQL database.

Additionally the following options can be used.

--one-shot

Instead of executing cuirass as a daemon looping over the jobs. Only evaluate and build the specifications once.

--cache-directory=directory

directory is the place where the VCS repositories used by the jobs are stored.

--specifications=specifications-file

-S specifications-file

Add the specifications defined in specifications-file in the job database before launching the evaluation and build processes.

--database=database

-D database

Use database as the database containing the jobs and the past build results. Since Cuirass uses PostgreSQL as a database engine, database must be a string such as "dbname=cuirass host=localhost". By default, Cuirass uses the following connection string: dbname=cuirass host=/var/run/postgresql".

--build-remote

Use the remote build mechanism, whereby build distribution is handled by a separate cuirass remote-server process (see below). This option can increase throughput and resilience when distributing builds to a large number of build machines.

When this option is omitted, builds are started using the “normal” Guix way, by asking guix-daemon to build them.

--parameters=parameters-file

-P parameters-file

Read parameters from the given parameters-file. The supported parameters are described here (see Parameters).

--ttl=duration

Cuirass registers build results as garbage collector (GC) roots, thereby preventing them from being deleted by the GC. The --ttl option instructs it to keep those GC roots live for at least duration—e.g., 1m for one month, 2w for two weeks, and so on. The default is 30 days.

Those GC roots are typically stored in /var/guix/gcroots/profiles/per-user/user/cuirass, where user is the user under which Cuirass is running.

--interval=n

-I n

Wait at most n seconds between each poll.

Note: We recommend notifying Cuirass when it should evaluate a jobset—e.g., because new code has been pushed to a channel’s Git repository—and passing a high value of n like 3600 (an hour): this will reduce network traffic as Cuirass will update its local checkouts only when needed, plus every n seconds “just in case”.

To trigger a jobset evaluation, issue an HTTP GET request, for example with a command along these lines:

wget --post-data="" -O /dev/null \
  https://cuirass.example.org/jobset/jobset/hook/evaluate

You would typically run that command as a push hook on the servers that host the Git repositories relevant to jobset.

Our course, you may only do this for repositories you control. For other repositories, periodic polling in unavoidable.

--threads=n

Use up to n kernel threads.

n should be lower than or equal to the number of CPU cores on the machine. In general though, having a large n is not very useful since the work of Cuirass is primarily I/O-bound—on the contrary, large values of n may increase overhead. The default value should be appropriate for most cases.

--version

-V

Display the actual version of cuirass.

--help

-h

Display an help message that summarize all the options provided.

6.2 Invoking cuirass web

The usual way to invoke the cuirass web server is as follows:

cuirass web

This starts a Cuirass web server on the default port. Additionally the following options can be used.

--database=database

-D database

Use database as the database containing the jobs and the past build results. Since Cuirass uses PostgreSQL as a database engine, database must be a string such as "dbname=cuirass host=localhost". By default, Cuirass uses the following connection string: dbname=cuirass host=/var/run/postgresql".

--parameters=parameters-file

-P parameters-file

Read parameters from the given parameters-file. The supported parameters are described here (see Parameters).

--port=num

-p num

Make the HTTP interface listen on port num. Use port 8080 by default.

--listen=host

Make the HTTP interface listen on network interface for host. Use localhost by default.

--version

-V

Display the actual version of cuirass.

--help

-h

Display an help message that summarize all the options provided.

6.3 Invoking cuirass remote-server

The remote-server command starts a daemon that is able to communicate with remote-worker processes; it is used in conjunction with cuirass register --build-remote (see above). Its role is to answer build requests from the workers, by sending back derivations that must be built.

On build completion it updates the database accordingly and possibly fetches build substitutes. The remote-server and remote-worker processes communicate using ZMQ over TCP.

Additionally the following options can be used.

--backend-port=port

The TCP port for communicating with remote-worker processes using ZMQ. It defaults to 5555.

--log-port=port

The TCP port of the log server. It defaults to 5556.

--publish-port=port

The TCP port of the publish server. It defaults to 5557.

--parameters=parameters-file

-P parameters-file

Read parameters from the given parameters-file. The supported parameters are described here (see Parameters).

--database=database

-D database

Use database PostgreSQL connection string.

--cache=directory

Use directory to cache build log files.

--log-expiry=duration

Periodically delete build logs older than duration, where ‘2m’ means “2 months”, ‘10d’ means “10 days”, and so on. The default duration is 6 months.

--trigger-substitute-url=URL

Once a substitute is successfully fetched, trigger substitute baking at URL.

--user=user

Change privileges to user as soon as possible—i.e., once the signing key has been read.

--no-publish

Do not start a publish server and ignore the publish-port argument. This can be useful if there is a standalone publish server standing next to the remote server.

--public-key=file

--private-key=file

Use the specific files as the public/private key pair used to sign the store items being published.

--version

-V

Display the actual version of cuirass.

--help

-h

Display an help message that summarize all the options provided.

6.4 Invoking cuirass remote-worker

The remote-worker command starts a daemon that is able to communicate with a remote-server process. Its role is to request builds to the remote-server, perform them and report their status.

The remote-worker is able to discover a remote-server process on the local network using Avahi and connect to it.

Additionally the following options can be used.

--workers=count

Start count parallel workers. It defaults to 1.

--publish-port=port

The TCP port of the publish server. It defaults to 5558.

--server=ip-address

Do not use Avahi discovery and connect to the given remote-server IP address.

--systems=systems

Only request builds for the given systems. It defaults to (list (%current-system)).

substitute-urls (default: %default-substitute-urls)

The list of URLs where to look for substitutes by default.

--public-key=file

--private-key=file

Use the specific files as the public/private key pair used to sign the store items being published.

--version

-V

Display the actual version of cuirass.

--help

-h

Display an help message that summarize all the options provided.