[//]: # (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.com/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.com/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.com/EvergreenCrypto/dfi-docs) repository. #### Plugins Plugins allow you to use docker-finance public APIs, libraries and environment (client and/or container) to meet your unique needs. These plugins are categorical; as in, there are client-side ("custom") plugins and repository ("repo") plugins. Additionally, there are subcategories such as `docker`, `finance` and `root` (respective to their modules). Client-side custom plugins allow you to drop-in any code that you write and keep them locally. Repository plugins are plugins that remain within the repository and will require a pull request for any changes to be made. Client-side custom plugins can be used for either client or container modules (see directory layout). Upon client `gen`, a client-side directory layout is generated. This layout consists of: - `${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker` - Custom plugins that function only client-side (`lib_docker`) - `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/{finance,root}` - Custom plugins that function only container-side (`lib_finance`, `root`) **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)). For more information, see the example plugins and help usage of each module, e.g.; `plugins help` or `help()`. > Note: for custom plugins within directory `docker` and `finance` that utilize the shell, any language can be used so long as the file is executable, reads the shell environment and can initiailize their respective libraries (`lib_docker`, `lib_finance`). #### 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.com/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)