Merge pull request #8 into master

ef0c8a5 markdown: update repo domain to gitea.evergreencrypto.co (Aaron Fiore)
661c089 README: update repo domain to gitea.evergreencrypto.co (Aaron Fiore)

README.md

@@ -18,7 +18,7 @@
 
 <div align="center">
 
-[<img src="assets/branding/png/docker-finance.png" height=75% width=75% align="center" />](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+[<img src="assets/branding/png/docker-finance.png" height=75% width=75% align="center" />](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 </div>
 

markdown/How-do-I-connect.md

@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10% />](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10% />](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[How do I connect?](#how-do-i-connect)**
   * [`#docker-finance:matrix.org`](#docker-financematrixorg)

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)
@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[How do I contribute?](#how-do-i-contribute)**
   * [Donate](#donate)
@@ -34,7 +34,7 @@ Your input while using docker-finance is [valuable and appreciated](How-do-I-con
 
 #### Dependencies
 
-If you like docker-finance, please consider donating to the [wonderful projects](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.yaml) that it relies upon.
+If you like docker-finance, please consider donating to the [wonderful projects](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.yaml) that it relies upon.
 
 ### Development
 
@@ -47,7 +47,7 @@ When developing with the [`finance` image](What-does-it-do.md#image-finance), yo
   * Developer mockup CSVs can be found in the `mockup` directories within the hledger-flow section of the docker-finance repository
   * Developer mockup CSVs will *intentionally* have multiple years within in a `1-in/year` directory in order to test for year parsing
 
-When developing non-code documentation, please work with the [dfi-docs](https://gitea.com/EvergreenCrypto/dfi-docs) repository.
+When developing non-code documentation, please work with the [dfi-docs](https://gitea.evergreencrypto.co/EvergreenCrypto/dfi-docs) repository.
 
 #### Plugins
 
@@ -64,7 +64,7 @@ Upon client `gen`, a client-side directory layout is generated. This layout cons
 **WARNING: don't change the parent client-side directory layout** (although, you can add subdirectories):
   - e.g., `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/finance/my_experimental_plugins/{file1.ext,file2.ext}`
 
-This client-side "custom" layout somewhat mirrors the repository's plugins layout (see [`client/plugins`](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/plugins) and [`container/plugins`](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/container/plugins)).
+This client-side "custom" layout somewhat mirrors the repository's plugins layout (see [`client/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/plugins) and [`container/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/container/plugins)).
 
 For more information, see the example plugins and help usage of each module, e.g.; `plugins help` or `help()`.
 
@@ -80,12 +80,172 @@ Before sending a pull request:
 3. As for style guidelines, these are recommended:
    - [Bash](https://google.github.io/styleguide/shellguide.html)
    - [C++](https://google.github.io/styleguide/cppguide.html)
-   - [PHP](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/ruleSets/PhpCsFixer.rst)
+     * 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/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.
+Any non-code documentation should go into the [dfi-docs](https://gitea.evergreencrypto.co/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`)

markdown/How-do-I-get-started.md

@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[How do I get started?](#how-do-i-get-started)**
   * [Installation](#installation)
@@ -69,7 +69,7 @@ docker-finance *should* work out-of-the-box on any modern Linux system. For exam
            echo "FATAL: docker-finance repo not found" >&2
          fi
        else
-         if ! git clone https://gitea.com/EvergreenCrypto/docker-finance; then
+         if ! git clone https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance; then
            echo "FATAL: docker-finance repo not cloned" >&2
          fi
        fi
@@ -91,7 +91,7 @@ docker-finance *should* work out-of-the-box on any modern Linux system. For exam
 
 5. Prepare your client (host) shell environment:
 
-   Install convenience aliases and command completion to your shell environment (see [install.bash](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/install.bash) for details):
+   Install convenience aliases and command completion to your shell environment (see [install.bash](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/install.bash) for details):
 
      ```bash
      ./docker-finance/client/install.bash && source ~/.bashrc
@@ -221,7 +221,7 @@ The client (host) configuration file:
   - client/container configurations can be stored on shared NFS/CIFS or related network storage (with applicable user permissions)
     - allows for customizable locations of *all* container data on any mountable filesystem (as a replacement for Docker Volumes)
   - consists solely of variables in the format `DOCKER_FINANCE_VARIABLE=value` and is used by both Docker and docker-finance
-  - default template variables can be found in [gen.bash](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/client/env/gen.bash), as described below
+  - default template variables can be found in [gen.bash](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/client/env/gen.bash), as described below
 
 After `gen` is complete, you can edit this file with the client (host) command: `edit type=env` (see [Client (Host) Command Format](How-do-I-use-it.md#client-host-command-format)).
 
@@ -393,7 +393,7 @@ The client (host) custom Dockerfile:
     - allows you to append any Dockerfile command to a generated build
   - is located in the `${DOCKER_FINANCE_CLIENT_CONF}/client/Dockerfiles/` directory
     - format consists of `username@hostname` where `username` is your host username and `hostname` is your machine's hostname
-  - default generated templates can be found [here](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/client/Dockerfiles)
+  - default generated templates can be found [here](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/client/Dockerfiles)
 
 After `gen` is complete, you can edit this file with the client (host) command: `edit type=build` (see [Client (Host) Command Format](How-do-I-use-it.md#client-host-command-format)).
 
@@ -409,7 +409,7 @@ The client/container shell script (Superscript) is a bind-mounted (by directory)
 
 See the in-file comments for further documentation:
 
-  - [superscript.bash.in](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/shell/superscript.bash.in)
+  - [superscript.bash.in](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/shell/superscript.bash.in)
 
 After `gen` is complete, you can edit this file with the client (host) command: `edit type=shell` (see [Client (Host) Command Format](How-do-I-use-it.md#client-host-command-format)).
 
@@ -427,7 +427,7 @@ By default, this file will contain user aliases for all container commands. Thes
 
 See the in-file comments for further documentation:
 
-  - [subscript.bash.in](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/shell/subscript.bash.in)
+  - [subscript.bash.in](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/shell/subscript.bash.in)
 
 After `gen` is complete, from within the container, you can edit this file with: `dfi profile/subprofile edit type=shell` (see [Container Command Format](How-do-I-use-it.md#container-command-format)).
 
@@ -437,7 +437,7 @@ The source of all remote API fetching configurations (exchanges, blockchains, ma
 
 See the in-file comments for further documentation:
 
-  - [fetch.yaml.in](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/fetch/fetch.yaml.in)
+  - [fetch.yaml.in](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/fetch/fetch.yaml.in)
 
 After `gen` is complete, from within the container, you can edit this file with: `dfi profile/subprofile edit type=fetch` (see [Container Command Format](How-do-I-use-it.md#container-command-format)).
 
@@ -447,7 +447,7 @@ The source of all custom metadata information (typically used to store cryptocur
 
 See the in-file comments for further documentation:
 
-  - [meta.csv.in](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/meta/meta.csv.in)
+  - [meta.csv.in](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/meta/meta.csv.in)
 
 After `gen` is complete, from within the container, you can edit this file with: `dfi profile/subprofile edit type=meta` (see [Container Command Format](How-do-I-use-it.md#container-command-format)).
 

markdown/How-do-I-use-it.md

@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[How do I use it?](#how-do-i-use-it)**
   * [Mostly-Unified CLI](#mostly-unified-cli)

markdown/What-does-it-do.md

@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[What does it do?](#what-does-it-do)**
   * [Highlights](#highlights)

markdown/What-is-supported.md

@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[What is supported?](#what-is-supported)**
   * [CeFi (centralized custodians)](#cefi)

markdown/Where-is-the-legalese.md

@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[Where is the legalese?](#where-is-the-legalese)**
   * [License and Disclaimer](#license-and-disclaimer)