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

• How do I get started?
  • Installation
  • Environment Generation
  • Configuration Files

How do I get started?

docker-finance (dfi) is not your typical Docker image in which you simply pull and containerize. dfi is an image-based accounting system that operates translucently between your client (host) and container; keeping your finances containerized (with all the benefits of containerization).

To get started, you'll only need a modern Linux client (host) with a working Docker installation.

Installation

docker-finance should work out-of-the-box on any modern Linux system. For example, if your client (host) is Ubuntu, the default installation of coreutils, shells and utils that came with your system will satisfy requirements. However, you'll still need to manually install Docker (see below).

1. Install required dependencies:

   1. Docker Engine (post-install configuration) along with Docker Compose and Docker Buildx plugins
      • Latest stable versions
   2. GNU Bash
      • Latest stable version (or at least 5.0.17)
      • Installed by default on most Linux distributions
   3. Git
      • Latest stable version (or at least 2.25.1)
      • Only needed for step 3 but should be kept in order to:
        • Remain up-to-date with the docker-finance repository
        • Safely track your workflow related data (journals, metadata, etc.)

2. Install optional helpers:

   Although not required, consider the following for workflow efficiency:

   • A terminal multiplexer like tmux or screen
   • A terminal file manager like mc (Midnight Commander)

3. Prepare your repository:

   Before proceeding, change your directory to a persistent path that you'll likely keep; as your client (host) shell environment will be aliased/sourced to the path you choose.

   if hash git &>/dev/null; then
     if [ -d docker-finance ]; then
       if pushd docker-finance &>/dev/null; then
         if ! git pull --tags; then
           echo "FATAL: docker-finance repo not pulled" >&2
         fi
         popd 1>/dev/null
       else
         echo "FATAL: docker-finance repo not found" >&2
       fi
     else
       if ! git clone https://gitea.com/EvergreenCrypto/docker-finance; then
         echo "FATAL: docker-finance repo not cloned" >&2
       fi
     fi
   else
     echo "FATAL: git not found" >&2
   fi
   

4. Verify your repository (recommended):

   if pushd docker-finance/ 1>/dev/null; then
     gpg --keyserver hkp://keyserver.ubuntu.com --recv-key 518A22F85BEFD32BCC99C48603F90C4F35E0213E \
       && git verify-commit $(git log -n1 --pretty=format:"%H") \
       && echo -e "\nSUCCESS: now confirm matching key = 518A22F85BEFD32BCC99C48603F90C4F35E0213E" \
       || echo -e "\nFATAL: no key available or possible MITM - do not use!"
     popd 1>/dev/null
   fi
   

5. Prepare your client (host) shell environment:

   Install convenience aliases and command completion to your shell environment (see install.bash for details):

   ./docker-finance/client/install.bash && source ~/.bashrc
   

   • The dfi alias of docker-finance is the recommended alias to use for for all client/container operations
   • After your first image is built (step 7), you can use commandline completion for all dfi images and commands

6. Generate your translucent environment:

   This will create your client/container environment for the given image; as well as your first container profile/subprofile:

   dfi archlinux/${USER}:default gen all=all
   

   • To regenerate any step in this process, now or in the future, use gen help for available options
   • To use the ubuntu image instead, replace archlinux with ubuntu here and for all remaining steps

7. Build your default dfi image:

   dfi archlinux/${USER}:default build type=default
   

   • Use the build help command to see available build options (such as smaller, faster builds)

8. Bring up your container:

   dfi archlinux/${USER}:default up
   

9. You're inside! See How do I use it? for next steps.

10. (Optional) Developers: on your client (host), you can build and setup the dev-tools platform:

    dfi dev-tools/${USER}:default gen all=all && dfi dev-tools/${USER}:default build type=default
    

Environment Generation

docker-finance's environment consists of two scopes: client and container. The client (host) view is confined to the host while the container view confined to the container (though the client can, at times, view from within the container's perspective).

In terms of configuration, the client (host) has the following files:

1. The Client (Host) Configuration File (client only)
2. The Client (Host) Custom Dockerfile (client only)
3. The Client (Host) / Container Superscript (client/container)

You'll create these files (and more) when running client (host) command gen, as seen below.

Tip: client scope can be considered an OOP class which inherits the container as a protected class, with the Client (Host) / Container Superscript binding them.

---

Client Generation

When running gen, you'll see the following:

