EvergreenCrypto/docker-finance
1
1
Fork 1
Code Issues 31 Pull Requests Actions Releases 10 Activity

README: various updates/fixes

Browse Source 
- Reflects the latest impl
- Adds various clarifications
- Adds clarity to environment `gen`
- Fixes/Improves installation notes/process
This commit is contained in:
Aaron Fiore
2024-07-29 16:33:51 -07:00
parent 7881f80b62
commit 5ed63e63ef
1 changed files with 145 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
README.md
View File

@@ -20,6 +20,8 @@
**Modern accounting for the power-user** | *Crypto, banking, tax prep, meta analysis & more!* **Modern accounting for the power-user** | *Crypto, banking, tax prep, meta analysis & more!*
> Looking for a Quickstart? Skip to [Installation](#installation).
1. **[What does it do?](#what-does-it-do)** 1. **[What does it do?](#what-does-it-do)**
- [Overview](#overview) - [Overview](#overview)
- [Highlights](#highlights) - [Highlights](#highlights)
@@ -50,9 +52,9 @@
### Overview ### Overview
`docker-finance` empowers you with a privacy-focused, highly uniform system of financial management - but with a modern twist. `docker-finance` gives you the power of a privacy-focused, highly uniform system of financial management - but with a modern twist.
Cryptocurrencies and blockchain metadata are unified with your legacy finances to create a world of best-practice accounting in a highly flexible, time-tested environment. Cryptocurrencies & blockchain metadata are unified with legacy finance to create a world of best-practice accounting in a highly flexible, time-tested environment.
### Highlights ### Highlights
@@ -241,32 +243,46 @@ Supported blockchains (independent of wallet type):
### Installation ### Installation
`docker-finance` is not your typical Docker image in which you simply pull and containerize but rather, its an *image-based* accounting system that functions almost entirely within your container. `docker-finance` is not your typical Docker image in which you simply pull and containerize, but rather it's an *image-based* accounting system that operates transparently between your client (host) and container; keeping your finances containerized, with all the benefits of containerization.
`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). `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 dependencies** (most recent stable versions): 1. **Install dependencies**:
- [Docker](https://docs.docker.com/engine/install/) with [post-install configuration](https://docs.docker.com/engine/install/linux-postinstall/) 1. [Docker Engine](https://docs.docker.com/engine/install/#supported-platforms) with [post-install configuration](https://docs.docker.com/engine/install/linux-postinstall/)
- GNU Bash 5.2+ - Latest version (or at least `27.1.1`)
- If you don't have `bash` installed by default (or if `bash` is not your default shell), setup `bash` per your system's documentation 2. [GNU Bash](https://www.gnu.org/software/bash/)
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git/), for step 3 (**strongly advised**): - Latest version (or at least `5.0.17`)
- `git` should be available via your package manager (e.g., `apt`, `pacman`, etc.). - Installed by *default* on most Linux distributions
2. **Open a `bash` shell**, if you haven't already done so. 2. **Install recommended**:
1. [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git/)
- Latest version (or at least `2.25.1`)
- Only needed for step 3 but should be kept in order to:
- Remain up-to-date with future `docker-finance` versions
- Safely track your workflow related data (journals, metadata, etc.)
2. Consider using a terminal multiplexer like [tmux](https://github.com/tmux/tmux/wiki) or [screen](https://www.gnu.org/software/screen/) for optimal workflow efficiency
3. **Copy/paste the following into your shell** (one-time repository clone and client preparation): 3. **Copy/paste the following into your `bash` shell** (one-time repository clone and client preparation):
```bash ```bash
bashrc=~/.bashrc bashrc=~/.bashrc
aliases=~/.bash_aliases aliases=~/.bash_aliases
if [[ -f "$bashrc" && ! -f "$aliases" ]]; then if ! test -f "$bashrc" || ! hash bash &>/dev/null; then
if ! grep -E "(^\. ${aliases}|^source ${aliases})" "$bashrc" 1>/dev/null; then echo "FATAL: unsupported bash installation"
aliases="$bashrc" else
fi if [[ ! -z "$SHELL" && "$SHELL" =~ bash ]]; then
fi if [ ! -f "$aliases" ]; then
if git clone https://gitea.com/EvergreenCrypto/docker-finance; then if ! grep -E "(\. ~/.bash_aliases|^source ~/.bash_aliases|^source ${aliases})" "$bashrc" &>/dev/null; then
if ! grep -E "^alias docker-finance=" "$aliases" 1>/dev/null; then aliases="$bashrc"
echo "alias docker-finance='$(pwd)/docker-finance/client/docker.bash archlinux/$(whoami):latest'" >>"$aliases" fi
source "$aliases" fi
if git clone https://gitea.com/EvergreenCrypto/docker-finance; then
if ! grep -E "^alias docker-finance=" "$aliases" &>/dev/null; then
echo "alias docker-finance='$(pwd)/docker-finance/client/docker.bash archlinux/$(whoami):latest'" >>"$aliases"
source "$aliases"
fi
fi
else
echo "FATAL: unsupported bash environment"
fi fi
fi fi
``` ```
@@ -291,97 +307,102 @@ Supported blockchains (independent of wallet type):
```bash ```bash
docker-finance build type=default && docker-finance up docker-finance build type=default && docker-finance up
``` ```
> Note: see `docker-finance build help` for build options. > See `docker-finance build help` for build options (such as smaller, faster builds)
7. **You're inside!** See [How do I use it?](#how-do-i-use-it) for next steps. 7. **You're inside!** See [How do I use it?](#how-do-i-use-it) for next steps.
### Environment Generation ### 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). Think of the client as a class that inherits the container as a protected class with all the relevant permissions and scope. `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 two primary files, with one of them being mutually shared with the container. The 1st file is the [Client (Host) Configuration File](#client-host-configuration) and the 2nd file is a joint [Client/Container Superscript](#clientcontainer-superscript). Think of this **superscript** as the glue that binds the client/container scopes. In terms of configuration, the client (host) has the following files:
1. The [Client (Host) Configuration File](#client-host-configuration) (client only)
2. The [Client (Host) Custom Dockerfile](#client-host-custom-dockerfile) (client only)
3. The [Client/Container Superscript](#clientcontainer-superscript) (client/container)
You'll create these files (and more) when running `docker-finance gen`, as seen below. You'll create these files (and more) when running `docker-finance gen`, as seen below.
#### Client generation > Tip: client scope can be considered an OOP class which inherits the container as a protected class, with the [Client/Container Superscript](#clientcontainer-superscript) binding them.
> Client-side environment found, backup then generate new one? ---
Generates the client (host) configuration file. See the [Client (Host) Configuration File](#configuration-files) section for details. #### Client Generation
When running `gen`, you'll see the following:
> *Client-side environment found, backup then generate new one?*
Generates the client (host) configuration file (see the [Client (Host) Configuration File](#client-host-configuration) for details).
- You can use the generated defaults but make sure your directory layout matches accordingly - 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 `docker-finance edit type=env` - To easily edit this configuration file after `gen` is complete, run `docker-finance edit type=env`
#### Container generation > *Generating new custom (optional) Dockerfile*
Container generation comes after (and *must* come after) client environment generation. Generates custom Dockerfile. Do as you wish; install your own container packages, etc. (see the [Client (Host) Custom Dockerfile](#client-host-custom-dockerfile) for details).
The container environment contains the bulk of configurations for everything you'll need while inside `docker-finance`. - To easily edit this configuration file after `gen` is complete, run `docker-finance edit type=build`
--- ---
> Generate (or update) container profile configs and/or accounts?
The container environment is a minimum requirement but here you'll have the option to continue generating or to backup a previous install. #### Container Generation
--- After the previous client environment is generated, the following will prepare the container environment (everything you'll need while inside `docker-finance`).
> Will this profile be used for development and/or demonstration?
> *Generate (or update) container profile configs and/or accounts?*
Although the container environment is a minimum requirement, here you'll have the option to continue generating or to backup a previous install.
> *Will this profile be used for development and/or demonstration?*
If you're a developer or wish to see the mockup test profile, select 'y' here. If you're a developer or wish to see the mockup test profile, select 'y' here.
> Enter profile name (e.g., family in 'family/alice') > *Enter profile name (e.g., family in 'family/alice')*
> Enter subprofile name (e.g., alice 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. 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.
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: It should be noted that:
- all subsequent questions and container generation will relate to this `profile/subprofile` pairing - 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 - all output will be sent to the `${DOCKER_FINANCE_CONTAINER_FLOW}/profiles/profile/subprofile` path
--- > *Generate (or update) joint client/container shell script (superscript)? [Y/n]*
> Generate (or update) joint client/container shell script (superscript)? [Y/n]
Select 'y' if this a first-run. If this is not a first-run but you need to regenerate the file, the select 'y'. Select 'y' if this a first-run. If this is not a first-run but you need to regenerate the file, then select 'y' (see [Superscript](#clientcontainer-superscript) for details).
See [Superscript](#clientcontainer-superscript) for details. > *Generate (or update) container hledger-flow configs and/or accounts?*
---
> Generate (or update) container hledger-flow configs and/or accounts?
Not limited to `hledger-flow` data, this option leads to generating *all* `docker-finance` journal data (and configurations). Not limited to `hledger-flow` data, this option leads to generating *all* `docker-finance` journal data (and configurations).
--- > *Generate (or update) subprofile's shell script?*
> Generate (or update) subprofile's shell script?
The container's subprofile's shell script is where all subprofile commands and aliases exist. 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. This file is generated on a per-subprofile basis and all custom code *on a per-subprofile basis* should go here (see [Subprofile](#subprofile) for details).
--- > *Generate (or update) subprofile's fetch configuration?*
> Generate (or update) subprofile's fetch configuration?
The container's fetch configuration is what all remote fetching relies on: prices, exchanges, blockchain explorers; all are configured here. See [Container Configurations](#container-configurations) for details. The container's fetch configuration is what all remote fetching relies on: prices, exchanges, blockchain explorers; all are configured here (see [Fetch](#fetch-1) for details).
--- > *Generate (or update) subprofile's financial metadata?*
> Generate (or update) subprofile's financial metadata?
The container's *per-subprofile* metadata file. 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 [Container Configurations](#container-configurations) for details. This file contains all your custom metadata and can edited with the `edit` and analyzed with the `meta` or `root` command (see [Meta](#meta) for details).
--- > *Generate (or update) subprofile's hledger-flow accounts?*
> Generate (or update) subprofile's hledger-flow accounts?
The container's `hledger-flow` accounts to be installed. These are the accounts described in [What is supported?](#what-is-supported). The container's `hledger-flow` accounts to be installed. These are the accounts described in [What is supported?](#what-is-supported).
> *Generate individual subprofile accounts instead of generating them all at once?*
If you intend to only use a few accounts, you can do so here. Otherwise, generate all accounts (recommended).
**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). **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 ### Configuration Files
> Note: Docker volumes aren't used because of chicken-or-the-egg problem, regarding client configuration (among other reasons). `docker-finance` needs the client environment *before* building the Docker image and spawning the subsequent container (which would rely on volumes). #### Client (Host) Configuration
#### Client (host) configuration
The client (host) configuration file: The client (host) configuration file:
- is located in the `${DOCKER_FINANCE_CLIENT_CONF}/client/env/` directory, with subdirectory format of `kernel-machine/platform/tag` - is located in the `${DOCKER_FINANCE_CLIENT_CONF}/client/env/` directory, with subdirectory format of `kernel-machine/platform/tag`
@@ -391,22 +412,23 @@ The client (host) configuration file:
- consists solely of variables in the format `DOCKER_FINANCE_VARIABLE=value` and is used by both Docker and `docker-finance` - 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](client/docker-finance.d/client/env/gen.bash), as described below - default template variables can be found in [gen.bash](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: `docker-finance edit type=env` (see [Client (Host) Command Format](#client-host-command-format)).
> DOCKER_FINANCE_CLIENT_CONF > DOCKER_FINANCE_CLIENT_CONF
Client (host) configuration path. Parent directory for client configuration files. Client (host) configuration path. Parent directory for client configuration files.
- Example: `DOCKER_FINANCE_CLIENT_CONF=/home/${USER}/.config/docker-finance.d` - Example: `DOCKER_FINANCE_CLIENT_CONF=/home/${USER}/.config/docker-finance.d`
---
> DOCKER_FINANCE_CLIENT_FLOW > DOCKER_FINANCE_CLIENT_FLOW
Client (host) hledger-flow path. Parent directory for all profiles. Client (host) hledger-flow path. Parent directory for all profiles.
- Example: `DOCKER_FINANCE_CLIENT_FLOW=/net/nfs4/hledger-flow` - Example: `DOCKER_FINANCE_CLIENT_FLOW=/net/nfs4/hledger-flow`
---
> DOCKER_FINANCE_CLIENT_REPO > DOCKER_FINANCE_CLIENT_REPO
Client (host) path for the `docker-finance` code repository (from the host's perspective). Client (host) path for the `docker-finance` code repository (from the host's perspective).
@@ -415,7 +437,7 @@ This parent directory is where the `client` and `container` directories are loca
- Example: `DOCKER_FINANCE_CLIENT_REPO=/net/nfs4/git/docker-finance` - Example: `DOCKER_FINANCE_CLIENT_REPO=/net/nfs4/git/docker-finance`
---
> DOCKER_FINANCE_CLIENT_SHARED > DOCKER_FINANCE_CLIENT_SHARED
Client (host) path for the client/container shared directory. Client (host) path for the client/container shared directory.
@@ -424,7 +446,6 @@ The bind-mount is used exclusively for non-essential file sharing (custom script
- Example: `DOCKER_FINANCE_CLIENT_SHARED=/mnt/share.d` - Example: `DOCKER_FINANCE_CLIENT_SHARED=/mnt/share.d`
---
> DOCKER_FINANCE_CONTAINER_CMD > DOCKER_FINANCE_CONTAINER_CMD
@@ -434,21 +455,21 @@ Default: `finance.bash` (internally aliased to `finance`)
- Example: `DOCKER_FINANCE_CONTAINER_CMD=finance.bash` - Example: `DOCKER_FINANCE_CONTAINER_CMD=finance.bash`
---
> DOCKER_FINANCE_CONTAINER_CONF > DOCKER_FINANCE_CONTAINER_CONF
The container's configuration path (bind-mounted to client's (host's) configuration path). 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` - Example: `DOCKER_FINANCE_CONTAINER_CONF=/home/${USER}/.config/docker-finance.d`
---
> DOCKER_FINANCE_CONTAINER_EDITOR > DOCKER_FINANCE_CONTAINER_EDITOR
The container's default text editor. The container's default text editor.
- Example: `DOCKER_FINANCE_CONTAINER_EDITOR=vim` - Example: `DOCKER_FINANCE_CONTAINER_EDITOR=vim`
---
> DOCKER_FINANCE_CONTAINER_FLOW > DOCKER_FINANCE_CONTAINER_FLOW
The container's hledger-flow path from the container's perspective. The container's hledger-flow path from the container's perspective.
@@ -457,7 +478,7 @@ This path is bind-mounted to the client's (host's) hledger-flow path.
- Example: `DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/hledger-flow` - Example: `DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/hledger-flow`
---
> DOCKER_FINANCE_CONTAINER_REPO > DOCKER_FINANCE_CONTAINER_REPO
The container's `docker-finance` code repository path (as viewed from the container). The container's `docker-finance` code repository path (as viewed from the container).
@@ -466,62 +487,62 @@ This path is bind-mounted to the client's (host's) `docker-finance/container` pa
- Example: `DOCKER_FINANCE_CONTAINER_REPO=/home/${USER}/docker-finance` - Example: `DOCKER_FINANCE_CONTAINER_REPO=/home/${USER}/docker-finance`
---
> DOCKER_FINANCE_CONTAINER_SHARED > DOCKER_FINANCE_CONTAINER_SHARED
The container's `share.d` path, bind-mounted to client's (host's) `share.d` path. 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` - Example: `DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/share.d`
---
> DOCKER_FINANCE_CPUS > DOCKER_FINANCE_CPUS
Docker daemon/container setting: number of CPUs to use. Docker daemon/container setting: number of CPUs to use.
- Example: `DOCKER_FINANCE_CPUS=2` - Example: `DOCKER_FINANCE_CPUS=2`
---
> DOCKER_FINANCE_DEBUG > DOCKER_FINANCE_DEBUG
Enable/disable debugging code paths (e.g., debug logging) Enable/disable debugging code paths (e.g., debug logging)
- Example: `DOCKER_FINANCE_DEBUG=true` - Example: `DOCKER_FINANCE_DEBUG=true`
---
> DOCKER_FINANCE_PORT_HLEDGER > DOCKER_FINANCE_PORT_HLEDGER
`hledger-web` client-side (host) port `hledger-web` client-side (host) port
- Example: `DOCKER_FINANCE_PORT_HLEDGER=5000` - Example: `DOCKER_FINANCE_PORT_HLEDGER=5000`
---
> DOCKER_FINANCE_PORT_ROOT > DOCKER_FINANCE_PORT_ROOT
`root` client-side (host) port for web interface `root` client-side (host) port for web interface
- Example: `DOCKER_FINANCE_PORT_ROOT=8080` - Example: `DOCKER_FINANCE_PORT_ROOT=8080`
---
> DOCKER_FINANCE_MEMORY > DOCKER_FINANCE_MEMORY
`docker-finance` container memory limit (see Docker documentation). `docker-finance` container memory limit (see Docker documentation).
- Example: `5G` - Example: `5G`
---
> DOCKER_FINANCE_GID > DOCKER_FINANCE_GID
Group ID for bind mount. **MUST** have write permissions to rw bind-mounts. Group ID for bind mount. **MUST** have write permissions to rw bind-mounts.
- Example: `DOCKER_FINANCE_GID=998` - Example: `DOCKER_FINANCE_GID=998`
---
> DOCKER_FINANCE_UID > DOCKER_FINANCE_UID
User ID for bind mount. **MUST** have write permissions to rw bind-mounts. User ID for bind mount. **MUST** have write permissions to rw bind-mounts.
- Example: `DOCKER_FINANCE_UID=1001` - Example: `DOCKER_FINANCE_UID=1001`
---
> DOCKER_FINANCE_USER > DOCKER_FINANCE_USER
`docker-finance` container user. `docker-finance` container user.
@@ -534,6 +555,19 @@ User **MUST** have write permissions to rw bind-mounts.
--- ---
#### 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](client/docker-finance.d/client/Dockerfiles)
After `gen` is complete, you can edit this file with the client (host) command: `docker-finance edit type=build` (see [Client (Host) Command Format](#client-host-command-format)).
---
#### Client/Container Superscript #### Client/Container Superscript
The client/container shell script (Superscript) is a bind-mounted (by directory) script that: The client/container shell script (Superscript) is a bind-mounted (by directory) script that:
@@ -546,7 +580,9 @@ See the in-file comments for further documentation:
- [superscript.bash.in](client/docker-finance.d/container/shell/superscript.bash.in) - [superscript.bash.in](client/docker-finance.d/container/shell/superscript.bash.in)
> Note: as described in [Client (host) command format](#client-host-command-format), to edit this file, issue the client (host) command: `docker-finance edit type=shell` After `gen` is complete, you can edit this file with the client (host) command: `docker-finance edit type=shell` (see [Client (Host) Command Format](#client-host-command-format)).
---
#### Container Configurations #### Container Configurations
@@ -562,6 +598,8 @@ See the in-file comments for further documentation:
- [subprofile.bash.in](client/docker-finance.d/container/shell/subprofile.bash.in) - [subprofile.bash.in](client/docker-finance.d/container/shell/subprofile.bash.in)
After `gen` is complete, from within the container, you can edit this file with: `finance profile/subprofile edit type=shell` (see [Container Command Format](#container-command-format)).
##### *Fetch* ##### *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. 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.
@@ -570,6 +608,8 @@ See the in-file comments for further documentation:
- [fetch.yaml.in](client/docker-finance.d/container/fetch/fetch.yaml.in) - [fetch.yaml.in](client/docker-finance.d/container/fetch/fetch.yaml.in)
After `gen` is complete, from within the container, you can edit this file with: `finance profile/subprofile edit type=fetch` (see [Container Command Format](#container-command-format)).
##### *Meta* ##### *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)](#meta-w-root-c-analysis). 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)](#meta-w-root-c-analysis).
@@ -578,6 +618,8 @@ See the in-file comments for further documentation:
- [meta.csv.in](client/docker-finance.d/container/meta/meta.csv.in) - [meta.csv.in](client/docker-finance.d/container/meta/meta.csv.in)
After `gen` is complete, from within the container, you can edit this file with: `finance profile/subprofile edit type=meta` (see [Container Command Format](#container-command-format)).
## How do I use it? ## How do I use it?
### Mostly-Unified CLI ### Mostly-Unified CLI
@@ -650,33 +692,35 @@ Where:
- `<command>` is the command to pass to `finance.bash` - `<command>` is the command to pass to `finance.bash`
- `[args]` are the (optional) arguments to pass to `<command>` - `[args]` are the (optional) arguments to pass to `<command>`
> Note: by default, the finance command can be called by either `finance.bash` or `finance`. By default, `finance.bash` is aliased to `finance` (so, either can be used).
For a complete list of commands and usage help: For a complete list of commands (no `<profile/subprofile>` needed):
```bash ```bash
finance help finance help
``` ```
You can also view the help usage of, for example, the `fetch` command (notice the need for `<profile/subprofile>`): You can also view the help usage of, for example, the `fetch` command (notice the need for `<profile/subprofile>`).
Assuming `<profile/subprofile>` is `testprofile/testuser`:
```bash ```bash
finance testprofile/testuser fetch help finance testprofile/testuser fetch help
``` ```
> Note: the `finance` alias is named to avoid confusion with the client (host) command `docker-finance` - but you can still use the alias `docker-finance` *within* the container in place of all `finance` commands.
Or, use a subprofile alias, as described in [Subprofile](#subprofile): Or, use a subprofile alias, as described in [Subprofile](#subprofile):
```bash ```bash
testuser_fetch help testuser_fetch help
``` ```
> Note: the `finance` alias is named to avoid confusion with the client (host) command `docker-finance`, but you can still use the alias `docker-finance` *within* the container in place of all `finance` commands.
### Flow Layout ### Flow Layout
A primary read through of [hledger](https://hledger.org) and [hledger-flow](https://github.com/apauley/hledger-flow/blob/master/README.org) documentation should bring you up to speed on the essentials. A primary read through of [hledger](https://hledger.org) and [hledger-flow](https://github.com/apauley/hledger-flow/blob/master/README.org) documentation should bring you up to speed on the essentials.
As for `docker-finance` specifics, create a test profile during [Environment Generation](#environment-generation) to see what your flow's layout should look like. As for `docker-finance` specifics, you can create a *test profile* during [Environment Generation](#environment-generation) to see what your flow's layout should look like.
> Note: be sure to select 'y' when asked if this will be a development profile, and then go on to create account(s). > Note: be sure to select 'y' when asked if this will be a development profile, and then go on to create account(s).
Once inside the container, assuming you created a profile named `testprofile` and subprofile named `testuser`, issue the following commands: Once inside the container, assuming you created a profile named `testprofile` and subprofile named `testuser`, issue the following commands:
@@ -684,7 +728,9 @@ Once inside the container, assuming you created a profile named `testprofile` an
```bash ```bash
finance testprofile/testuser fetch all=price year=all && finance testprofile/testuser import year=2018 finance testprofile/testuser fetch all=price year=all && finance testprofile/testuser import year=2018
``` ```
> Note: you **MUST** import from `2018` as there are mockup accounts that begin from that year > Note: for this *test profile* with developer mockups, you **MUST** import from `2018` as there are accounts that begin from that year
After experimenting with a *test profile*, you can re-run `gen` again to create your own normal profile.
--- ---
@@ -714,8 +760,8 @@ Peeking inside `${DOCKER_FINANCE_CONTAINER_FLOW}/profiles/profile/subprofile`, y
Regarding any profile you create: Regarding any profile you create:
- For manual CSV downloads, place you CSV file into your `${DOCKER_FINANCE_CONTAINER_FLOW}/profiles/profile/subprofile/import/subprofile/account/subaccount/1-in/year` directory - replacing `year` with the year of data that the file/data represents (see `import help` for details). - For manual CSV downloads, place you CSV file into your `${DOCKER_FINANCE_CONTAINER_FLOW}/profiles/profile/subprofile/import/subprofile/account/subaccount/1-in/year` directory (replacing `year` with the year of data that the file/data represents). See `import help` for details.
- When you want to edit custom settings for an account or a subaccount, use the `edit` command (see `edit help` for details). - When you want to edit custom settings for an account or a subaccount, use the `edit` command. See `edit help` for details.
- Your `hledger-flow` will contain a symlink called `src` which links to all the internal mechanics that process your data. **Do not delete this link**. - Your `hledger-flow` will contain a symlink called `src` which links to all the internal mechanics that process your data. **Do not delete this link**.
### Caveats & Oddities ### Caveats & Oddities
@@ -764,32 +810,32 @@ Your input is valuable and appreciated. Come, make this project your own!
> This pool is reserved for the `docker-finance` ecosystem (developers & operating costs). > This pool is reserved for the `docker-finance` ecosystem (developers & operating costs).
##### Cryptocurrency ##### *Cryptocurrency*
[Donate with Coinbase Commerce](https://commerce.coinbase.com/checkout/8831f2a9-1797-4aff-8cc3-bdbf97136a97) [Donate with Coinbase Commerce](https://commerce.coinbase.com/checkout/8831f2a9-1797-4aff-8cc3-bdbf97136a97)
[<img src=".img/donation/coinbase-commerce.png" width="25%" height="25%" />](https://commerce.coinbase.com/checkout/8831f2a9-1797-4aff-8cc3-bdbf97136a97 "Donate with Coinbase Commerce") [<img src=".img/donation/coinbase-commerce.png" width="25%" height="25%" />](https://commerce.coinbase.com/checkout/8831f2a9-1797-4aff-8cc3-bdbf97136a97 "Donate with Coinbase Commerce")
##### Legacy ##### *Legacy*
[Donate with PayPal](https://www.paypal.com/donate/?hosted_button_id=2RESHZY8U37EJ) [Donate with PayPal](https://www.paypal.com/donate/?hosted_button_id=2RESHZY8U37EJ)
[<img src=".img/donation/paypal-business.png" width="25%" height="25%" />](https://www.paypal.com/donate/?hosted_button_id=2RESHZY8U37EJ "Donate with PayPal") [<img src=".img/donation/paypal-business.png" width="25%" height="25%" />](https://www.paypal.com/donate/?hosted_button_id=2RESHZY8U37EJ "Donate with PayPal")
##### Alternative ##### *Alternative*
For alternative donation methods, including your crypto/token of choice, please open a request in the [issue tracker](https://gitea.com/EvergreenCrypto/docker-finance/issues) or reach out to [Evergreen Crypto LLC](#evergreen-crypto-llc). For alternative donation methods, including your crypto/token of choice, please open a request in the [issue tracker](https://gitea.com/EvergreenCrypto/docker-finance/issues) or reach out to [Evergreen Crypto LLC](#evergreen-crypto-llc).
--- ---
##### Dependencies ##### *Dependencies*
To donate to the wonderful projects that `docker-finance` gratefully depends upon, please donate to them directly: To donate to the wonderful projects that `docker-finance` gratefully depends upon, please donate to them directly:
- [Docker](https://www.docker.com/blog/get-involved-with-docker/)
- [hledger](https://hledger.org/sponsor.html) - [hledger](https://hledger.org/sponsor.html)
- [hledger-flow](https://github.com/apauley/hledger-flow) - [hledger-flow](https://github.com/apauley/hledger-flow)
- [ROOT.cern](https://root.cern/contribute/) - [ROOT.cern](https://root.cern/contribute/)
- [Docker](https://www.docker.com/blog/get-involved-with-docker/)
For other dependencies, please see their individual contributing guidelines. For other dependencies, please see their individual contributing guidelines.
@@ -802,21 +848,22 @@ Additionally, when developing with the [`docker-finance` image](#image-docker-fi
#### Pull Request #### Pull Request
The following assumes that the command `docker-finance_dev-tools` has been properly aliased, per `docker-finance help`. The following assumes that the command `dev-tools` has been properly aliased, per `docker-finance help`.
Before sending a pull request: Before sending a pull request:
1. If you created a new file, please run `docker-finance_dev-tools license file=/path/to/new/file.ext` and update the copyright date and author. 1. If you created a new file, please run `dev-tools license file=/path/to/new/file.ext` and update the copyright date and author.
2. For any work that utilizes Bash/C++/PHP, please run the linter for your respective language (e.g., `docker-finance_dev-tools linter type=bash`). 2. For any work that utilizes Bash/C++/PHP, please run the linter for your respective language (e.g., `dev-tools linter type=bash`).
- See `docker-finance_dev-tools linter help` for details. - See `dev-tools linter help` for details.
3. As for style guidelines, these are recommended: 3. As for style guidelines, these are recommended:
- [Bash](https://google.github.io/styleguide/shellguide.html) - [Bash](https://google.github.io/styleguide/shellguide.html)
- [C++](https://google.github.io/styleguide/cppguide.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) - [PHP](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/ruleSets/PhpCsFixer.rst)
4. If you can, please document the code in Doxygen style where applicable and run `docker-finance_dev-tools doxygen gen` to see your code documentation. 4. If you can, please document the code in Doxygen style where applicable and run `dev-tools doxygen gen` to see your code documentation.
#### Notes #### 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](#mostly-unified-cli), to use a developer version of the `finance` image (not a `dev-tools` image), simply build and tag a new `finance` image with `dev` (or whatever you see fit), and reset the `docker-finance` alias at your discretion. - As described in [Mostly-Unified CLI](#mostly-unified-cli), to use a developer version of the `finance` image (not a `dev-tools` image), simply build and tag a new `finance` image with `dev` (or whatever you see fit), and reset the `docker-finance` alias at your discretion.
- Run `DOCKER_FINANCE_DEBUG=true docker-finance <cmd> [args]` to debug *before* the [Client (Host) Configuration File](#client-host-configuration) file is read. - Run `DOCKER_FINANCE_DEBUG=true docker-finance <cmd> [args]` to debug *before* the [Client (Host) Configuration File](#client-host-configuration) file is read.
- The `.C` files you see in the repository are ROOT.cern macro files, not C-language files. - The `.C` files you see in the repository are ROOT.cern macro files, not C-language files.