Package: gnucash-web
GnuCash WebGnuCash Webis a simple, easy to use, mobile-friendly web interface forGnuCashintended for self-hosting. It can access a single
GnuCash-Database insqlite3,postgresormysql(includingmariadb) format using the greatpiecashGnuCash library for Python.Development status should be considered at mostBeta, seebelowfor
more information.Check out thedemo!FeaturesThe primary use case forGnuCash Webis adding simple two-split transactions on the
go, e.g. to record a cash expense when buying a coffee.Key features include:Browse account hierarchyView transaction history and balance for an accountAdd and edit two-split transactions, delete transactionsRecycle commonly used transactionsSimple single-user authenticationEase of use, especially on mobileCLI to update the price databaseBrowse account hierarchyView and add transactionsEdit transactionsCore Technology StackPythonpiecashfor accessing GnuCash databaseFlaskweb frameworkBootstrapfor front end designInstallationGnuCash Webisavailable on PyPI, so you can
simply install it viapip install gnucash_web. Additionally, you may need to installmysqlorpsycopg2, 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, seebelowfor 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, sinceGnuCash Webis only a companion and not
intended to be used on its own. If your database is not publicly accessible, using anSSH Tunnelis an easy and secure way to
access it remotely.UsageGnuCash Webis aimed at system administrators, but is otherwise easy to set up.ConfigurationCreate a config file in/etc/gnucash-web/config.pyor in~/.config/gnucash-web/config.py.  If both files are present, values from the latter
override those from the former.  Set the environment variableGNUCASH_WEB_CONFIGto 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 allstandard
configuration
variablescan also be set. All options havedefault values, but you
should at least setSECRET_KEYandDB_NAME.importlogging# 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 levelLOG_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 ledgerTRANSACTION_PAGE_LENGTH=25# Name of the account to be preselected when creating new transactions (optional)PRESELECTED_CONTRA_ACCOUNT='Example:Account'RunningIt is not recommended to use the builtin Flask web server in production.GnuCash Webcomes as aWSGIapplication, so there aremany
optionsavailable to run it.Most WSGI web server require setting a "module", which is the WSGI object that runs the
app. ForGnuCash Web, this isgnucash_web.wsgi:app.For example, the following.ini-file might be used as a config foruWSGI:[uwsgi]module=gnucash_web.wsgi:apppidfile=gnucash_web.pidmaster=trueprocesses=1http-socket=:8080chmod-socket=660vacuum=trueDockerGnuCash Webcan be run usingDocker, either using the publishedpackages, DockerFile, or usingdocker composewith the provided sampledocker-compose.ymlfiles. This uses a simple SQLite backend,
though if you want to use a dedicated database backend thendocker-compose-postgres.ymlis also provided, runningPostgreSQLas 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 toinitialise the databaseyou'll need toexpose 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 isprovidedfor the SQLite version.The Docker version runs thegunicornWSGI server.Initialising databaseGnuCash Webonly 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 useGnuCash Web.Preferably, you will use the official GnuCash desktop app to create a new
book. Simply select the appropriate database back end in theOpen-dialog. You can
also migrate an existing GnuCash XML file to a database usingSave as. More details
and database considerations can be found in the officialGnuCash
documentation.Alternatively, you can also usepiecashto create a new book, as is described in
theirexample
section.AuthenticationCurrently, there are only two authentication mechanisms supported,Noneand'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 Webasks 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.CLIThe CLI is calledgnucash-weband is installed with the PyPi package. Currently, the only
supported subcommand isgnucash-web commodities:Usage:gnucash-webcommodities[OPTIONS]COMMAND[ARGS]...

Options:--helpShowthismessageandexit.

Commands:listListallusedcommodities.update_pricesUpdatepricesforallcommoditiesforwhichitisenabled.You canadd/edit commodities using the GnuCash desktop
app. Make sure to
enable online quotes updating. Then,gnucash-web commodities update_priceswill retrieve
daily closing prices from Yahoo Finance (Quandl for currencies). See also thepiecash
documentationof the underlying function.DevelopmentInitialise submodules and install dependencies:gitsubmoduleinitgitsubmoduleupdatepipinstall-rrequirements.txtRun it:exportFLASK_APP=gnucash_webexportFLASK_ENV=developmentflaskrunBuild and upload package:python-mbuildpython-mtwineuploaddist/*ContributingDevelopment 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.SinceGnuCash Webfulfills 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.SeeIssuesandMilestonesfor some ideas on how
to get started.Related WorkThere seem to be few other projects in the same direction:The GnuCash mailing list(s) has a few resultsIn 2003,Martin asked about
thisand
was recommended to to use SSH+X-Forwarding to access his GnuCash database
remotely.In 2005,Sachin saidthey are planning to work on a web interface, but I could find no further results.In 2012,James
postedabout his projectnylen/gnucash-django, but the last
commit is from 2015.TheGnuCash Wiki's
Wishlistlists the
use through a web browser (as well as an iPhone-App) as "WONTFIX" (discussion from
2006/2007).In 2016, mikedom722 asked onReddit,
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 appRemote
GnuCash, but the last commit is
from 2017 and the website is down.TheGnuCash Wikimentions 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 isalensiljak/gnucash-portfolio-webuion 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!LicenseCopyright © 2023 Joshua Bachmeierjoshua@bachmeier.ccThis 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, butwithout any
warranty; without even the implied warranty ofmerchantabilityorfitness for a
particular purpose.  See the GNU General Public License for more details.SeeLICENSEin this repository orhttps://www.gnu.org/licenses/for a copy of
the GNU General Public License.The contents of the submodulesEncryptedSession(GPLv3),Selectize(Apache License 2.0),Bootstrap(MIT License) andGnuCash(mutually-compatible set of licenses) as
well as all dependencies are published under their own licenses by their respective authors.