Installation Manual

This is installation manual for tackler command line.

To use tackler cli you will need

  • Java Runtime Environment (Java 8 and Java 11 are tested regularly)

  • Tackler command line binary (tackler-cli.jar-file)

Minimal setup

Minimal initial installation and setup is described in Quickstart Guide.

Minimal setup with account name validation (Chart of Accounts)

To enable account name validation for minimal quickstart setup, there have to be Chart of Accounts, which defines all used account names:

cat >> accounts.conf << EOF
accounts {

  strict = true

  permit-empty-commodity = true

  coa = [
    "Expenses:Ice_cream",
    "Expenses:Lemonade",
    "Assets:Cash"
  ]
}
EOF

After that it’s possible to run tackler with account name validation:

java -jar ./tackler-cli.jar

If there is missing or mistyped account, that will cause an exception error. See example of accounts.conf for full documentation of Chart of Accounts and commodity listing.

Recommended layout

Recommended layout and setup would be:

./bin/tackler-cli.jar
./bin/tackler.conf
./bin/accounts.conf
./txns/
./txns/YYYY/MM/journal-01.txn
./txns/YYYY/MM/journal-02.txn
...

Where YYYY and MM stand for time based data shard with year and month slides. It’s up to individual setup which is the best way to shard transaction data, if any.

Transactions can be selected either based on shards or by using filters. See Usage Guide for how to use filters, and Transaction Filters document for overall information about available filters.

By default Tackler will try to find configuration file (tackler.conf) next to its jar-file. You can also provide path to configuration file with --cfg option.

With recommended setup, configuration file tackler.conf is located next to the jar-file and it is auto-discovered. There is also accounts.conf which contains accounts and commodity names definitions. This makes it possible to do strict account and commodity name validation.

Minimal tackler.conf for above setup could be:

tackler {
  core {
    basedir = ../
    input {
      storage = fs
      fs {
        dir = "txns"
        glob = "**.txn"
      }
    }
    include "accounts.conf"
  }
}

With this setup, it is possible to run Tackler by:

java -jar ./bin/tackler-cli.jar

and it will just work.

There are more examples how to use tackler in Usage Guide.

Configuration

Please see Configuration Manual for information about how to tailor and configure system.

You can override some of the configuration varibles with CLI arguments. These configuration variables, and command line switches are documented in tackler.conf.

Chart of Accounts and commodities

By default it is fatal error if there is an unknown account or commodity within transactions. It’s also fatal error if there is a posting without commodity and at the same accounts.permit-empty-commodity is false.

Both checks for accounts and commodities can be turned off with:

--accounts.strict=false

but then there is no safety net against typos with account names.

Postings with empty/missing commodities can be allowed with configuration setting:

accounts {
   permit-empty-commodity = true
}

With production systems, it is highly recommended to provide valid Chart of Accounts and list of valid commodities.

Chart of accounts is defined either as part of main configuration or as separate configuration file. See accounts.conf for example configuration.