Compare commits
1 Commits
master
...
db76fbbfc2
| Author | SHA1 | Date | |
|---|---|---|---|
db76fbbfc2
|
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -51,7 +51,24 @@ When developing non-code documentation, please work with the [dfi-docs](https://
|
||||
|
||||
#### Plugins
|
||||
|
||||
Primary plugin documentation can be found [here](How-do-I-use-it.md#plugins). Technically speaking, you can write custom plugins and never need to merge with the repository but if you feel that the plugin(s) would be beneficial to the public, add testcases and send everything with a [pull request](#pull-request).
|
||||
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.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/plugins) and [`container/plugins`](https://gitea.evergreencrypto.co/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
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
|
||||
[//]: # (docker-finance | modern accounting for the power-user)
|
||||
[//]: # ()
|
||||
[//]: # (Copyright [C] 2021-2026 Aaron Fiore [Founder, Evergreen Crypto LLC])
|
||||
[//]: # (Copyright [C] 2021-2025 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)
|
||||
@@ -25,15 +25,13 @@
|
||||
|
||||
## 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 financial world containerized (and with all the benefits of containerization).
|
||||
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
|
||||
|
||||
`dfi` *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).
|
||||
|
||||
> Watch this [example demo](../assets/examples/webm/client-install.webm) for a quick showcase of the below instructions (using a development test profile)
|
||||
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:
|
||||
|
||||
@@ -58,13 +56,13 @@ To get started, you'll only need a modern Linux client (host) with a working Doc
|
||||
3. Prepare your base path and repository:
|
||||
|
||||
- Before proceeding, change your directory to a *persistent base path* that you intend to keep; as this will be the default base path for all data going forward
|
||||
* The absolute path of your current working directory + `./docker-finance` will be the default base path to house all data
|
||||
* By default, `./docker-finance` in your current working directory will be the default base path to house all data
|
||||
* If you'd like, you *can* change the base path later during [Client Generation](#client-generation)
|
||||
|
||||
```bash
|
||||
# NOTE: you can change the domain to `gitea.com`, as this repository is also mirrored there
|
||||
if hash git &>/dev/null; then
|
||||
if ! git clone --depth=1 https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance docker-finance/repo -b v1.3.0; then
|
||||
if ! git clone --depth=1 https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance docker-finance/repo -b v1.2.0; then
|
||||
echo "FATAL: docker-finance repo not cloned" >&2
|
||||
fi
|
||||
else
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
|
||||
[//]: # (docker-finance | modern accounting for the power-user)
|
||||
[//]: # ()
|
||||
[//]: # (Copyright [C] 2021-2026 Aaron Fiore [Founder, Evergreen Crypto LLC])
|
||||
[//]: # (Copyright [C] 2021-2025 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)
|
||||
@@ -21,8 +21,6 @@
|
||||
- **[How do I use it?](#how-do-i-use-it)**
|
||||
* [Mostly-Unified CLI](#mostly-unified-cli)
|
||||
* [Flow Layout](#flow-layout)
|
||||
* [Plugins](#plugins)
|
||||
* [FAQ](#faq)
|
||||
* [Caveats & Oddities](#caveats--oddities)
|
||||
|
||||
## How do I use it?
|
||||
@@ -169,210 +167,17 @@ All `times` related files will reside in `${DOCKER_FINANCE_CONTAINER_FLOW}/times
|
||||
|
||||
See the container `times help` command for details.
|
||||
|
||||
### Plugins
|
||||
|
||||
Plugins (pluggables) allow you to leverage `dfi` client/container APIs, libraries and environments to meet your unique needs.
|
||||
|
||||
Checkout this two-part client/container set of [Bitcoin plugins](#plugins-bitcoin) to see how all APIs/libraries/environments can work together in unison.
|
||||
|
||||
For more information and other examples, see some of the various existing plugins (pluggables) and respective help usage, i.e.;
|
||||
|
||||
- Client-side (host): `dfi <platform/user:tag> plugins help`
|
||||
- Container-side: `dfi <profile/subprofile> plugins help`
|
||||
- Within `root` interpreter: `dfi::help()`
|
||||
|
||||
#### Plugins: Layout
|
||||
|
||||
Plugins are categorical:
|
||||
|
||||
1. Repository (`repo`) plugins
|
||||
- These plugins remain within the repository and will require a pull request for any changes to be made to them.
|
||||
|
||||
2. End-user (`custom`) plugins
|
||||
- These plugins remain on your client (host) and are bind-mounted to your container; allowing you to drop-in any code that you write while keeping them local and private.
|
||||
|
||||
Within these categories are subcategories where plugins exist either client-side (host) or container-side; meaning, they rely upon (or operate within) their respective client/container APIs/libraries/environments:
|
||||
|
||||
1. `client` | *Tends to operate only client-side (host) but can also utilize a container*
|
||||
- `docker` | *Operates **only** from the `bash` shell*
|
||||
* Called client-side with `dfi <platform/user:tag> plugins`
|
||||
* Can be any language so long as:
|
||||
- The file is executable by the shell
|
||||
- The plugin reads the shell environment
|
||||
- The plugin initializes the respective library (`lib_docker`)
|
||||
2. `container` | *Operates **only** within the container*
|
||||
- `finance` | *Operates **only** from the `bash` shell*
|
||||
* Called container-side with `dfi <profile/subprofile> plugins`
|
||||
* Can be any language so long as:
|
||||
- The file is executable by the shell
|
||||
- The plugin reads the shell environment
|
||||
- The plugin initializes the respective library (`lib_finance`)
|
||||
- `root` | *Operates **only** within the `root` interpreter*
|
||||
* Called container-side by either two different ways:
|
||||
- Within a running `dfi <profile/subprofile> root` instance:
|
||||
* `dfi::plugin::load("repo/a_repo_plugin/plugin.cc")`
|
||||
* `dfi::plugin::load("custom/my_custom_plugin/plugin.cc")`
|
||||
- With the `dfi <profile/subprofile> root plugins` command
|
||||
* Use tab completion to see available plugins (pluggables)
|
||||
* Can only be languages supported by the interpreter (C/C++)
|
||||
|
||||
To mirror these categories, a client-side `custom` plugin directory layout is generated upon `dfi <platform/user:tag> gen`. This layout consists of:
|
||||
|
||||
1. `${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker`
|
||||
- This path remains client-side only (not bind-mounted)
|
||||
- This layout mirrors `repo` plugins [`client/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/plugins)
|
||||
2. `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/{finance,root}`
|
||||
- The container directory is bind-mounted to `DOCKER_FINANCE_CONTAINER_PLUGINS`
|
||||
- This layout mirrors `repo` plugins [`container/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/container/plugins)
|
||||
|
||||
**WARNING: don't change the above expected layout!** However, you can add subdirectories, e.g.;
|
||||
|
||||
- `${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker/my_docker_plugins/plugin.bash`
|
||||
- `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/finance/my_finance_plugins/plugin.bash`
|
||||
- `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/root/my_plugin/my_plugin.cc`
|
||||
* NOTE: `root` pluggable auto-(un)loading requires a parent directory as the callable namespace (and more)
|
||||
- See docs for details: `dfi dev-tools/${USER}:default doxygen gen`
|
||||
|
||||
#### Plugins: Bitcoin
|
||||
|
||||
`dfi`'s bitcoin plugin is a two-part client/container set of plugins that gives you direct access to bitcoin's libbitcoinkernel (and related headers/symbols).
|
||||
|
||||
The following demo assumes that you'll be using a fresh setup and that you've at least satisfied the required dependencies in [Installation](How-do-I-get-started.md#installation) (Docker Engine/Compose/Buildx, Bash, Git).
|
||||
|
||||
If you're a first-time user and/or developer who simply wants a quickstart, run the following before proceeding:
|
||||
|
||||
```bash
|
||||
git clone --depth=1 https://gitea.com/EvergreenCrypto/docker-finance docker-finance/repo
|
||||
./docker-finance/repo/client/install.bash && source ~/.bashrc
|
||||
dfi archlinux/${USER}:default gen all=all profile=testprofile/testuser confirm=no dev=on
|
||||
```
|
||||
|
||||
##### Plugins: Bitcoin: Client
|
||||
|
||||
Here, we prepare client-side dependencies and build everything needed for the container-side plugin:
|
||||
|
||||
<video src="../assets/examples/webm/client-plugins-bitcoin.webm" controls></video>
|
||||
|
||||
Shell 1:
|
||||
|
||||
```bash
|
||||
# NOTE: editing will only be required once (unless you `gen type=build` in the future)
|
||||
dfi archlinux/${USER}:default edit type=build
|
||||
dfi archlinux/${USER}:default build type=default
|
||||
```
|
||||
|
||||
Shell 2:
|
||||
|
||||
```bash
|
||||
dfi archlinux/${USER}:default up
|
||||
```
|
||||
|
||||
Shell 1:
|
||||
|
||||
```bash
|
||||
dfi archlinux/${USER}:default plugins repo/bitcoin.bash get
|
||||
dfi archlinux/${USER}:default plugins repo/bitcoin.bash build
|
||||
```
|
||||
|
||||
##### Plugins: Bitcoin: Container
|
||||
|
||||
Here, we see the multiple ways the container-side plugin can be loaded and also test its functionality:
|
||||
|
||||
<video src="../assets/examples/webm/container-root-plugins-bitcoin_cli.webm" controls></video>
|
||||
|
||||
Shell 2 (or open a new shell into container, as seen in the demo):
|
||||
|
||||
```bash
|
||||
dfi testprofile/testuser root
|
||||
```
|
||||
|
||||
Within `root` interpreter:
|
||||
|
||||
```cpp
|
||||
// NOTE:
|
||||
// - The demo shows `btck` tab completion (which can't be put here)
|
||||
// - semicolons are not needed, since the following is executed per line
|
||||
GetRandHash()
|
||||
dfi::plugin::load("repo/bitcoin/bitcoin.cc")
|
||||
GetRandHash()
|
||||
dfi::macro::load("repo/test/unit.C", "Random*")
|
||||
.quit
|
||||
```
|
||||
|
||||
Shell 2:
|
||||
|
||||
```bash
|
||||
BENCHMARK_FILTER="^Random" dfi testprofile/testuser root plugins/repo/bitcoin/bitcoin.cc 'dfi::macro::load(\"repo/test/benchmark.C\"); dfi::common::exit(0);'
|
||||
dfi testprofile/testuser root plugins/repo/bitcoin/bitcoin.cc 'dfi::macro::load(\"repo/web/server.C\")'
|
||||
```
|
||||
|
||||
##### Plugins: Bitcoin: Web browser
|
||||
|
||||
Here, we see a real-world visualization of what the container-side plugin can produce. In this example, with the plugin previously loaded (as seen above), we sample bitcoin's RNG:
|
||||
|
||||
<video src="../assets/examples/webm/container-root-plugins-bitcoin_web.webm" controls></video>
|
||||
|
||||
- Open browser to `http://127.0.0.1:8080`
|
||||
* Default port can be changed with client-side command: `dfi archlinux/${USER}:default edit type=env`
|
||||
- Click `rng_sample` -> Enter sample amount
|
||||
- Click `reload`
|
||||
|
||||
### FAQ
|
||||
|
||||
> Q. Are there two versions of the `dfi` script? Or a single script that gathers all functionality under various subcommands?
|
||||
|
||||
The `dfi` command has different functionality depending on its [context](#mostly-unified-cli). The client-side (host) command only operates client-side (but can also operate *on* a container) while the container-side `dfi` command only operates within the container.
|
||||
|
||||
This pairing is part of that "translucent" quality of the system where the "same" command behaves differently, depending on the context. It allows for a fluid transition between the dual worlds of the docker-finance system. A good visual example of how the two can work together can be seen in this [demo](#plugins-bitcoin).
|
||||
|
||||
> Q. Is this dual world of docker images essential to docker-finance? Could it work with just 1 docker image, or 0 images?
|
||||
|
||||
The "dual world" aspect only describes the client (host) and container system. Currently, there are 2 `finance` images ([only 1 is actively maintained (`archlinux`)](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/issues/239)) and 1 optional `dev-tools` (developer) image.
|
||||
|
||||
The client (host) is *not* an image: these terms only describe the supported host (currently Linux). You can run `dfi` on an Ubuntu host, a Debian host, an Arch Linux host etc. When you see `archlinux` in the documentation, that only describes what the `finance` image is based - *not* what the client (host) is.
|
||||
|
||||
As for 0 image, well that would defeat the purpose! :) And although I think the world ran fine before Docker existed, the benefits of Docker (at least in this case) far outweigh the cost of the overhead.
|
||||
|
||||
> Q. What's the essential need for docker here? Is it just a packaging/distribution choice?
|
||||
|
||||
`dfi` is an all-in-one accounting system; a privacy-aware, security-aware, modern-finance-aware accounting system; a system of operating within an operating system; a financial framework for power-users.
|
||||
|
||||
But why does `dfi` (docker-finance) exist? Perhaps it's easier to ask the following:
|
||||
|
||||
1. How can I manage my own accounting locally and privately, without the need for 3rd party hosting but also using features provided by 3rd parties?
|
||||
2. How can I use [hledger-suite](https://hub.docker.com/r/evergreencrypto/hledger-suite/) to account for transactions fetched by [ccxt](https://github.com/ccxt/ccxt/) then generate privacy-aware tax reports for a [cost-basis calculator](https://bitcoin.tax/) and perform local analysis using [root](https://root.cern/) while simultaneously tracking the [time](https://taskwarrior.org/) to then bill a client with a [custom billing invoice/email plugin](#plugins); all with a single command issued from the commandline to a single locally administered system?
|
||||
3. How can the previous question be applied to multiple client profiles who's accounting must be technologically, mathematically, financially and ethically separated; while also enjoying the benefits of this all-in-one system?
|
||||
4. How can the previous question's execution be generic enough and templated enough to work for all other `dfi` project end-users without every end-user needing to maintain their own dependencies, their own locations for all relevant data or even their own functional needs (e.g., "I don't need `root` but I need to `fetch` my data and use `hledger`") but also simultaneously allow them the flexibility to do so (should they choose)?
|
||||
5. How does one provide a baseline accounting system and [workflow](#flow-layout) for users to work with that also allows them the freedom and flexibility of Docker, while also allowing the API contracts required by the aforementioned dependencies to communicate with each other across multiple languages and environments, in order to produce useful data aggregation, bookkeeping and analysis?
|
||||
6. How does one stay in line with the spirit of file-based accounting for all of the aforementioned while also avoiding a traditional DBMS and the language/UI overhead that's usually involved?
|
||||
7. How does one manage the dependencies and upstream requirements of these many different languages and environments without putting that burden on an end-user other than them running a single `update` command?
|
||||
8. How does one do all of this without compiling any code? Or rather; no compiling outside of a JIT compiler or interpreter outside of a commonly used native Linux shell?
|
||||
9. How are all of the aforementioned dependencies contained within a single system, without needing to manage packages across multiple Linux distributions?
|
||||
10. How does one do all of this with only 2 runtime dependencies for the end-user? Meaning, end-users only need to concern themselves with having `bash` and `docker` installed on their client (host) in order to run?
|
||||
|
||||
I believe `dfi` (docker-finance) answers all of these questions; satisfies all of these requirements and more.
|
||||
|
||||
> Q. Why not just provide some Dockerfiles and compose files and be done with it?
|
||||
|
||||
The docker-finance system is not that simple, but that simplicity is offered to end-users. You can work with your own custom Dockerfile and docker-compose.yml while still working within the system: simply run the client-side `dfi` command with `edit type=build,compose`.
|
||||
|
||||
This style of extensibility allows you to add or remove what you need without needing to submit a pull request (or if your need is entirely personal/unique and shouldn't be applied to other `dfi` end-users).
|
||||
|
||||
> Q. Can I use my own custom container-side `dfi` implementation?
|
||||
|
||||
Yes! Simply edit your client-side (host) environment with `edit type=env` and update `DOCKER_FINANCE_CONTAINER_CMD` to point to your own command.
|
||||
|
||||
### Caveats & Oddities
|
||||
|
||||
#### Caveats & Oddities: Flow
|
||||
#### Flow Layout
|
||||
|
||||
Your `flow` directory will contain a symlink called `src` which links to code that processes your data. **Do not delete this symlink**.
|
||||
|
||||
##### Caveats & Oddities: Flow: Prices
|
||||
##### *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!**
|
||||
|
||||
##### Caveats & Oddities: Flow: Accounts: Trezor
|
||||
##### *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:
|
||||
|
||||
@@ -389,7 +194,7 @@ docker-finance relies on `Amount unit` within the file for the actual symbol/cur
|
||||
1. This allows you to maintain device continuity by reusing wallet names for different currencies.
|
||||
2. 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.
|
||||
|
||||
##### Caveats & Oddities: Flow: Taxes
|
||||
#### Taxes
|
||||
|
||||
- If you have a wallets designated for `SPEND`ing/`GIFT`ing or `INCOME`, you can use custom rules to mark all outgoing/incoming transactions as such (ex., using tags `taxed_as:SPEND`/`taxed_as:GIFT`/`taxed_as:INCOME`/etc.). See implementation for details.
|
||||
- **WARNING**: *all* `GIFTIN` cost-basis must be manually entered from the corresponding `GIFT` results/calculations (as gifted from another).
|
||||
|
||||
Reference in New Issue
Block a user