Client environment file found, backup then generate new one? [Y/n]

Generates the client (host) configuration file (see the Client (Host) Configuration File for details).

• You can use the generated defaults but make sure your directory layout matches accordingly
• To easily edit this configuration file after gen is complete, run client (host) command edit type=env

Generating new custom (optional) Dockerfile

Generates custom Dockerfile. Do as you wish; install your own container packages, etc. (see the Client (Host) Custom Dockerfile for details).

• To easily edit this configuration file after gen is complete, run client (host) command edit type=build

Generate joint client/container superscript? [Y/n]

Select 'y' if this is your first-run for the given platform and tag, or if you need to regenerate the file (see Client (Host) / Container Superscript for details).

---

Container Generation

After the previous client environment is generated, the following will prepare the container environment (everything you'll need while inside docker-finance).

Generate container finance flow (layout and profiles)? [Y/n]

Not limited to hledger-flow data, this option leads to generating the layout and files needed for processing all docker-finance end-user generated data (journals, configurations, etc.).

Although the container environment is a minimum requirement, here you'll have the option to continue generation.

Enter profile name (e.g., family in 'family/alice')

Enter subprofile name (e.g., alice in 'family/alice')

Container generation will always be for a specific profile with subprofile, and here is where you input that information. For example, you could have a family profile with subprofiles of various family members or a business profile with subprofiles of all the various businesses you own.

It should be noted that:

• all subsequent questions and container generation will relate to this profile/subprofile pairing
• all output will be sent to the ${DOCKER_FINANCE_CONTAINER_FLOW}/profiles/profile/subprofile path

Generate subprofile's subscript file? [Y/n]

The container's subprofile's shell script is where all subprofile commands and aliases exist.

This file is generated on a per-subprofile basis and all custom code on a per-subprofile basis should go here (see Subscript for details).

Generate subprofile's fetch configuration file? [Y/n]

The container's fetch configuration is what all remote fetching relies on: prices, exchanges, blockchain explorers; all are configured here (see Fetch for details).

Generate subprofile's financial metadata file? [Y/n]

The container's per-subprofile metadata file.

This file contains all your custom metadata and can edited with the edit and analyzed with the meta or root command (see Meta for details).

Generate subprofile's hledger configuration file? [Y/n]

This configuration file is specific to hledger. See hledger documentation for options.

Generate subprofile's hledger-flow accounts? [Y/n]

The container's hledger-flow accounts to be installed. These are the accounts described in What is supported?.

WARNING: if you plan to use blockchain-based wallets (coinbase-wallet, pera-wallet, ledger, metamask, etc.), you MUST generate their respective chains, as seen during generation (algorand, ethereum-based, tezos, etc).

Configuration Files

Client (Host) Configuration

The client (host) configuration file:

• is located in the ${DOCKER_FINANCE_CLIENT_CONF}/client/env/ directory, with subdirectory format of kernel-machine/platform/tag
  • format consists of username@hostname where username is your host username and hostname is your machine's hostname
• 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, 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).

DOCKER_FINANCE_CLIENT_CONF

Client (host) configuration path. Parent directory for client configuration files.

• Example: DOCKER_FINANCE_CLIENT_CONF=/home/${USER}/.config/docker-finance.d

DOCKER_FINANCE_CLIENT_FLOW

Client (host) finance-flow path. Parent directory for all profiles and end-user data.

• Example: DOCKER_FINANCE_CLIENT_FLOW=/net/nfs4/finance-flow

DOCKER_FINANCE_CLIENT_REPO

