GnuCash Web

GnuCash Web is a simple, easy to use, mobile-friendly web interface for GnuCash intended for self-hosting. It can access a single GnuCash-Database in sqlite3, postgres or mysql (including mariadb) format using the great piecash GnuCash library for Python.

Development status should be considered at most Beta, see below for more information.

Check out the demo!

Features

The primary use case for GnuCash Web is adding simple two-split transactions on the go, e.g. to record a cash expense when buying a coffee.

Key features include:

• Browse account hierarchy
• View transaction history and balance for an account
• Add and edit two-split transactions, delete transactions
• Recycle commonly used transactions
• Simple single-user authentication
• Ease of use, especially on mobile
• CLI to update the price database

Browse account hierarchy	View and add transactions	Edit transactions

Core Technology Stack

• Python
• piecash for accessing GnuCash database
• Flask web framework
• Bootstrap for front end design

Installation

GnuCash Web is available on PyPI, so you can simply install it via pip install gnucash_web. Additionally, you may need to install mysql or psycopg2, depending on which back end you want to use (sqlite back end is included in the python standard library).

Note that at least Python 3.8 is required.

You also need to setup a database that stores the GnuCash data, see below for more information. Mind that you will likely need to be able to access the database directly from your desktop/notebook with the official GnuCash desktop app, since GnuCash Web is only a companion and not intended to be used on its own. If your database is not publicly accessible, using an SSH Tunnel is an easy and secure way to access it remotely.

Usage

GnuCash Web is aimed at system administrators, but is otherwise easy to set up.

Configuration

Create a config file in /etc/gnucash-web/config.py or in ~/.config/gnucash-web/config.py. If both files are present, values from the latter override those from the former. Set the environment variable GNUCASH_WEB_CONFIG to load a different config file. If set, no other config files are read.

Config variables can also be set via environment variables, with the same available options.

The config file is a python script. The following example illustrates possible values for all available options. This is the normal Flask configuration file, so all standard configuration variables can also be set. All options have default values, but you should at least set SECRET_KEY and DB_NAME.

import logging

# A 32-bit-key used e.g. to encrypt the session cookie or for other cryptographic operations
# Use e.g. `from Crypto.Random import get_random_bytes; print(get_random_bytes(32))`
SECRET_KEY = 'please use something thats actually safe'

# Python standard library log level
LOG_LEVEL = logging.WARN

# Supported values: 'sqlite', 'mysql' or 'postgres'
DB_DRIVER = 'mysql'

# Host name of the database (ignored for DB_DRIVER = 'sqlite')
DB_HOST = 'database.example.org'

# Name of the Database on the host (for DB_DRIVER = 'sqlite', this is the 'path/to/db.sqlite')
DB_NAME = 'gnucash_data'

# Supported values: None, 'passthrough'. See below for details.
AUTH_MECHANISM = None

# The maximum number of transactions per page in the ledger
TRANSACTION_PAGE_LENGTH = 25

# Name of the account to be preselected when creating new transactions (optional)
PRESELECTED_CONTRA_ACCOUNT = 'Example:Account'

Running

It is not recommended to use the builtin Flask web server in production. GnuCash Web comes as a WSGI application, so there are many options available to run it.

Most WSGI web server require setting a "module", which is the WSGI object that runs the app. For GnuCash Web, this is gnucash_web.wsgi:app.

For example, the following .ini-file might be used as a config for uWSGI:

[uwsgi]
module = gnucash_web.wsgi:app
pidfile = gnucash_web.pid
master = true
processes = 1
http-socket = :8080
chmod-socket = 660
vacuum = true

Docker

GnuCash Web can be run using Docker, either using the published packages, DockerFile, or using docker compose with the provided sample docker-compose.yml files. This uses a simple SQLite backend, though if you want to use a dedicated database backend then docker-compose-postgres.yml is also provided, running PostgreSQL as the name implies.

In either case, configuration is done via environment variables in the compose file instead of the default configuration file. The same options are available.

If you're running a dedicated backend as part of docker compose, then in order to initialise the database you'll need to expose the respective ports. Keep security in mind when exposing ports, such as using a strong password, as exposing ports may grant any user on the internet access to your database.

If you want to quickly spin up and test gnucash-web, then a sample GnuCash database is provided for the SQLite version.

The Docker version runs the gunicorn WSGI server.

Initialising database

