Beancolage, a plaintext accounting environment bundling Beancount-based tools

This is an ongoing prototype of a plaintext accounting environment based on Eclipse Theia and including Beancount, VSCode-Beancount, and Fava.

⚠️ This is a prototype currently in early development. Feel free to file an issue if you have questions or interest in contributing.

Motivation & Limitations

The aspiration of Beancolage is to provide a more 'download and try' experience for plaintext accounting, centered around Beancount and Fava. The hope is to make the plaintext accounting experience accessible beyond just those with deep technical expertise, potentially to assist in group/organization bookkeeping. This said, Beancolage is intended to be a bricolage and not intended to be a fully-integrated accounting tool.

Can I use this for a full workflow including importing from my bank?

No, this is a missing piece of Beancolage right now, and may be explored later. Generally importers in the plaintext accounting space have been a challenge to collaboratively develop on - for now you might want to check the external contribution guides on importing, such as The Five Minute Ledger Update.

License

Beancolage is built upon Eclipse Theia, a framework for building cloud and desktop IDEs.

• Eclipse Public License 2.0
• 一 (Secondary) GNU General Public License, version 2 with the GNU Classpath Exception

Beancolage also uses:

• vscode-beancount by Lencerf (MIT License)
• ves-process from VUEngine Studio (Eclipse Public License v2.0)

Future releases of Beancolage plan to include:

• Beancount (GNU GPLv2 License)
• Fava (MIT License)

Repository Structure

This repository, including this readme, is heavily based on Theia-IDE (fka Theia-Blueprint) with various UI extensions.

• Root level configures mono-repo build with lerna
• applications groups the different app targets:
  • browser contains a browser based version of Beancolage that may be packaged as a Docker image
  • electron contains app to package, packaging configuration, and E2E tests for the electron target.
• extensions/beancolage-extensions-ext groups the various extensions, within src there is:
  • navigator-fava - A navigation panel for opening beancount files in Fava, and to see open Fava views (based on open-editors-widget).
  • fava-interface - manages Fava server, notably adding in file arguments.
  • process - copy of ves-process from VUEngine Studio.
• extensions/beancolage-product-ext is based on theia-blueprint-product and handles application-wide customizations (getting started page, help, default workbench layout, colors, etc.).

Getting Started

Prequisite Installs

At this time, builds only work if you have Beancount and Fava installed such that fava by command line can be called.

0. Install [Fava], assuming you already have Python installed this can be done via:

pip install fava

Install Beancolage

TODO

Building Beancolage

Prerequisites

0. Clone this repository.

1. Install nvm.

2. Install npm and node.

nvm install --lts

nvm use --lts`

0. Install yarn.

npm install -g yarn

(optional) Download vscode plugins

If adding or updating any vscode plugins (e.g. vscode-beancount) you may need to do:

yarn theia download:plugins

(optional) Prepare

yarn prepare

Build

yarn

For development and casual testing, one can build it in "dev" mode:

# Build "dev" version of Beancolage. Its quicker, uses less resources, 
# but the front end app is not "minified"
yarn && yarn build:dev && yarn download:plugins

For production builds:

# Build production version Beancolage
yarn && yarn build && yarn download:plugins

Package the Electron Application

yarn package:applications
# or
yarn electron package

The packaged application is located in applications/electron/dist.

NOTE: In practice I have found myself running npx theia rebuild:electron followed by yarn electron package , likely due to electron-rebuild issues that result in Error: Module did not self-register:[...]drivelist.node errors

Create a Preview Electron Application (without packaging it)

yarn electron package:preview

The packaged application is located in applications/electron/dist.

Running E2E Tests on Electron

The E2E tests basic UI tests of the actual application. This is done based on the preview of the packaged application.

yarn electron package:preview
yarn electron test

Running Browser app

The browser app may be started with

# Download Plugins for browser app
yarn browser download:plugins

# Start browser app
yarn browser start

and connect to http://localhost:3000/

Troubleshooting

TODO

Reporting Feature Requests and Bugs

Many features in Beancolage are based on Theia and the included extensions/plugins. For bugs in Theia please consider opening an issue in the Theia project on Github.

If something isn't working properly, please open an issue on Github to let us know.

Docker Build

You can create a Docker Image for Beancolage based on the browser app with the following build command:

docker build -t beancolage -f browser.Dockerfile .

You may then run this with

docker run -p=3000:3000 --rm beancolage

and connect to http://localhost:3000/