πŸ“–

Self-Hosted Costflow Hub Docs

1. Download Costflow Hub

Choose the program you want to download on the download page.

If you want to run it on a linux server, you can also download using the following command:

curl -L https://self-hosted.costflow.io/download/linux --output costflow-hub-linux
sudo chmod 755 ./costflow-hub-linux

Compatibility test

Run Costflow Hub with the commands in step 6 now. If the program is not crash and displays version info, you're good to go.

2. Get a license

We will send the license to your email once you purchased Costflow Hub on Gumroad.

πŸ’‘

Your license can be used in any supported operating system, but only one can be running at the same time.

3. Apply a Telegram bot token

Send command /newbot to the @botfather, then reply the bot name and username, that's it.

image

4. Configure hub.json

Create a new file named hub.json in the same directory as the Costflow Hub program.

A sample hub.json file:

{
  "license": "AAAAAAAA-BBBBBBBB-CCCCCCCC-DDDDDDDD",
  "telegram_bot_token": "11111111:AAAAAAABBBBBBBCCCCCCDDDD",
  "authorized_users": {
    "telegram": "leplay"
  },
  "config_path": "",
  "ledger_path": "~/costflow-hub/%YYYY/MM%.bean",
  "proxy": ""
}
πŸ’‘

Replace license and telegram_bot_token with your own. For security concerns, you must fill your Telegram username into authorized_users.telegram , so only your messages will be accepted and saved to ledger files. config_path is the path of costflow.json . Leave it blank if it is in the same directory as hub.json. ledger_path is the path where ledger files will be saved. Some date variables are supported (YYYY, MM, DD, the whole path needs to be surrounded using % ). For example, %YYYY/MM%.bean means to save all entries by month under the year folder. proxy is designed for connecting Telegram API, HTTP/HTTPS proxies are supported. E.g., https://1.1.1.1:2020。

5. Configure costflow.json

costflow.json is the config file of Costflow Syntax. A sample file:

{
  "currency": "USD",
  "mode": "beancount",
  "timezone": "Asia/Hong_Kong",
  "tag": "#costflow",
  "indent": 2,
  "lineLength": 50,
  "insertTime": "metadata",
  "alphavantage": "AAAABBBBCCCC",
  "account": {
    "cloud": "Expenses:Tech:Cloud",
    "eob": "Equity:Opening-Balances",
    "spotify": "Expenses:Entertainment:Spotify",
    "visa": "Liabilities:CreditCard:VISA"
  },
  "formula": {
    "aws": "! @AWS {{ amount }} USD visa > cloud",
    "spotify": "! @Spotify 15.98 USD visa > spotify"
  }
}

You can get more info on Costflow Syntax docs.

6. Run

Once the above steps finished, you can start the program by opening a terminal window and use cd command to the program directory, then run the following command:

Mac OS

./costflow-hub-macos

Windows

# Type command in Terminal app, double-click will not work.
costflow-hub-win.exe

Linux

./costflow-hub-linux

If you want to run Costflow Hub background on a remote server, you can use screen command.

Docs

Security Tips

  • Do not share your Telegram token and bot's username.
  • You can revoke your Telegram bot's token via @botfather if necessary. If your bot keeps getting messages from other users, you should consider creating a new bot (the username of Telegram bot is not allowed to change at the moment).
  • Do not share your license.
  • If you want to run Costflow Hub on a server, you should disable all unnecessary ports on network or firewall settings.