Write instructions for running CI locally

Continuous-integration.md

@@ -0,0 +1,80 @@
+## Running continuous integration locally
+
+### Motivation
+
+There are situations where you'll want to run the continuous integration workflow on a development machine. These include:
+
+- You want to check whether your code will pass continuous integration without committing your work.
+- You want to work on the continuous integration workflow.
+
+### Setup
+
+#### Install Forgejo Runner
+
+Setting up Forgejo Runner for local, manual use is simpler than setting it up for remote, automated use.
+
+1. Download these files from the [release page](https://data.forgejo.org/forgejo/runner/releases):
+   - The binary `forgejo-runner-#.#.#-linux-amd64`.
+   - *(Recommended)* The signature `forgejo-runner-#.#.#-linux-amd64.asc`.
+2. *(Recommended)* Verify the binary's authenticity by checking its signature.
+   1. Import Forgejo's public signing key by calling
+      ```bash
+      gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
+      ```
+      If that doesn't work, you can download the key manually:
+      1. Search in OpenPGP keyserver [web interface](https://keys.openpgp.org) for the fingerprint listed after `--recv` above.
+      2. Download the key and call `gpg --import` on it.
+   2. Check the signature by calling
+      ```bash
+      gpg --verify forgejo-runner-#.#.#-linux-amd64.asc forgejo-runner-#.#.#-linux-amd64
+      ```
+3. Give the binary permission to be executed by the user who owns it.
+4. *(Optional)* For convenience, put the binary in your command search path. I like to do this by placing two symbolic links in `~/.local/bin`, which is already on my search path:
+   
+   - A link called `forgejo-runner-#.#.#` that points to the location of the binary `forgejo-runner-#.#.#-linux-amd64`.
+   - A link called `forgejo-runner` that points to `forgejo-runner-#.#.#`.
+   
+   Now I can launch a specific version of the runner by calling `forgejo-runner-#.#.#`, and I can launch my chosen default version by calling `forgejo-runner`.
+
+#### *(Optional)* Install Docker and build the continuous integration container image
+
+If you want to run the continuous integration workflow in a Docker container, like the remote CI system does, you'll need to install Docker and build the container image.
+
+1. Install Docker
+   - On Ubuntu 22.04, I used the [`docker-compose`](https://packages.ubuntu.com/jammy/docker-compose) package, although [`docker.io`](https://packages.ubuntu.com/jammy/docker.io) might be enough.
+2. Go to the `tools/ci-image` folder in the dyna3 repository and run the `build` script. The script tells Docker to build the image described by the neighboring `Dockerfile` and place it in Docker's image store with the tag `dyna3:ci`.
+
+If you rebuild the Docker image with changes, the old version will still be sitting around in Docker's image store. Here's how to remove it.
+
+- If you only ever ran the old version through Forgejo Runner, all the containers that referred to it should've been cleaned up automatically, so `docker image prune` should remove it.
+  - ⚠️ This will also remove any other unreferenced images you might have in the image store.
+- If you ever ran the old version some other way, there may still be a container referring to it. In this case, get the old image's ID by finding it in the list displayed by `docker images`. Calling `docker image rm` on that ID should lead to an error that mentions which containers refer to the old image. Use `docker ps -a` to examine those containers and confirm that they're not needed anymore. Then use `docker rm` to remove the containers that refer to the old image.
+
+### Execution
+
+#### Running directly on your development system
+
+1. Go into the top level of the dyna3 repository and call
+   ```bash
+   forgejo-runner exec --image -self-hosted
+   ```
+
+This will only work if your build system is set up in the way the continuous integration workflow expects. For example, it assumes that you can call Cargo with the command `cargo`.
+
+#### Running in a Docker container
+
+1. Go into the top level of the dyna3 repository and call
+   ```bash
+   forgejo-runner exec
+   ```
+
+This will only work if you've done the Docker section of the setup procedure.
+
+#### Running one particular job
+
+The continuous integration workflow includes several jobs. If you only want to run one of them:
+
+1. Look up the name of the job you want to run. Job names can be found in two places that I know of:
+   - Listed under `jobs` in the workflow description, `.forgejo/workflows/continuous-integration.yaml`.
+   - In the `[continuous-integration.yaml/JOB_NAME]` annotations in the workflow's console output.
+2. Call one of the execution commands above with the extra option `--job JOB_NAME`.