GnuCash Web
===========
*GnuCash Web* is a simple, easy to use, mobile-friendly web interface for
[GnuCash](https://gnucash.org/) intended for self-hosting. It can access a single
GnuCash-Database in [sqlite3](https://sqlite.org/index.html),
[postgres](https://www.postgresql.org/) or [mysql](https://www.mysql.com/de/) (including
[mariadb](https://mariadb.org/)) format using the great
[piecash](https://pypi.org/project/piecash/) GnuCash library for Python.
Development status should be considered at most *Beta*, see [below](#Contributing) for
more information.
Check out the [demo](https://gnucash-web-demo.bachmeier.cc)!
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
| Browse account hierarchy | View and add transactions | Edit transactions |
|---------------------------------------------------------------------------|------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
|  |  |  |
Core Technology Stack
---------------------
- [Python](https://www.python.org/)
- [piecash](https://pypi.org/project/piecash/) for accessing GnuCash database
- [Flask](https://palletsprojects.com/p/flask/) web framework
- [Bootstrap](https://getbootstrap.com/) for front end design
Installation
------------
*GnuCash Web* is [available on PyPI](https://pypi.org/project/GnuCash-Web/), 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](#Initialising Database) 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](https://www.ssh.com/academy/ssh/tunneling) 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.
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](https://flask.palletsprojects.com/en/2.0.x/config/#builtin-configuration-values)
can also be set.
```python
import logging
# A 32-bit-key used e.g. to encrypt the session cookie or for other cryptographic operations
SECRET_KEY = 'devel'
# 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
```
### Running
It is not recommended to use the builtin Flask web server in production. *GnuCash Web*
comes as a [WSGI](https://wsgi.readthedocs.io/en/latest/) application, so there are [many
options](https://flask.palletsprojects.com/en/2.0.x/deploying/) 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](https://uwsgi-docs.readthedocs.io/en/latest/):
```ini
[uwsgi]
module = gnucash_web.wsgi:app
pidfile = gnucash_web.pid
master = true
processes = 1
http-socket = :8080
chmod-socket = 660
vacuum = true
```
### 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](https://www.gnucash.org/docs/v4/C/gnucash-guide/basics-files1.html).
Alternatively, you can also use *piecash* to create a new book, as is described in
their [example
section](https://piecash.readthedocs.io/en/master/tutorial/examples.html#creating-and-opening-gnucash-files).
### 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.
Development
-----------
Initialise submodules and install dependencies:
```sh
git submodule init
git submodule update
pip install -r requirements.txt
```
Run it:
```sh
export FLASK_APP=gnucash_web
export FLASK_ENV=development
flask run
```
Build and upload package:
```sh
python -m build
python -m twine upload dist/*
```
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.
See [Issues](https://github.com/joshuabach/gnucash-web/issues) and
[Milestones](https://github.com/joshuabach/gnucash-web/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](https://lists.gnucash.org/pipermail/gnucash-user/2003-July/007243.html) and
was recommended to to use SSH+X-Forwarding to access his GnuCash database
remotely.
- In 2005, [Sachin said](https://lists.gnucash.org/pipermail/gnucash-user/2005-July/014163.html)
they are planning to work on a web interface, but I could find no further results.
- In 2012, [James
posted](https://lists.gnucash.org/pipermail/gnucash-user/2012-March/043762.html)
about his project
[nylen/gnucash-django](https://github.com/nylen/gnucash-django), but the last
commit is from 2015.
- The [GnuCash Wiki's
Wishlist](https://wiki.gnucash.org/wiki/WishList#Use_through_web_browser) 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](https://www.reddit.com/r/GnuCash/comments/3zlel3/gnucash_web_interface_useful/),
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](https://github.com/justinhunt1223/remotegnucash), but the last commit is
from 2017 and the website is down.
- The [GnuCash Wiki](https://wiki.gnucash.org/wiki/GnuCash_and_Mobile_Devices)
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](https://github.com/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 © 2022 Joshua Bachmeier <joshua@bachmeier.cc>
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](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](https://github.com/SaintFlipper/EncryptedSession) (GPLv3),
[Selectize](https://github.com/selectize/selectize.js) (Apache License 2.0),
[Bootstrap](https://github.com/twbs/bootstrap) (MIT License) and
[GnuCash](https://github.com/Gnucash/gnucash) (mutually-compatible set of licenses) as
well as all dependencies are published under their own licenses by their respective authors.
Raw data
{
"_id": null,
"home_page": "https://github.com/joshuabach/gnucash-web",
"name": "GnuCash-Web",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "bootstrap,flask,web,gnucash",
"author": "Joshua Bachmeier",
"author_email": "joshua@bachmeier.cc",
"download_url": "https://files.pythonhosted.org/packages/89/97/4924b2670e915acacf59f71f86c5cfcb6a3798b92ba7f28969be3e653990/GnuCash%20Web-0.1.0.tar.gz",
"platform": null,
"description": "GnuCash Web\n===========\n\n*GnuCash Web* is a simple, easy to use, mobile-friendly web interface for\n[GnuCash](https://gnucash.org/) intended for self-hosting. It can access a single\nGnuCash-Database in [sqlite3](https://sqlite.org/index.html),\n[postgres](https://www.postgresql.org/) or [mysql](https://www.mysql.com/de/) (including\n[mariadb](https://mariadb.org/)) format using the great\n[piecash](https://pypi.org/project/piecash/) GnuCash library for Python.\n\nDevelopment status should be considered at most *Beta*, see [below](#Contributing) for\nmore information.\n\nCheck out the [demo](https://gnucash-web-demo.bachmeier.cc)!\n\nFeatures\n--------\n\nThe primary use case for *GnuCash Web* is adding simple two-split transactions on the\ngo, e.g. to record a cash expense when buying a coffee.\n\nKey features include:\n\n- Browse account hierarchy\n- View transaction history and balance for an account\n- Add and edit two-split transactions, delete transactions\n- Recycle commonly used transactions\n- Simple single-user authentication\n- Ease of use, especially on mobile\n\n| Browse account hierarchy | View and add transactions | Edit transactions |\n|---------------------------------------------------------------------------|------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|\n|  |  |  |\n\nCore Technology Stack\n---------------------\n\n- [Python](https://www.python.org/)\n- [piecash](https://pypi.org/project/piecash/) for accessing GnuCash database\n- [Flask](https://palletsprojects.com/p/flask/) web framework\n- [Bootstrap](https://getbootstrap.com/) for front end design\n\nInstallation\n------------\n\n*GnuCash Web* is [available on PyPI](https://pypi.org/project/GnuCash-Web/), so you can\nsimply install it via `pip install GnuCash-Web`. Additionally, you may need to install\n`mysql` or `psycopg2`, depending on which back end you want to use (sqlite back end is\nincluded in the python standard library).\n\nNote that at least Python 3.8 is required.\n\nYou also need to setup a database that stores the GnuCash data, see\n[below](#Initialising Database) for more information. Mind that you will likely need\nto be able to access the database directly from your desktop/notebook with the\nofficial GnuCash desktop app, since *GnuCash Web* is only a companion and not\nintended to be used on its own. If your database is not publicly accessible, using an\n[SSH Tunnel](https://www.ssh.com/academy/ssh/tunneling) is an easy and secure way to\naccess it remotely.\n\nUsage\n-----\n\n*GnuCash Web* is aimed at system administrators, but is otherwise easy to set up.\n\n### Configuration\n\nCreate a config file in `/etc/gnucash_web/config.py` or in\n`~/.config/gnucash_web/config.py`. If both files are present, values from the latter\noverride those from the former. Set the environment variable `GNUCASH_WEB_CONFIG` to load\na different config file. If set, no other config files are read.\n\nThe config file is a python script. The following example illustrates possible values for\nall available options. This is the normal Flask configuration file, so all [standard\nconfiguration\nvariables](https://flask.palletsprojects.com/en/2.0.x/config/#builtin-configuration-values)\ncan also be set.\n\n```python\nimport logging\n\n# A 32-bit-key used e.g. to encrypt the session cookie or for other cryptographic operations\nSECRET_KEY = 'devel'\n\n# Python standard library log level\nLOG_LEVEL = logging.WARN\n\n# Supported values: 'sqlite', 'mysql' or 'postgres'\nDB_DRIVER = 'mysql'\n\n# Host name of the database (ignored for DB_DRIVER = 'sqlite')\nDB_HOST = 'database.example.org'\n\n# Name of the Database on the host (for DB_DRIVER = 'sqlite', this is the 'path/to/db.sqlite')\nDB_NAME = 'gnucash_data'\n\n# Supported values: None, 'passthrough'. See below for details.\nAUTH_MECHANISM = None\n\n# The maximum number of transactions per page in the ledger\nTRANSACTION_PAGE_LENGTH = 25\n```\n\n### Running\n\nIt is not recommended to use the builtin Flask web server in production. *GnuCash Web*\ncomes as a [WSGI](https://wsgi.readthedocs.io/en/latest/) application, so there are [many\noptions](https://flask.palletsprojects.com/en/2.0.x/deploying/) available to run it.\n\nMost WSGI web server require setting a \"module\", which is the WSGI object that runs the\napp. For *GnuCash Web*, this is `gnucash_web.wsgi:app`.\n\nFor example, the following `.ini`-file might be used as a config for\n[uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/):\n\n```ini\n[uwsgi]\nmodule = gnucash_web.wsgi:app\npidfile = gnucash_web.pid\nmaster = true\nprocesses = 1\nhttp-socket = :8080\nchmod-socket = 660\nvacuum = true\n```\n\n### Initialising database\n\n*GnuCash Web* only works on a preexisting database. It is also currently not possible\nto create accounts. Therefore, you have to create a database and populate it with an\naccount hierarchy before you can use *GnuCash Web*.\n\nPreferably, you will use the official GnuCash desktop app to create a new\nbook. Simply select the appropriate database back end in the *Open*-dialog. You can\nalso migrate an existing GnuCash XML file to a database using *Save as*. More details\nand database considerations can be found in the official [GnuCash\ndocumentation](https://www.gnucash.org/docs/v4/C/gnucash-guide/basics-files1.html).\n\nAlternatively, you can also use *piecash* to create a new book, as is described in\ntheir [example\nsection](https://piecash.readthedocs.io/en/master/tutorial/examples.html#creating-and-opening-gnucash-files).\n\n### Authentication\n\nCurrently, there are only two authentication mechanisms supported, `None` and `'passthrough'`.\n\nWhen using no authentication, anyone can access the web interface and no credentials are\nprovided to the database host. This is generally only useful when using the sqlite\nback end (which does not accept credentials).\n\nWhen using pass-through authentication, *GnuCash Web* asks for username and password upon login,\nwhich are provided as credentials for the database hosts. They are also stored in an\nencrypted session cookie in the users browser. \"Logging out\" simply deletes the session\ncookie.\n\n\n\nDevelopment\n-----------\n\nInitialise submodules and install dependencies:\n```sh\n git submodule init\n git submodule update\n pip install -r requirements.txt\n\n```\n\nRun it:\n```sh\n export FLASK_APP=gnucash_web\n export FLASK_ENV=development\n flask run\n```\n\nBuild and upload package:\n```sh\n python -m build\n python -m twine upload dist/*\n```\n\nContributing\n------------\n\n**Development is at an early stage, but contributions are welcome.**\n\nThis is (currently) a personal project to play around with and satisfy my own everyday\nneeds and intellectual curiosity.\n\nSince *GnuCash Web* fulfills my primary use case for it, I don't expect much development\nin the near future. However, if anyone is willing to help taking this into a more\nfeature-rich direction, I am motivated to work on that.\n\nSee [Issues](https://github.com/joshuabach/gnucash-web/issues) and\n[Milestones](https://github.com/joshuabach/gnucash-web/milestones) for some ideas on how\nto get started.\n\nRelated Work\n------------\nThere seem to be few other projects in the same direction:\n\n- The GnuCash mailing list(s) has a few results\n - In 2003, [Martin asked about\n this](https://lists.gnucash.org/pipermail/gnucash-user/2003-July/007243.html) and\n was recommended to to use SSH+X-Forwarding to access his GnuCash database\n remotely.\n - In 2005, [Sachin said](https://lists.gnucash.org/pipermail/gnucash-user/2005-July/014163.html)\n they are planning to work on a web interface, but I could find no further results.\n - In 2012, [James\n posted](https://lists.gnucash.org/pipermail/gnucash-user/2012-March/043762.html)\n about his project\n [nylen/gnucash-django](https://github.com/nylen/gnucash-django), but the last\n commit is from 2015.\n- The [GnuCash Wiki's\n Wishlist](https://wiki.gnucash.org/wiki/WishList#Use_through_web_browser) lists the\n use through a web browser (as well as an iPhone-App) as \"WONTFIX\" (discussion from\n 2006/2007).\n- In 2016, mikedom722 asked on\n [Reddit](https://www.reddit.com/r/GnuCash/comments/3zlel3/gnucash_web_interface_useful/),\n whether anyone would be interested in a web interface (stating that he has one),\n but did not follow up.\n- In the same thread, superman279 presents his app [Remote\n GnuCash](https://github.com/justinhunt1223/remotegnucash), but the last commit is\n from 2017 and the website is down.\n- The [GnuCash Wiki](https://wiki.gnucash.org/wiki/GnuCash_and_Mobile_Devices)\n mentions two GnuCash mobile apps, one for iOS and one for Android. The one for\n Android seems to be discontinued (last commit 2020) the one for iOS still has new\n commits in 2022, but its purpose seems to be to export a CSV to be imported in\n GnuCash, rather then writing to the database directly.\n- There is\n [alensiljak/gnucash-portfolio-webui](https://github.com/alensiljak/gnucash-portfolio-webui)\n on GitHub, but the README does not clearly state what it does. It seems to be only a\n exporter for certain reports. Anyway, it was archived in 2022, with last commit\n from 2018.\n\nTo conclude, all projects in this direction seem to be at most prototypes for playing\naround and even those are scarce. The GnuCash dev-team itself doesn't seem to be keen\non providing a real mobile/web alternative, which is perfectly fine and\nunderstandable. I probably wouldn't either if I were them. Luckily, I am not!\n\nLicense\n-------\n\nCopyright \u00a9 2022 Joshua Bachmeier <joshua@bachmeier.cc>\n\nThis program is free software: you can redistribute it and/or modify it under the terms of\nthe GNU General Public License as published by the Free Software Foundation, either\nversion 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but **without any\nwarranty**; without even the implied warranty of **merchantability** or **fitness for a\nparticular purpose**. See the GNU General Public License for more details.\n\nSee [LICENSE](LICENSE) in this repository or https://www.gnu.org/licenses/ for a copy of\nthe GNU General Public License.\n\nThe contents of the submodules\n[EncryptedSession](https://github.com/SaintFlipper/EncryptedSession) (GPLv3),\n[Selectize](https://github.com/selectize/selectize.js) (Apache License 2.0),\n[Bootstrap](https://github.com/twbs/bootstrap) (MIT License) and\n[GnuCash](https://github.com/Gnucash/gnucash) (mutually-compatible set of licenses) as\nwell as all dependencies are published under their own licenses by their respective authors.\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "A simple, easy to use, mobile-friendly webinterface for GnuCash intended for self-hosting",
"version": "0.1.0",
"split_keywords": [
"bootstrap",
"flask",
"web",
"gnucash"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a45097edd49f6a510bf6c89c21fdb7dfabe403556f16910ec831a150bd38752d",
"md5": "4595358dbd04a6fb9331c9f483676377",
"sha256": "87510bd256cd0e2223e8e32eb379447cf3c5bf22cf80f1257ee2fb169a9216b9"
},
"downloads": -1,
"filename": "GnuCash_Web-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4595358dbd04a6fb9331c9f483676377",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 677126,
"upload_time": "2023-01-12T23:54:04",
"upload_time_iso_8601": "2023-01-12T23:54:04.738673Z",
"url": "https://files.pythonhosted.org/packages/a4/50/97edd49f6a510bf6c89c21fdb7dfabe403556f16910ec831a150bd38752d/GnuCash_Web-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "89974924b2670e915acacf59f71f86c5cfcb6a3798b92ba7f28969be3e653990",
"md5": "4c8c524a90a117a54e4eb3abb0bf1857",
"sha256": "c510b5449a898438e5c3baaf13a7bb732c3c0e4b2defe1f409f0786b94f64640"
},
"downloads": -1,
"filename": "GnuCash Web-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4c8c524a90a117a54e4eb3abb0bf1857",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 655248,
"upload_time": "2023-01-12T23:54:07",
"upload_time_iso_8601": "2023-01-12T23:54:07.043531Z",
"url": "https://files.pythonhosted.org/packages/89/97/4924b2670e915acacf59f71f86c5cfcb6a3798b92ba7f28969be3e653990/GnuCash%20Web-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-12 23:54:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "joshuabach",
"github_project": "gnucash-web",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "gnucash-web"
}
JSON
