diff --git a/README.md b/README.md index 73d5c12..10af235 100644 --- a/README.md +++ b/README.md @@ -71,17 +71,19 @@ Cryptocurrencies & blockchain metadata are unified with legacy finance to create - 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](#fetch) - - 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 +- [Automated data procurement & aggregation into meaningful journals](#fetch) + - Use network APIs to [`fetch`](#fetch) account CSV data or market prices + - Manually drop-in your institutions' CSVs (for accounts w/out remote API) + - Import all journals with a single command to create a unified journal - Enjoy using your client's (host's) `crontab` for the [container's suite of commands](#help-suite-of-commands) - [Unique & customizable environments for your individual needs](#image-docker-finance) - 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 + - Anonymous: [Tor](https://www.torproject.org/) support is available for all [`fetch`](#fetch) functionality - [Developer-friendly environment that keeps you in the zone](#image-dev-tools) - - [Plugins](#plugins) support for maximum extensibility + - A [plugins](#plugins) framework allows for maximum extensibility - See the [Development](#development) section for details ### Screenshots @@ -376,7 +378,7 @@ Generates custom Dockerfile. Do as you wish; install your own container packages After the previous client environment is generated, the following will prepare the container environment (everything you'll need while inside `docker-finance`). -> *Generate (or update) container profile configs and/or accounts?* +> *Generate (or update) container flow (profiles, etc.)?* Although the container environment is a minimum requirement, here you'll have the option to continue generating or to backup a previous install. @@ -400,9 +402,13 @@ It should be noted that: 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). -> *Generate (or update) container hledger-flow configs and/or accounts?* +> *Generate (or update) hledger configuration file?* -Not limited to `hledger-flow` data, this option leads to generating *all* `docker-finance` journal data (and configurations). +If the container's version of hledger supports it, use this customizable configuration file. + +> *Generate (or update) container flow configs and/or accounts?* + +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.). > *Generate (or update) subprofile's shell script?* @@ -454,9 +460,9 @@ Client (host) configuration path. Parent directory for client configuration file > DOCKER_FINANCE_CLIENT_FLOW -Client (host) hledger-flow path. Parent directory for all profiles. +Client (host) finance-flow path. Parent directory for all profiles and end-user data. -- Example: `DOCKER_FINANCE_CLIENT_FLOW=/net/nfs4/hledger-flow` +- Example: `DOCKER_FINANCE_CLIENT_FLOW=/net/nfs4/finance-flow` > DOCKER_FINANCE_CLIENT_REPO @@ -511,11 +517,11 @@ The container's default text editor. > DOCKER_FINANCE_CONTAINER_FLOW -The container's hledger-flow path from the container's perspective. +The container's finance-flow path from the container's perspective. -This path is bind-mounted to the client's (host's) hledger-flow path. +This path is bind-mounted to the client's (host's) finance-flow path. -- Example: `DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/hledger-flow` +- Example: `DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/finance-flow` > DOCKER_FINANCE_CONTAINER_REPO @@ -775,14 +781,14 @@ finance testprofile/testuser fetch all=price year=all && finance testprofile/tes After experimenting with a *test profile*, you can re-run `gen` again to create your own normal profile. ---- +#### Profiles 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` and `directives.journal` - - These top-level journals are generated by `hledger-flow`. Ignore these and use the `edit` command for journal editing. + - These top-level journals are generated by `hledger-flow`. Ignore these and use the container `edit` command for all journal editing. - `docker-finance.d` - Location of all `docker-finance` configuration files (see `edit help` for details). @@ -799,18 +805,23 @@ Peeking inside `${DOCKER_FINANCE_CONTAINER_FLOW}/profiles/profile/subprofile`, y - `taxes` - Location of all generated taxes, by year, as generated by `taxes` (see `taxes help` for details). ---- - -Regarding any profile you create: +Note: - 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. - - 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**. + - When you want to edit custom settings for an account or a subaccount, use the container `edit` command. See container's `edit help` for details. + +#### Times + +All `times` related files will reside in `${DOCKER_FINANCE_CONTAINER_FLOW}/times` (this includes the timewarrior database). + +See the container `times help` command for details. ### Caveats & Oddities #### Flow Layout +Your `finance-flow` directory will contain a symlink called `src` which links to code that processes your data. **Do not delete this symlink**. + ##### *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!**