Aaron Fiore
cc4994f6e1
|
||
---|---|---|
.img | ||
client | ||
container | ||
.gitignore | ||
docker-finance.dox | ||
LICENSE.md | ||
README.md |
docker-finance
Modern accounting for the power-user | Crypto, banking, tax prep, meta analysis & more!
- What does it do?
- What is supported?
- How do I get started?
- How do I use it?
- How do I contribute?
- How do I connect?
- Where is the legalese?
What does it do?
Overview
docker-finance
empowers you with 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.
Highlights
- Highly granular plaintext accounting
- Visualize your metadata with a high-powered physics framework
- Privacy-aware instance generates (and stores) your visualizations locally
- Interactive C++ interpreter allows complex analysis with efficiency
- Report generation & tax preparation
- Cryptocurrency income from interest and staking
- Cryptocurrency spending and network fees
- Capital gains/losses across all accounts
- Income statements, balance sheets and more
- Automated data procurement & aggregation into meaningful journal entries
- Use network APIs for CSV data or drop-in your institutions' CSVs
- Import all CSV data with a single command to create a unified journal
- Enjoy using your client's (host's)
crontab
for the container's suite of commands
- Unique & customizable environments for your individual needs
- Versatile: create unlimited profiles for any number of groups and users
- Flexible: while automation is useful, so is the manual entry framework
- Private: all of your accounts are under your control; not a 3rd party
- Secure: all financial activity is managed within a Docker container
- Developer-friendly environment that keeps you in the zone
- See the Development section for details
Screenshots
Client (Host)
The docker in docker-finance
.
image: docker-finance
image: dev-tools
Container
The finance in docker-finance
.
Fetch
Ledger (command)
Meta (w/ ROOT C++ analysis)
ROOT (CLI w/ C++ API)
Taxes
Reports
Help (suite of commands)
What is supported?
Plaintext accounting gives you the power to manage any number of assets or accounts.
However, for accounts that require fetch/import functionality, only the following are supported:
CeFi
Regularly maintained
Available but requires community maintenance
Available but no longer maintained
- BlockFi (bankrupt)
- Celsius Network (bankrupt)
DeFi
Blockchain explorers / Ecosystems
Supported blockchains (independent of wallet type):
- Algorand (powered by AlgoNode.io)
- Cardano
- Ethereum-based
- Arbitrum
- Ethereum (powered by Etherscan.io APIs)
- Optimism
- Polygon (powered by PolygonScan APIs)
- Tezos (powered by TzKT API)
Self-hosting
Wallets
Software
Hardware
Web
TradFi
Regularly maintained
Requires community maintenance
Prices
- Cryptocurrency
- Traditional markets
How do I get started?
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
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).
-
Install dependencies (most recent stable versions):
- Docker with post-install configuration
- GNU Bash 5.2+
- If you don't have
bash
installed by default (or ifbash
is not your default shell), setupbash
per your system's documentation
- If you don't have
- Git, for step 3 (strongly advised):
git
should be available via your package manager (e.g.,apt
,pacman
, etc.).
-
Open a
bash
shell, if you haven't already done so. -
Copy/paste the following into your shell (one-time repository clone and client preparation):
bashrc=~/.bashrc aliases=~/.bash_aliases if [[ -f "$bashrc" && ! -f "$aliases" ]]; then if ! grep -E "(^\. ${aliases}|^source ${aliases})" "$bashrc" 1>/dev/null; then aliases="$bashrc" fi fi if git clone https://gitea.com/EvergreenCrypto/docker-finance; then if ! grep -E "^alias docker-finance=" "$aliases" 1>/dev/null; then echo "alias docker-finance='$(pwd)/docker-finance/client/docker.bash archlinux/$(whoami):latest'" >>"$aliases" source "$aliases" fi fi
-
Verify your repository (recommended):
if pushd docker-finance/ 1>/dev/null; then gpg --keyserver hkp://keyserver2.gnupg.org --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
-
Generate client/container environment (see Environment Generation for details):
docker-finance gen
-
Build the image and bring up container:
docker-finance build && docker-finance up
-
You're inside! See How do I use it? for next steps.
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.
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 and the 2nd file is a joint Client/Container Superscript. Think of this superscript as the glue that binds the client/container scopes.
You'll create these files (and more) when running docker-finance gen
, as seen below.
Client generation
Client-side environment found, backup then generate new one?
Generates the client (host) configuration file. See the Client (Host) Configuration File section 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, rundocker-finance edit type=env
Container generation
Container generation comes after (and must come after) client environment generation.
The container environment contains the bulk of configurations for everything you'll need while inside docker-finance
.
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.
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.
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 (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'.
See Superscript for details.
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).
Generate (or update) subprofile's shell script?
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.
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 for details.
Generate (or update) subprofile's financial metadata?
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 for details.
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?.
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
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
The client (host) configuration file:
- is located in the
${DOCKER_FINANCE_CLIENT_CONF}/client/env/
directory, with subdirectory format ofkernel-machine/platform/tag
- format consists of
username@hostname
whereusername
is your host username andhostname
is your machine's hostname
- format consists of
- 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 anddocker-finance
- default template variables can be found in gen.bash, as described below
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) hledger-flow path. Parent directory for all profiles.
- Example:
DOCKER_FINANCE_CLIENT_FLOW=/net/nfs4/hledger-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_CONTAINER_CMD
The container's finance
command (useful for experimental implementations).
Default: finance.bash
(internally aliased to finance
)
- 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 hledger-flow path from the container's perspective.
This path is bind-mounted to the client's (host's) hledger-flow path.
- Example:
DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/hledger-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_CPUS
Docker daemon/container setting: number of CPUs to use.
- Example:
DOCKER_FINANCE_CPUS=2
DOCKER_FINANCE_DEBUG
Enable/disable debugging code paths (e.g., debug logging)
- Example:
DOCKER_FINANCE_DEBUG=true
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
DOCKER_FINANCE_VERSION
Expected docker-finance
configuration version.
Don't manually change this unless you were born with the UNIX Bible in your hand.
- Example:
DOCKER_FINANCE_VERSION=1.0.0
Client/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 Subprofile scripts
- 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:
Note: as described in Client (host) command format, to edit this file, issue the client (host) command:
docker-finance edit type=shell
Container Configurations
These configurations are confined solely to the container.
Subprofile
The Subprofile script 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:
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:
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:
How do I use it?
Mostly-Unified CLI
You'll only need to call two different scripts throughout your time using docker-finance
:
- The client script which handles the client-side system:
docker.bash
- The container script which handles the container-side system:
finance.bash
These two scripts can be rationalized by the following format:
<script> <super/sub> <command> [args]
Note: for your convenience, command arguments [args] can be arranged in any order.
For example, these Screenshots describe a setup with mockup data where the client (host) user named personal
, along with container $DOCKER_FINANCE_USER
named personal
, engage in client/container activity. The container profile named testprofile
and its subprofile named testuser
can be described as <super/sub>
portion of the format (testprofile/testuser
).
Note: mockup data can be found in the
mockup
directories within this repository.
Client (Host) Command Format
The client (host) command format consists of:
docker.bash <platform/username:tag> <command> [args]
Where:
docker.bash
is located in${DOCKER_FINANCE_CLIENT_REPO}/client
<platform/username:tag>
platform
is the image platform (archlinux, ubuntu)username
is the client (host) username with read/write permissions to the container (see Configuration Files)tag
is a custom tag you can use to delineate any number of images that you wish you create (latest
,dev
, etc.)
<command>
is the command to pass todocker.bash
[args]
are the (optional) arguments to pass to<command>
For a complete list of commands and usage help:
${DOCKER_FINANCE_CLIENT_REPO}/client/docker.bash archlinux/$(whoami):latest help
Or, if the Installation alias was properly created:
docker-finance help
You can also view the help usage of, for example, the edit
command:
docker-finance edit help
Container Command Format
The container command format consists of:
finance.bash <profile/subprofile> <command> [args]
Where:
finance.bash
is located in${DOCKER_FINANCE_CLIENT_REPO}/container
<profile/subprofile>
profile
is the profile, as defined during Environment Generationsubprofile
is the subprofile (user), as defined during Environment Generation
<command>
is the command to pass tofinance.bash
[args]
are the (optional) arguments to pass to<command>
Note: by default, the finance command can be called by either
finance.bash
orfinance
.
For a complete list of commands and usage help:
finance help
You can also view the help usage of, for example, the fetch
command (notice the need for <profile/subprofile>
):
finance testprofile/testuser fetch help
Note: the
finance
alias is named to avoid confusion with the client (host) commanddocker-finance
- but you can still use the aliasdocker-finance
within the container in place of allfinance
commands.
Or, use a subprofile alias, as described in Subprofile:
testuser_fetch help
Flow Layout
A primary read through of hledger and hledger-flow documentation should bring you up to speed on the essentials.
As for docker-finance
specifics, create a test profile during 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).
Once inside the container, assuming you created a profile named testprofile
and subprofile named testuser
, issue the following commands:
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
All profiles/subprofiles are installed into the parent directory ${DOCKER_FINANCE_CONTAINER_FLOW}/profiles
.
Peeking inside ${DOCKER_FINANCE_CONTAINER_FLOW}/profiles/profile/subprofile
, you'll see the following:
-
all-years.journal
anddirectives.journal
- These top-level journals are generated by
hledger-flow
. Ignore these and use theedit
command for journal editing.
- These top-level journals are generated by
-
docker-finance.d
- Location of all
docker-finance
configuration files (seeedit help
for details).
- Location of all
-
import
- Location of all CSV data and real journals. This is where you'll place CSV files and custom account/subaccount changes (see
edit help
for details).
- Location of all CSV data and real journals. This is where you'll place CSV files and custom account/subaccount changes (see
-
prices
- Location of all market price data, by year, as acquired by
fetch price
(seefetch help
for details).
- Location of all market price data, by year, as acquired by
-
reports
- Location of all generated reports, by year, as generated by
reports
(seereports help
for details).
- Location of all generated reports, by year, as generated by
-
taxes
- Location of all generated taxes, by year, as generated by
taxes
(seetaxes help
for details).
- Location of all generated taxes, by year, as generated by
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 - replacingyear
with the year of data that the file/data represents (seeimport help
for details). - When you want to edit custom settings for an account or a subaccount, use the
edit
command (seeedit help
for details). - Your
hledger-flow
will contain a symlink calledsrc
which links to all the internal mechanics that process your data. Do not delete this link.
Caveats & Oddities
Flow Layout
Prices
Before you try to infer market prices, be sure to fetch prices before you do your first import (or first import of the year). If you do not fetch, the prices journal will not be included within the import and, if you have a previous year of prices, you will unwittingly infer against that previous year instead of your expected year!
Accounts: Trezor
In the "Trezor Suite" app, change your wallet name to your subaccount(s). For example, to delineate between your Trezor One from several Trezor T devices, and to delineate between their separate wallets within every device, follow these steps:
Example, using your #2 Trezor T device and one of its BTC "storage" wallets:
- Change wallet name in app to
t-2:storage-1
as it's your Trezor T device #2, 1st bitcoin wallet namedstorage-1
(versus your 2nd bitcoin wallet namedstorage-2
, etc.) - Export the CSV file to the appropriate directory. It will be in the format of
t_2_storage_1_20230629T230013.csv
(timestamp will be different) - Rename the file to
t-2:storage-1_BTC.csv
(be sure to append the currency ticker to the file. So,_BTC
if bitcoin or_LTC
if litecoin, etc).
Note: see Trezor
mockup
data within this repository, for a working example.
docker-finance
relies on Amount unit
within the file for the actual symbol/currency so, this file naming convention serves at least two purposes:
- This allows you to maintain device continuity by reusing wallet names for different currencies.
- This allows you to export, in the future, to the correct file from the associated hardware wallet because each hardware wallet exports its own unique CSV.
Taxes
- If you have a wallets designated for
SPEND
ing/GIFT
ing orINCOME
, you can use custom rules to mark all outgoing/incoming transactions as such (ex., using tagstaxed_as:SPEND
/taxed_as:GIFT
/taxed_as:INCOME
/etc.). See implementation for details. - WARNING: all
GIFTIN
cost-basis must be manually entered from the correspondingGIFT
results/calculations (as gifted from another).- For blockchain-related transactions, you can easily add cost-basis of a gift received (
GIFTIN
) by TXID in your custom rules- Example: despite Electrum providing
fiat_value
, you'll need to manually enter in your custom rules the correctGIFT
value (if divergent)
- Example: despite Electrum providing
- For blockchain-related transactions, you can easily add cost-basis of a gift received (
How do I contribute?
Donate
Time
Your input is valuable and appreciated. Come, make this project your own!
Funding
→ 100% of your donations go to the docker-finance
funding pool. ←
This pool is reserved for the
docker-finance
ecosystem (developers & operating costs).
Cryptocurrency
Legacy
Alternative
For alternative donation methods, including your crypto/token of choice, please open a request in the issue tracker or reach out to Evergreen Crypto LLC.
Dependencies
To donate to the wonderful projects that docker-finance
gratefully depends upon, please donate to them directly:
For other dependencies, please see their individual contributing guidelines.
Development
You'll greatly benefit from building the dev-tools
image, as seen in docker-finance help
.
Additionally, when developing with the docker-finance
image, please test your work with mockups as described in Environment Generation and Flow Layout.
Note: mockup CSVs will intentionally have multiple years within in a
1-in/year
directory in order to test for year parsing.
Pull Request
The following assumes that the command docker-finance_dev-tools
has been properly aliased, per docker-finance help
.
Before sending a pull request:
- 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. - 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
).- See
docker-finance_dev-tools linter help
for details.
- See
- As for style guidelines, these are recommended:
- 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.
Notes
- As described in Mostly-Unified CLI, to use a developer version of the
finance
image (not adev-tools
image), simply build and tag a newfinance
image withdev
(or whatever you see fit), and reset thedocker-finance
alias at your discretion. - Run
DOCKER_FINANCE_DEBUG=true docker-finance <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.
How do I connect?
#docker-finance:matrix.org
Join the docker-finance
Matrix community.
Evergreen Crypto LLC
- For general communications, please visit the contact section of the website.
- For security-related concerns, please contact the Founder directly with PGP encrypted email.
Where is the legalese?
License and Disclaimer
docker-finance
:
- is not a Docker product
- is not a Docker trademark
- is not an endorsement of what is supported
- is not a tax-advising product (consult your tax adviser)
- is not a financial-advising product (consult your financial adviser)
- is licensed under the GPLv3 but...
- I highly suggest that you consider refraining from the use of AI modeling against
docker-finance
and also refrain from mirroring (or archiving)docker-finance
on GitHub, GitLab or any other service that uses AI against its hosted code, until the court make its final ruling on litigation against GitHub/Microsoft and OpenAI (and after any possible appeal).
- I highly suggest that you consider refraining from the use of AI modeling against