Open source: Install the agent

Open source

Install the agent

One command installs the hookci binary, the job user and the systemd units, and verifies the download before it touches anything.

The agent is a single static Go binary called hookci. The installer downloads it from a GitHub release, verifies it, and sets up the pieces that let it run jobs as an unprivileged user under systemd. If you only want to run checks on your laptop, the binary alone is enough: see Run checks locally.

Requirements

  • Linux on x86_64 (amd64) or aarch64 (arm64). Other systems stop with exit code 2.
  • systemd, and root access (the installer uses sudo when you are not root).
  • curl or wget, tar, and sha256sum or shasum.
  • git 2.30 or newer, which the agent uses to fetch the commits it builds. hookci doctor checks this.
  • Outbound HTTPS (port 443) to https://ci.webuno.io, or to your own hub if you self-host. No inbound ports are needed.

Run the installer

curl -fsSL https://ci.webuno.io/install | sh
build-host
build-host recording
$ curl -fsSL https://ci.webuno.io/install | sh
Downloading hookci_0.4.0_linux_amd64.tar.gz (v0.4.0)
Signature verified

Installed hookci v0.4.0. Next, pair this machine with the token from Slack App Home (https://ci.webuno.io):
  sudo hookci connect <pair-token>

Illustration. A normal install on a fresh host. cosign is optional but recommended.

The version in this sample is illustrative. The installer prints the real release tag, and a checksum mismatch stops it before anything is installed.

What it installs

Path What it is
/usr/local/bin/hookci The binary, mode 0755, owned by root.
hookci-run A system user with no home and a nologin shell. Jobs run as this user.
/etc/systemd/system/hookci.slice The cgroup slice that holds every agent and every job, so you can cap them together.
/etc/systemd/system/hookci-agent@.service The agent unit template. One instance per paired installation.
/var/lib/hookci State root, mode 0700, owned by root. Each agent keeps its own subdirectory here.

After writing the files the installer runs systemctl daemon-reload. It does not start anything: an agent has no identity until you pair it. Continue with Pair an agent for the hosted service, or Connect agents for your own hub.

If you install from a .deb or .rpm package instead, the post-install script creates the same user and directory and restarts running agents with systemctl try-restart 'hookci-agent@*.service'.

Verify what you downloaded

The installer always checks the archive against SHA256SUMS and exits with code 3 on a mismatch. When cosign is on your PATH it also verifies the signature of SHA256SUMS against the pinned release identity and exits with code 4 if that fails. Without cosign it says so:

cosign not found: checksum verified, signature not verified

Install cosign first if you want the signature check. To verify a release by hand:

VERSION=v0.4.0
BASE=https://github.com/KCuppens/hookci/releases/download/$VERSION
curl -fsSLO $BASE/hookci_${VERSION#v}_linux_amd64.tar.gz
curl -fsSLO $BASE/SHA256SUMS
curl -fsSLO $BASE/SHA256SUMS.sigstore.json

sha256sum --check --ignore-missing SHA256SUMS
cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "<release identity>" \
  --certificate-oidc-issuer https://github.com/login/oauth \
  SHA256SUMS

The release identity is published in the repository’s release notes at https://github.com/KCuppens/hookci. Each release carries four assets: the archive hookci_<version>_linux_<arch>.tar.gz, SHA256SUMS, SHA256SUMS.sigstore.json and trusted_root.json.

Environment variables

Set these before the sh, not before curl:

curl -fsSL https://ci.webuno.io/install | HOOKCI_VERSION=v0.4.0 sh
Variable Default Effect
HOOKCI_VERSION latest latest or a tag such as v0.4.0.
HOOKCI_PREFIX /usr/local Install root. The binary goes to $HOOKCI_PREFIX/bin/hookci and the unit’s ExecStart is rewritten to match. Must be an absolute path made of letters, digits and / . _ -.
HOOKCI_RELEASE_BASE https://github.com/KCuppens/hookci/releases/download Where release assets are fetched from. See mirrors below.
HOOKCI_INSTALL_DRY_RUN unset When set to any value, print the privileged steps and the generated unit instead of running them.

Pin a version

Pin in CI images and provisioning scripts so that a new release never arrives unannounced:

curl -fsSL https://ci.webuno.io/install | HOOKCI_VERSION=v0.4.0 sh

latest is resolved with a HEAD request to the releases page, which needs curl. Pinned versions work with wget alone. To move an installed host to another version later, use hookci upgrade.

Dry run

Review exactly what will happen before it does:

curl -fsSL https://ci.webuno.io/install | HOOKCI_INSTALL_DRY_RUN=1 sh

The download and verification still run. Each privileged step is printed as a + command line, followed by the generated unit file, and nothing on the system changes.

Mirrors and air-gapped hosts

HOOKCI_RELEASE_BASE must point at a tree that mirrors the release layout, <base>/<tag>/<asset>. Only https:// and file:// bases are accepted.

# an internal HTTPS mirror
curl -fsSL https://ci.webuno.io/install \
  | HOOKCI_RELEASE_BASE=https://mirror.example.com/hookci HOOKCI_VERSION=v0.4.0 sh

# a local directory, for hosts with no internet access
HOOKCI_RELEASE_BASE=file:///srv/hookci-releases HOOKCI_VERSION=v0.4.0 sh install.sh

Pin a version when you use a mirror. Verification works the same way against the mirrored files. Install cosign on the host so the signature is checked too: the checksum file alone comes from the mirror, so only the signature proves the files are the ones HookCI released.

Exit codes

Code Meaning
1 Any other failure.
2 Unsupported operating system or architecture.
3 The archive does not match SHA256SUMS.
4 The signature check failed.

Next steps

  1. Pair the machine: sudo hookci connect <pair-token>. See Pair an agent.
  2. Read how the service behaves in The agent service.
  3. Try a check on your laptop first with Run checks locally.