The scalable version of Huishoudboekje the software, usable for all Dutch municipalities. Huishoudboekje is developed using the principles of Common Ground.
Huishoudboekje uses the following technical stack:
- Typescript, React
- Python, Flask
- NodeJS, Express
- Docker, Kubernetes
Huishoudboekje consists of several independent software components, packages as Docker containers. These are:
The architecture is currently undergoing improvements. New components:
All data for our own services is stored in a single PostgreSQL server.
Every service receives its own user and database to keep the data separated. The credentials are stored in secrets and can be mounted to build the connection.
The data models are managed using Alembic and Prisma migration scripts and that are executed using init containers.
Huishoudboekje uses symbolic links. If you're working on Windows, you need to explicitly enable symbolic links in Git, otherwise these links will just appear as text files and things will not work as expected.
Once symbolic links are enabled, please use
git clone -c core.symlinks=truewhen you clone this repository, and symlinks should be working.
Also, do make sure that (at least from Windows 11 onwards) Developer Mode had been turned on. See: Microsoft
To setup the frontend application, see the Frontend README.
To setup the backend applications, there are a few different ways you can set up your local backend development
environment:
-
Please make sure you have
docker-composeinstalled. It comes with Docker Desktop. -
Run
docker-compose up -dto launch all the services and the backend. This might take a few moments as the services execute some migrations on the database. -
Run
docker-compose -f docker-compose.dev.yaml up -dto launch all the services except the csharp services. For local development its easier to debug when these are run locally. -
Add the --build tag when you want all the containers to rebuild
-
It's best to run the frontend application natively on your system using NodeJS. For instructions see frontend/app/README.md
-
Run
docker-compose up sampledatato insert a small dataset into your system. Make sure you have all your services, a database and the backend running. -
Run
docker-compose up evaluate-alarmsto run the timed alarm evaluation. -
Run
docker-compose up generate-payment-instructionsto generate payment instructions for today.
- Run
docker-compose --profile tests upto run all tests. - Run
docker-compose run huishoudboekjeservice-testto run only tests for the huishoudboekjeservice. You can put any application that has tests here.
We really recommend using the Docker Compose setup, but if you want to run everything locally and manually, you can do so. To set up the backend manually you could also run the database locally and run the backend and services in separate virtual environments.
- Install a local PostgreSQL database.
On MacOS, you can use Postgres.app. Run
brew install libpqto be able to usepsql. - To make dealing with environment variables as easy as possible, install direnv.
- To start an application, see the README in the subdirectory of that application.
You need python virtualenv, a Ubuntu shell with zsh and you need to make sure your symlinks work correctly.
- To make sure your git installation had enabled symbolic links,
run
git clone -c core.symlinks=true https://gitlab.com/commonground/huishoudboekje/app-new.git. - Install PostgreSQL to setup a local database. Make sure to also install a database management application like pgAdmin, if you need a web client to manage your databases.
- Create virtual environments for the services and the backend. Please see each of their
README.mdfor instructions.
To install Huishoudboekje in production, the community provides Helm charts.