[//]: # (docker-finance | modern accounting for the power-user) [//]: # () [//]: # (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) [//]: # (the Free Software Foundation, either version 3 of the License, or) [//]: # ([at your option] any later version.) [//]: # () [//]: # (This program is distributed in the hope that it will be useful,) [//]: # (but WITHOUT ANY WARRANTY; without even the implied warranty of) [//]: # (MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the) [//]: # (GNU General Public License for more details.) [//]: # () [//]: # (You should have received a copy of the GNU General Public License) [//]: # (along with this program. If not, see .) # [](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance") - **[How do I contribute?](#how-do-i-contribute)** * [Donate](#donate) * [Development](#development) ## How do I contribute? There are multiple ways to contribute. All contributions are welcome! ### Donate #### Time Your input while using docker-finance is [valuable and appreciated](How-do-I-connect.md). Come, make this project your own! #### Dependencies 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 Developers: your work won't go unnoticed or unappreciated. [Bounties are also available](How-do-I-connect.md). When developing any part of the codebase, you'll greatly benefit from building the [`dev-tools` image](What-does-it-do.md#image-dev-tools). When developing with the [`finance` image](What-does-it-do.md#image-finance), you can create a development profile with the `gen` command argument `dev=on`. From there, you'll have access to mockup CSVs as described in [Flow Layout](How-do-I-use-it.md#flow-layout). * In addition to `dev=on`, run the `confirm=off` and `profile=` arguments to quickly spin-up a new development profile * 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.evergreencrypto.co/EvergreenCrypto/dfi-docs) repository. #### Plugins Primary plugin documentation can be found [here](How-do-I-use-it.md#plugins). Technically speaking, you can write custom plugins and never need to merge with the repository but if you feel that the plugin(s) would be beneficial to the public, add testcases and send everything with a [pull request](#pull-request). #### Pull Request Before sending a pull request: 1. If you created a new file, please run the dev-tools' `license file=/path/to/new/file.ext` command to update the copyright date and author. 2. For any work that can be linted, utilize the dev-tools image (e.g., `dfi dev-tools/${USER}:default linter type=bash,php,c++`). - See `linter help` for details. 3. As for style guidelines, these are recommended: - [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/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.evergreencrypto.co/EvergreenCrypto/dfi-docs) repository. #### 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`) - Run `DOCKER_FINANCE_DEBUG=1 dfi [args]` to debug *before* the [Client (Host) Configuration File](How-do-I-get-started.md#client-host-configuration) file is read. - The `.C` files you see in the repository are ROOT.cern macro files, not C-language files. [//]: # (vim: sw=2 sts=2 si ai et)