package builder

  1. Overview
  2. Docs
Scheduling and executing shell jobs

Install

Dune Dependency

Authors

Maintainers

Sources

builder-0.3.1.tbz
sha256=0b85b4a8afcebbd82804234df72fa5f59ed9156ee56fcbfdbc883eb130c093fc
sha512=ab2d63a3a494b2f3710a13873a3c744c974e4f002aaf6ae8c2095c847205e2f8049ee9bf65cd28555353c4dce4ca56143fbc5da29aa65c1c5d48081ae7ad7521

Description

The builder server has a schedule of jobs to be executed, stored persistently on disk. Any number of workers can connect via TCP (using ASN.1 encoded messages) that execute a single job -- usually contained in a sandbox (FreeBSD jail or Docker container). A client is a command-line interface to modify the schedule. Access control is out of scope - run it locally on your build host. The server receives the output artifacts of each job, and either stores them on the local file system or upload them to a remote server via http.

See https://builds.robur.coop for the live web frontend (builder-web).

Published: 16 Mar 2022

README

builder - scheduling and executing jobs

This consists of three programs, a worker, a server, and a client. The single server contains a queue of jobs, which are consumed by a worker. Any number of worker can be connected to the server. The client can modify the schedule: add/remove/modify jobs, also observe a concrete job.

The server keeps persistent state of the job queue (so restarts / crashes are dealt with). A worker connects, provides some information about itself, and then waits for a job. Once a job is read and accepted, it is executed by the worker. Resulting artifacts can be transferred by the client to the server.

The client has the ability to schedule jobs at regular intervals - similar to crontab - but workers are usually executed in sandboxes/ jailed environments.

Handled and unhandled error conditions:

  • worker execution fails (timeout, restart, killed): not handled, but server has a timeout

  • worker execution gets a signal: reported to server

  • worker can't write job data files -> failure is captured and reported

  • worker can't read job output -> logged to client's console (without artifacts gathered)

  • worker errors when submitting console output -> exits

  • worker fails communication with server -> job is ignored (the server is responsible for restarting)

A templating mechanism is available, look for orb-build.template as examples. Currently FreeBSD, Debian and Ubuntu are supported, and a repository that receives jobs is live at https://builds.robur.coop/

FreeBSD installation

To install a ZFS snapshot for a builder jail, the poudriere utility can be used. After setting the ZROOT in /usr/local/etc/poudriere.conf, you can setup your jail snapshots via: poudriere jail -c -j 13-0-REL -m ftp-archive -v 13.0-RELEASE where the argument -j is the jailname, and -v describes the version to download (NB: look into man poudriere-jail for further options).

A jail.conf and a shell-script to launch a jail are provided in the FreeBSD subdirectory of this repository. Adjust the exec.start in jail.conf (and other paths, such as path) if appropriate. In load.sh, adapt the zpool and zfs snapshot source name.

Before starting your jails, they'll need an Internet connection for downloading and installing packages, e.g. /etc/pf.conf: nat pass on "wlan0" inet from "127.0.2.0/24" to any -> ("wlan")

Dependencies (16)

  1. base64
  2. http-lwt-client >= "0.0.4" & < "0.1.0"
  3. uuidm
  4. ptime
  5. lwt
  6. logs
  7. fpath
  8. fmt >= "0.8.7"
  9. duration
  10. cstruct >= "6.0.0"
  11. cmdliner >= "1.1.0"
  12. bos
  13. bheap >= "2.0.0"
  14. asn1-combinators
  15. dune >= "2.0.0"
  16. ocaml >= "4.08.0"

Dev Dependencies

None

Used by (1)

  1. builder-web

Conflicts

None