diff --git a/content/ftest/cli.md b/content/ftest/cli.md new file mode 100644 index 0000000..13d6adc --- /dev/null +++ b/content/ftest/cli.md @@ -0,0 +1,100 @@ ++++ +title = "Using ftest CLI" +insert_anchor_links = "right" +weight = 2 ++++ + +The ftest binary can run in the following modes: + +1. Daemon: will act as a job server, listening for webhook events to + schedule new jobs. This mode is to be used on servers. + +2. CLI: Useful for running compliance tests locally on one's own + computer. + +## 0. Install Runtime Dependencies + +ftest invokes a few binaries that are listed bellow: + +1. [iproute2](https://packages.debian.org/bookworm/iproute2) +2. Docker +3. docker-compose +4. git + +_NOTE: The user running ftest binary must be part of the `docker` UNIX +group_ + +## 1. Setup networking + +ftest spawns a HTTP server to collect results from test suites. Right +now, it is hard-coded to listen on port `29130`. And, since test jobs +are run in containers and the ftest binary is going to be run on host +machine, we have to setup Docker and host machine's firewall to allow +traffic. We use an [nginx +container](https://git.batsense.net/ForgeFlux/ftest-nginx-proxy) to +achieve this. + +This guide has instructions for `ufw`, please adopt the same for your +setup. + +### i. Create Docker network `ftest` + +``` +docker network create --attachable -d bridge --subnet 192.168.32.0/20 ftest +``` + +_NOTE: if choosing custom subnet, adjust instructions in the section to match it_ + +### ii. Allow traffic from `ftest` net to host machine on port `29130` + +```bash +sudo ufw allow from 192.168.32.0/20 proto tcp to any port 29130 +``` + +## 2. Install ftest + +### i. Download assets + +```bash +wget https://dl.forgeflux.org/forgeflux/ftest/master/ftest-master-linux-amd64.tar.gz.asc +wget https://dl.forgeflux.org/forgeflux/ftest/master/ftest-master-linux-amd64.tar.gz.sha256 +wget https://dl.forgeflux.org/forgeflux/ftest/master/ftest-master-linux-amd64.tar.gz +``` + +### ii Verify checksum + +```bash +sha256sum -c ftest-master-linux-amd64.tar.gz.sha256 +``` + +### iii Verify GPG signature + +All ForgeFlux binaries are signed with [our GPG +key](http://keyserver.ubuntu.com/pks/lookup?search=56861597C15E54520A36983A6828E4A2E5B91DB9&fingerprint=on&op=index). +Please verify signatures to verify authenticity. + +```bash +gpg --keyserver keyserver.ubuntu.com --recv 56861597C15E54520A36983A6828E4A2E5B91DB9 +gpg --verify ftest-master-linux-amd64.tar.gz.asc +``` + +### iv. Install binary + +```bash +tar -xvzf ftest-master-linux-amd64.tar.gz && sudo cp ftest-master-linux-amd64/ftest /usr/local/bin +``` + +## 2. Run + +The [control repository](@/ftest/terminology.md#control-repository) has +a few pre-configured targets. We recommend starting from there. Please +see [here](@/ftest/tutorial-new-specimen.md) to configure ftest for new [specimens](@/ftest/terminology.md#specimen). + +```bash +git clone https://git.batsense.net/ForgeFlux/ftest-control +cd ftest-control/targets/forgejo +ftest test . +``` + +The results will be available in JSON format and HTML format in the same +directory.