Client (host) path for the docker-finance code repository (from the host's perspective).

This parent directory is where the client and container directories are located.

• Example: DOCKER_FINANCE_CLIENT_REPO=/net/nfs4/git/docker-finance

DOCKER_FINANCE_CLIENT_SHARED

Client (host) path for the client/container shared directory.

The bind-mount is used exclusively for non-essential file sharing (custom scripts or any file you wish).

• Example: DOCKER_FINANCE_CLIENT_SHARED=/mnt/share.d

DOCKER_FINANCE_CLIENT_PLUGINS

Client (host) path for the client/container shared custom plugins.

The bind-mount is used exclusively for user-added plugins not in the repository.

• Example: DOCKER_FINANCE_CLIENT_PLUGINS=/home/${USER}/Development/dfi_custom-plugins

DOCKER_FINANCE_CONTAINER_CMD

The container's finance command (useful for experimental implementations).

Default: finance.bash (internally aliased to finance and dfi)

• Example: DOCKER_FINANCE_CONTAINER_CMD=finance.bash

DOCKER_FINANCE_CONTAINER_CONF

The container's configuration path (bind-mounted to client's (host's) configuration path).

• Example: DOCKER_FINANCE_CONTAINER_CONF=/home/${USER}/.config/docker-finance.d

DOCKER_FINANCE_CONTAINER_EDITOR

The container's default text editor.

• Example: DOCKER_FINANCE_CONTAINER_EDITOR=vim

DOCKER_FINANCE_CONTAINER_FLOW

The container's finance-flow path from the container's perspective.

This path is bind-mounted to the client's (host's) finance-flow path.

• Example: DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/finance-flow

DOCKER_FINANCE_CONTAINER_REPO

The container's docker-finance code repository path (as viewed from the container).

This path is bind-mounted to the client's (host's) docker-finance/container path.

• Example: DOCKER_FINANCE_CONTAINER_REPO=/home/${USER}/docker-finance

DOCKER_FINANCE_CONTAINER_SHARED

The container's share.d path, bind-mounted to client's (host's) share.d path.

• Example: DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/share.d

DOCKER_FINANCE_CONTAINER_PLUGINS

The client's custom plugin path (as viewed from the container).

This path is bind-mounted to the client's (host's) ${DOCKER_FINANCE_CLIENT_PLUGINS}/container path.

• Example: DOCKER_FINANCE_CONTAINER_PLUGINS=/home/${USER}/plugins

DOCKER_FINANCE_CPUS

Docker daemon/container setting: number of CPUs to use.

• Example: DOCKER_FINANCE_CPUS=2

DOCKER_FINANCE_DEBUG

Enable/disable debugging code paths (i.e., debug logging)

Debug log-levels range from none to most: 0 1 2

• Example: DOCKER_FINANCE_DEBUG=2

DOCKER_FINANCE_PORT_HLEDGER

hledger-web client-side (host) port

• Example: DOCKER_FINANCE_PORT_HLEDGER=5000

DOCKER_FINANCE_PORT_ROOT

root client-side (host) port for web interface

• Example: DOCKER_FINANCE_PORT_ROOT=8080

DOCKER_FINANCE_MEMORY

docker-finance container memory limit (see Docker documentation).

• Example: 5G

DOCKER_FINANCE_GID

Group ID for bind mount. MUST have write permissions to rw bind-mounts.

• Example: DOCKER_FINANCE_GID=998

DOCKER_FINANCE_UID

User ID for bind mount. MUST have write permissions to rw bind-mounts.

• Example: DOCKER_FINANCE_UID=1001

DOCKER_FINANCE_USER

docker-finance container user.

Container user's UID/GID SHOULD match DOCKER_FINANCE_UID and DOCKER_FINANCE_GID. This is automatically determined during Environment Generation.

User MUST have write permissions to rw bind-mounts.

• Example: DOCKER_FINANCE_USER=alice

---

Client (Host) Custom Dockerfile

The client (host) custom Dockerfile:

• is appended to the final generated 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

After gen is complete, you can edit this file with the client (host) command: edit type=build (see Client (Host) Command Format).

---

Client (Host) / Container Superscript

The client/container shell script (Superscript) is a bind-mounted (by directory) script that:

• is the intermediary between client and container
• is unique to each client (host) user (/home/alice, /home/bob, etc.)
• is the glue that ties together all container Subscript
• is generated on a per-client basis: all custom code on a per-client basis should go here

See the in-file comments for further documentation:

• 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).

---

Container Configurations

These configurations are confined solely to the container.

Subscript

The Subprofile's subscript is unique to each subprofile, for each profile/subprofile within the profiles parent directory.

By default, this file will contain user aliases for all container commands. These aliases are mostly useful for small setups or setups with uniquely named subprofiles among all profiles.

See the in-file comments for further documentation:

• 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).

Fetch

The source of all remote API fetching configurations (exchanges, blockchains, market prices). This file is used by both the fetch and edit type=fetch commands.

See the in-file comments for further documentation:

• 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).

Meta

The source of all custom metadata information (typically used to store cryptocurrency metadata information). This file is used by the meta, edit type=meta and root commands, as seen in Meta (w/ ROOT C++ analysis).

See the in-file comments for further documentation:

• 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).