From ea0673a1b3180eb386ab8c529e6c0a7eb8699ce6 Mon Sep 17 00:00:00 2001 From: Aaron Fiore Date: Thu, 29 Jan 2026 14:23:05 -0800 Subject: [PATCH] markdown: contribute: add `gitea`/`act_runner` CI documentation --- markdown/How-do-I-contribute.md | 161 +++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 1 deletion(-) diff --git a/markdown/How-do-I-contribute.md b/markdown/How-do-I-contribute.md index 8d6586e..746538e 100644 --- a/markdown/How-do-I-contribute.md +++ b/markdown/How-do-I-contribute.md @@ -86,7 +86,166 @@ Before sending a pull request: Any non-code documentation should go into the [dfi-docs](https://gitea.com/EvergreenCrypto/dfi-docs) repository. -#### Notes +#### CI using self hosted `gitea` with `act_runner` + +This documentation is intended for users who are not familiar with Docker, Gitea or its CI process. + +🚨 **It's recommended to host these instances LOCALLY within a virtual machine (such as VirtualBox or QEMU)** + +##### Minimum host requirements (guest VM) + + - Arch Linux guest VM + * ~100 GiB disk space for entire VM + - Guest VM packages + * `docker` `docker-compose` `docker-buildx` + * `npm` (needed for `actions` e.g., `actions/checkout@v4` etc.) + * `act_runner` + * `vim` (needed for `dfi` client functional tests) + - Host/Guest port forwarding (such as VirtualBox NAT Port Forwarding) + * 3000 to 3000 (gitea web) + * 2345 to 2345 (gitea ssh) + * 2222 to 22 (VM/arch ssh) + * NOTE: if using VirtualBox, and guest uses DHCP, Guest IP will likely be 10.0.2.15 + +⚠️ All further documentation will assume the following: + - Deployments are entirely within the guest virtual machine (Arch Linux) + - For the `gitea` instance: the running user is a privileged non-root user who is a member of the `docker` group + +##### Install host (guest VM) packages + + ```bash + sudo pacman -Syu --noconfirm docker docker-compose docker-buildx npm vim + ``` + +##### Install `gitea` + +1. Easily deploy gitea with a [rootless docker image](https://docs.gitea.com/installation/install-with-docker-rootless) with database (MySQL), and ensure the following in `docker-compose.yml`: + + ```yaml + ports: + - "3000:3000" + - "2345:2345" + ``` + +2. After following Gitea's deployment instructions, in the current gitea directory, bring up the instance (not detached) + + ```bash + docker compose up + ``` + +3. Visit `http://127.0.0.1:3000` + + - Change ssh port to 2345 (accept all other defaults) + - Optional: for email registration, register a `@localhost.localdomain` user + +4. Bring down instance + + Press Ctrl+C if not detached (otherwise, `docker compose down`). + +5. Run the following in the current existing gitea directory + + ```bash + sed -i 's:SSH_LISTEN_PORT = 2222:SSH_LISTEN_PORT = 2345:' config/app.ini + ``` + +6. Bring instance back up + + ```bash + docker compose up -d + ``` + +7. Setup `docker-finance` repository + + - Visit `http://127.0.0.1:3000`, login and create the repository + - Push the `master` branch + +##### Install `act_runner` + +Returning back you the guest VM, run the following: + + ```bash + sudo pacman -Syu --noconfirm act_runner \ + && sudo usermod -aG docker act_runner + ``` + +##### Prepare `act_runner` user + +The `act_runner` package will create a system level user with shell `/usr/bin/nologin`. This is a standard security practice and usually should never be touched. However, because we are working entirely within a virutal machine, and we need the runner to run all functional tests as a regular user (a `dfi`-ism; and `act_runner` should not `su` into any other user), the following will be required. + +⚠️ **If you're not using a VM (as was recommended at documentation start), now is the time to reconsider** + +As root, run the following: + + ```bash + chsh -s /usr/bin/bash act_runner \ + && usermod --expiredate= act_runner \ + && pushd /var/lib/act_runner \ + && touch .bashrc \ + && chown act_runner:act_runner .bashrc \ + && popd + ``` + +##### Prepare `act_runner` config + +The following label must be added to `/etc/act_runner/config.yaml` in order to build locally on the "host" (guest VM). + +Optional: you can remove all other ubuntu labels if this is a dedicated instance for docker-finance. + + ```yaml + labels: + # - ubuntu labels... + - "archlinux_vm:host" + ``` + +##### Register `act_runner` + +As root, run the following: + + ```bash + pushd /var/lib/act_runner \ + && act_runner --config /etc/act_runner/config.yaml register \ + && popd + ``` + +1. Enter `http://127.0.0.1:3000` for instance +2. Enter token from the "Create new Runner" pull down in your instance's `Settings -> Actions -> Runners` page +3. Press enter to use default runner name (or make a new name) + +Then enable the `act_runner` systemd service: + + ```bash + systemctl enable --now act_runner + ``` + +To see if your runner is found and "Idle", login to your gitea instance refresh the "Runners" page. + +##### Add Secrets to `gitea` Actions + +Various `dfi` APIs will require API keys for successful `fetch`ing. + +In Gitea's `Settings -> Actions -> Secrets -> Add Secret`, add the following `Name`/`Value` pairs after visiting their respective websites. Once you obtain your key, simply copy/paste into the respective `Value` fields: + + `Names`: + + - `CI_DFI_FETCH_MOBULA` + - `CI_DFI_FETCH_COINGECKO` (this is optional and can be ignored unless you want to use a paid plan) + - `CI_DFI_FETCH_ETHERSCAN` + +##### Push your changes to `gitea` + +And watch the "Actions" page on your Gitea instance do its thing. + +##### CI notes + +DinD cannot be used because of bind-mounting limitations with DinD. Since the runner's container needs to mount `dfi`'s layout, and `dfi` does not use named volumes, the existing layout must also exist on the host (and intermediate) container with the same ownership as the runner's container user. The maintenance of such a setup is not worth the effort when the above setup can easily be deployed. + +See also: + +- https://docs.gitea.com/usage/actions/act-runner +- https://gitea.com/gitea/act_runner/issues/380 +- https://stackoverflow.com/questions/55845723/volume-bind-mounting-from-docker-in-docker + +#### Development notes - Regarding client configuration, Docker volumes aren't used because of chicken-or-the-egg problem (among other reasons). docker-finance needs the client environment *before* building the Docker image and spawning the subsequent container (which would rely on volumes). - As described in [Mostly-Unified CLI](How-do-I-use-it.md#mostly-unified-cli), to use a developer version of any `dfi` image, simply build and tag with any tag name you'd like (e.g., `dfi archlinux/${USER}:dev build type=default`)