GnuCash Web only works on a preexisting database. It is also currently not possible to create accounts. Therefore, you have to create a database and populate it with an account hierarchy before you can use GnuCash Web.

Preferably, you will use the official GnuCash desktop app to create a new book. Simply select the appropriate database back end in the Open-dialog. You can also migrate an existing GnuCash XML file to a database using Save as. More details and database considerations can be found in the official GnuCash documentation.

Alternatively, you can also use piecash to create a new book, as is described in their example section.

Authentication

Currently, there are only two authentication mechanisms supported, None and 'passthrough'.

When using no authentication, anyone can access the web interface and no credentials are provided to the database host. This is generally only useful when using the sqlite back end (which does not accept credentials).

When using pass-through authentication, GnuCash Web asks for username and password upon login, which are provided as credentials for the database hosts. They are also stored in an encrypted session cookie in the users browser. "Logging out" simply deletes the session cookie.

CLI

The CLI is called gnucash-web and is installed with the PyPi package. Currently, the only supported subcommand is gnucash-web commodities:

Usage: gnucash-web commodities [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  list           List all used commodities.
  update_prices  Update prices for all commodities for which it is enabled.

You can add/edit commodities using the GnuCash desktop app. Make sure to enable online quotes updating. Then, gnucash-web commodities update_prices will retrieve daily closing prices from Yahoo Finance (Quandl for currencies). See also the piecash documentation of the underlying function.

Development

Initialise submodules and install dependencies:

    git submodule init
    git submodule update
    pip install -r src/requirements.txt

Run it:

    cd src/gnucash_web/
    flask run --debug

Make new release:

• Update version number in src/gnucash_web/version.txt
• Build and upload package

      cd src/
      python -m build
      python -m twine upload dist/gnucash_web-$VERSION*

• Tag commit and create release on GitHub

Contributing

Development is at an early stage, but contributions are welcome.

This is (currently) a personal project to play around with and satisfy my own everyday needs and intellectual curiosity.

Since GnuCash Web fulfills my primary use case for it, I don't expect much development in the near future. However, if anyone is willing to help taking this into a more feature-rich direction, I am motivated to work on that, though time is naturally scarce.

Please note that my primary user is myself and any changes must be compatible with my use case and workflows. I will also not accept changes or additions that I cannot gauarantee to maintain in the future. Simplicity is more important to me than features, so please consider this and talk to me before spending time on big changes.

See Issues and Milestones for some ideas on how to get started.

Related Work

There seem to be few other projects in the same direction:

• The GnuCash mailing list(s) has a few results
  • In 2003, Martin asked about this and was recommended to to use SSH+X-Forwarding to access his GnuCash database remotely.
  • In 2005, Sachin said they are planning to work on a web interface, but I could find no further results.
  • In 2012, James posted about his project nylen/gnucash-django, but the last commit is from 2015.
• The GnuCash Wiki's Wishlist lists the use through a web browser (as well as an iPhone-App) as "WONTFIX" (discussion from 2006/2007).
• In 2016, mikedom722 asked on Reddit, whether anyone would be interested in a web interface (stating that he has one), but did not follow up.
• In the same thread, superman279 presents his app Remote GnuCash, but the last commit is from 2017 and the website is down.
• The GnuCash Wiki mentions two GnuCash mobile apps, one for iOS and one for Android. The one for Android seems to be discontinued (last commit 2020) the one for iOS still has new commits in 2022, but its purpose seems to be to export a CSV to be imported in GnuCash, rather then writing to the database directly.
• There is alensiljak/gnucash-portfolio-webui on GitHub, but the README does not clearly state what it does. It seems to be only a exporter for certain reports. Anyway, it was archived in 2022, with last commit from 2018.

To conclude, all projects in this direction seem to be at most prototypes for playing around and even those are scarce. The GnuCash dev-team itself doesn't seem to be keen on providing a real mobile/web alternative, which is perfectly fine and understandable. I probably wouldn't either if I were them. Luckily, I am not!

License

Copyright © 2023 Joshua Bachmeier [email protected]

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

See LICENSE in this repository or https://www.gnu.org/licenses/ for a copy of the GNU General Public License.

The contents of the submodules EncryptedSession (GPLv3), Selectize (Apache License 2.0), Bootstrap (MIT License) and GnuCash (mutually-compatible set of licenses) as well as all dependencies are published under their own licenses by their respective authors.