feat: cli usage instructions

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.