Developer Documentation

To get started with development first clone the repository.

git clone https://github.com/stustapay/stustapay.git

Developing on your local machine

Install system requirements:

• python >= 3.11
• nodejs >= 18
• docker (optional, recommended for running postgresql in a docker container)

Setup Backend for Development

Create a python virtualenv

python3 -m virtualenv -p python3 .venv
source .venv/bin/activate

Install backend python module as a local editable python module. This will install all python requirements needed for development and testing as well.

pip install -e '.[dev,test]'

You should now have the stustapay command available.

Setup the database

Start a local postgres instance via docker compose.

docker compose -f docker/docker-compose.devel.yaml up

This will start a postgresql instance and bind it to the local port 5433 (to not conflict with already locally running postgres databases on the default port.)

Use an already running local postgresql instance

Another option is to run a local postgresql instance.

In that case you have to take care of setting up a database user and database yourself. You'll probably want to copy etc/config.devel.yaml and adapt the database connection settings.

Apply the database schema

stustapay -c etc/config.devel.yaml db migrate

Now you're mostly set up and ready to start developing and using the backend.

Head over to the simulator docs to see how to generate test data and obtain a somewhat realistic test setup.

Setup web frontend for development

To install the web ui requirements run

cd web
npm install

Running

To start the administration web and customer web interfaces in development mode (supports live code reloading) run

npx nx serve administration
npx nx serve customerportal

Other usefull commands for development (where project is either customerportal or administration) are

npx nx build <project>
npx nx lint <project>

Formatting, Linting and Testing

# check format
make check-format
# format code
make format
# run linters
make lint
# run tests (nondocker based postgres instance only)
make tests

When using a docker based postgres instance as mentioned above, start the docker compose setup and run the tests using the following commands:

docker compose -f docker/docker-compose.devel.yaml up
TEST_DB_USER=stustapay_test TEST_DB_PASSWORD=stustapay_test TEST_DB_HOST=localhost TEST_DB_DATABASE=stustapay_test TEST_DB_PORT=5434 make test

Developing in a devcontainer

You can use vscode's development containers, we've included a configuration file in the repo root.

After starting the devcontainer you can simply start up the core services and the web uis.

When using DevContainer make sure to forward the port globally. Otherwise the till will not be able to connect. In the VSCode Settings set Remote: Local Port Host to allInterfaces

Troubles with the database? Connect to the database in the devcontainer pstgres-data (below dev volumes), then drop and re-create the schema.

1. su - postgres -c psql
2. drop schema public cascade;
3. create schema public;