Guides Introduction
Work in progress
Incomplete and too terse to be very useful at the moment.
To be expanded out with examples.
Terminology, Defaults and Basic Usage
TBD means ‘To Be Documented’
<ledglive> means
npx ts-node-dev appornpx ts-node app(in ledglive_server code).\ledglive-win.exeor./ledglive-linuxor./ledglive-macos(for binaries compiled from source).\ledglive.exeor./ledglive(for binaries downloaded from GitHub)
If <ledglive> as npx ts-node-dev app or npx ts-node app (in ledglive_server code) is used, then a separate web server must also be started in ledglive_server\ledglive_react client with yarn start.
See install start for specific examples.
When starting off adding -v (for verbose) to
Server runs on port 8652 (http) and port 8653 (https). Can be changed with command line argument. Server works with both GraphQL and REST. For binary builds, the web server for the react client is built in and uses the same ports.
The server for the react web client, when running as source code, runs on port 3010. It makes GraphQL requests over port 8652 to the ledglive server.
ledglive_server can be run in a client mode with a CLI (command line interface) for reporting purposes and uses REST to communicate with the server
Defaults
If no .env file is provided and the server is started as <ledglive> sr then the server uses the same configuration as in .env.opaltrader and looks for sqlite database file ledglive_opaltrader.db
LedgLive run modes
There are three run modes for <ledglive> and there is deliberately no default run mode
Running <ledglive> on its own results in
.\ledglive-win.exe
using external certs
LL (LedgLive) Server and Client, https://ledglive.io, v0.1.0
ledglive <cmd> [args], to show help for client command:
ledglive client -h
Commands:
ledglive server [port] start the server [aliases: sr]
ledglive client [cmd] connect with server [aliases: cl]
ledglive database [dbcmd] use database directly [aliases: db]
Options:
--version Show version number [boolean]
-v, --verbose Run with verbose logging [boolean]
-h, --help Show help [boolean]
The three run modes are named server, client and database. They have aliases sr, cl and db. <ledglive> must be followed with one of these mode names or its alias
Suppose <mode> is one of these modes or aliases then
<ledglive> <mode> -h shows help for that mode
server mode help
Server mode in WSL under Windows as ./ledglive-linux server does work with .\ledglive-win.exe client under Windows but not the other way around (see next section).
Running <ledglive > sr -h
.\ledglive-win.exe sr -h
using external certs
LL (LedgLive) Server and Client, https://ledglive.io, v0.1.0
ledglive server [port]
start the server
Positionals:
port port to bind on [number] [default: 8652]
Options:
--version Show version number [boolean]
-v, --verbose Run with verbose logging [boolean]
-h, --help Show help [boolean]
-d, --database_url if no dotenv file with DATABASE_URL: database sqlite file
or postgres connection string with :, such as with
postgres:, pg: or socket:
[string] [default: "ledglive_opaltrader.db"]
-k, --knexconfig override db, including default db and dotenv, from
internal knexconfig file [boolean]
-m, --migrate knex migrate:latest [boolean]
-s, --seed knex seed:run [boolean]
-c, --console allow information to console, default true. Set false for
Windows service [boolean] [default: true]
-f, --logfile allow information logging to file named, default no file.
Set a name for Windows service [string] [default: ""]
-l, --loglevel Loglevel for console and log file, default 'info', 'trace'
has highest quantity
[choices: "trace", "debug", "info", "warn", "error", "fatal", "off"] [default:
"info"]
client mode help
CLient mode in WSL under Windows as ./ledglive-linux client does not work with .\ledglive-win.exe server under Windows but does work with ./ledglive-linux server in WSL under Windows. So if you want to use ./ledglive-linux client with WSL make sure you are also using ./ledglive-linux server with WSL.
Running <ledglive > cl -h
.\ledglive-win.exe cl -h
using external certs
LL (LedgLive) Server and Client, https://ledglive.io, v0.1.0
ledglive client [cmd]
connect with server
Positionals:
cmd data to fetch
[choices: "ledger", "l", "account", "a", "accounts", "s", "tax", "t", "pl_bs",
"b", "privateuse", "p"] [default: "ledger"]
Options:
--version Show version number [boolean]
-v, --verbose Run with verbose logging [boolean]
-h, --help Show help [boolean]
-u, --url url to connect with
[string] [default: "http://localhost:8652"]
-a, --account_id For a. Account ID [number] [default: 11110]
-b, --datebegin For a. Date Begin [string] [default: "2021-09-01"]
-e, --dateend For a. Date End [string] [default: "2021-09-31"]
-l, --ledger_id For l. Ledger ID [number] [default: 1]
-y, --year For t. Year (not fin year) [number] [default: 2021]
-q, --quarter For t. Quarter [choices: 1, 2, 3, 4] [default: 3]
-r, --finyear_first For b, Financial year first [number] [default: 2022]
-s, --finyear_last For b, Financial year last [number] [default: 2022]
-p, --finyear_privateuse For p, Financial Year [number] [default: 2022]
database mode help
Running <ledglive > db -h
.\ledglive-win.exe db -h
using external certs
LL (LedgLive) Server and Client, https://ledglive.io, v0.1.0
ledglive database [dbcmd]
use database directly
Positionals:
dbcmd some shortcuts, better to use sqlite3 or psql
[choices: "readtable", "r", "addaccount", "a", "deleteemptyaccount", "d"]
[default: "readtable"]
Options:
--version Show version number [boolean]
-v, --verbose Run with verbose logging [boolean]
-h, --help Show help [boolean]
-u, --url url to connect with
[string] [default: "http://localhost:8652"]
-t, --table view content of table named
[string] [default: "help"]
-y, --type, --accounttype specify accounttype id for add account
[number] [default: 1]
-o, --owner,, --accountowner specify accountowner id for add account
[number] [default: 1]
-n, --name, --title specify title of new account
[string] [default: "New Account"]
-b, --balance, --openingbalance openingbalance for account
[number] [default: 0]
-i, --id specify id for database operation, if
required. default 0 is not accepted
[number] [default: 0]
The configuration layers
For server mode
The default database is the sample database sqlite file ledglive_opaltrader.
NODE_ENV defaults to ‘development’ if not specified in .env. So far this is only relevant if -k option is used and is intended to be used with knex migration and seeding.
If -k is specified and NODE_ENV in .env is development then the postgresql database specified in .env is used for knexfile.ts.
If -k is specified and NODE_ENV in .env is production then the sqlite database specified in .env in used in for knexfile.ts.
if -k is specified and there is no .env file then .env.opaltrader behaves as if it is the .env file. This means ledglive_opaltrader.db becomes the database file (as NODE_ENV is production and DB_SQLITE is ./ledglive_opaltrader.db in the original .env.opaltrader) file.
For server mode and client mode
Other than the above with -k for server mode, there are four layers of configuration:
- A command line argument takes precedence. For example
-d ledglive_production.dbfor an sqlite database (if-knot used). - if no overriding command line argument option then a corresponding environment variable with the same name as in the .env file takes precedence.
- If no overriding command line argument option and no corresponding environment variable then any corresponding dotenv entry takes precedence. For example
DB_URL=ledglive_production.dbin.env(if -k not used). - If there is no
.envfile then the server behaves as if the original.env.opaltraderis the.envfile. The word original is important, because editing the.env.opaltraderfile will not change what is loaded.
The .env file is set to be ignored by git
Git is also set to ignore ledglive.db, ledglive_production.db and ledglive_development.db
.env.opaltrader as default .env
If there is no .env then <ledglive> behaves as if .env is the contents of .env.opaltrader
Some of the entries in .env only apply to <ledglive> in client mode, such as
ACCOUNTID_DEFAULT
LEDGERID_DEFAULT
DATEBEGIN_DEFAULT
DATEEND_DEFAULT
TAX_YEAR_DEFAULT
TAX_QUARTER_DEFAULT
FINYEAR_FIRST_DEFAULT
FINYEAR_LAST_DEFAULT
FINYEAR_PRIVATEUSE_DEFAULT
# if below empty must be []
ACCOUNTID_INTERLOAN
ACCOUNTOWNERID_DEFAULT
ACCOUNTID_DEPRECIATION
ACCOUNTID_RETAINEDEARNINGS
ACCOUNTID_EQUITY
# if below empty must be []
ACCOUNTID_ACCSPECIALS
# if below empty must be []
TAXHEADEREXTRA
cat .env.opaltrader
#DB_URL is used if -k not specified for server and not overriden by -d
DB_URL=ledglive_opaltrader.db
#DB_URL=postgres://postgres:password@localhost:5432/ledglive_opaltrader
PORT=8652
#PORT=8654
#when -k specified for server and NODE_ENV is production
NODE_ENV=production
DB_SQLITE=./ledglive_opaltrader.db
#when -k specified for server and NODE_ENV is development
# use postgresql when NODE_ENV is development
#NODE_ENV=development
DB_CLIENT=postgresql
DB_HOST=localhost
DB_NAME=ledglive_opaltrader
DB_USER=postgres
DB_PASS=password
DB_PORT=5432
ACCOUNTID_DEFAULT = 11110
LEDGERID_DEFAULT = 1
DATEBEGIN_DEFAULT = 2021-09-01
DATEEND_DEFAULT = 2021-09-31
TAX_YEAR_DEFAULT = 2021
TAX_QUARTER_DEFAULT = 3
FINYEAR_FIRST_DEFAULT = 2022
FINYEAR_LAST_DEFAULT = 2022
FINYEAR_PRIVATEUSE_DEFAULT = 2022
# [12520, 21520] ['Loans from Mr Opal', 'Loans to Opal Trader']
# [12530, 31520] ['Loans from Ms Opal', 'Loans to Opal Trader']
# [22511, 31521] ['Loans from Ms Opal', 'Loans to Mr Opal']
# if below empty must be []
ACCOUNTID_INTERLOAN = [ [12520, 21520], [12530, 31520], [22511, 31521] ]
# 'Asset':
TYPE_ASSETID = 1
# 'Liability':
TYPE_LIABILITYID = 2
# 'Equity':
TYPE_EQUITYID = 3
# 'Revenue':
TYPE_INCOMEID = 4
# 'Expense':
TYPE_EXPENSEID = 5
# Opal Traders:
ACCOUNTOWNERID_DEFAULT = 1
ACCOUNTID_DEPRECIATION = 15310
ACCOUNTID_RETAINEDEARNINGS = 15001
ACCOUNTID_EQUITY = 13110
# if below empty must be []
ACCOUNTID_ACCSPECIALS = [ 11310, 11210, 12210 ]
# N/A:
TAXCODEID_DEFAULT = 1
# "extra line 1 from entity_opaltrader"
# "extra line 2 from entity_opaltrader"
# "extra line 3 from entity_opaltrader"
# "extra line 4 from entity_opaltrader"
# if below empty must be []
TAXHEADEREXTRA=["extra line 1 from entity_opaltrader", "extra line 2 from entity_opaltrader", "extra line 3 from entity_opaltrader", "extra line 4 from entity_opaltrader"]
GraphQL Codegen
Needs a lot of explaining but works in an incredibly convenient way for the project!
For server yarn codegen
For client, make sure server is running, then yarn codegen