Merge pull request #7 into master

ea0673a markdown: contribute: add `gitea`/`act_runner` CI documentation (Aaron Fiore)

markdown/How-do-I-contribute.md

@@ -1,7 +1,7 @@
 
 [//]: # (docker-finance | modern accounting for the power-user)
 [//]: # ()
-[//]: # (Copyright [C] 2021-2025 Aaron Fiore [Founder, Evergreen Crypto LLC])
+[//]: # (Copyright [C] 2021-2026 Aaron Fiore [Founder, Evergreen Crypto LLC])
 [//]: # ()
 [//]: # (This program is free software: you can redistribute it and/or modify)
 [//]: # (it under the terms of the GNU General Public License as published by)
@@ -81,12 +81,171 @@ Before sending a pull request:
    - [Bash](https://google.github.io/styleguide/shellguide.html)
    - [C++](https://google.github.io/styleguide/cppguide.html)
      * Ignore their rule for [no `throw`'ing / no `exceptions`](https://google.github.io/styleguide/cppguide.html#Exceptions)
-   - [PHP](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/ruleSets/PhpCsFixer.rst)
+   - [PHP](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/ruleSets/PSR12.rst)
 4. If you can, please document the code in Doxygen style where applicable and run `doxygen gen` to see your code documentation.
 
 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`)