EvergreenCrypto/dfi-docs
1
1
Fork 1
Code Issues 4 Pull Requests Releases 4 Activity
Files
master
dfi-docs/markdown/How-do-I-contribute.md

12 KiB
Raw Permalink Blame History

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. Come, make this project your own!

Dependencies

If you like docker-finance, please consider donating to the wonderful projects that it relies upon.

Development

Developers: your work won't go unnoticed or unappreciated. Bounties are also available.

When developing any part of the codebase, you'll greatly benefit from building the dev-tools image.

When developing with the finance image, 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.

  • 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 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 and 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:
  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 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
sudo pacman -Syu --noconfirm docker docker-compose docker-buildx npm vim
Install gitea

  1. Easily deploy gitea with a rootless docker image with database (MySQL), and ensure the following in docker-compose.yml:

        ports:
      - "3000:3000"
      - "2345:2345"

  2. After following Gitea's deployment instructions, in the current gitea directory, bring up the instance (not detached)

    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

    sed -i 's:SSH_LISTEN_PORT = 2222:SSH_LISTEN_PORT = 2345:' config/app.ini

  6. Bring instance back up

    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:

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:

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.

  labels:
#   - ubuntu labels...
    - "archlinux_vm:host"
Register act_runner

As root, run the following:

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:

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 fetching.

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:

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, 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 <platform/user:tag> <cmd> [args] to debug before the Client (Host) Configuration File file is read.
  • The .C files you see in the repository are ROOT.cern macro files, not C-language files.
Reference in New Issue View Git Blame Copy Permalink