README.md

# Stechuhr-Server

The stechuhr system is a contract tracing solution created at HFBK-Hamburg. The students use their Mifare RFID cards to check in at one station when they enter a area and out once they leave. The checkin/checkouts are transfered to a server and stored in a SQLite database. The stations store no data at all.

The server software _stechuhr-server_ is programmed in python3 and uses Flask as a web frontend. Data is stored in a SQLite database.



## Run dev-server with poetry

To make a development server run on localhost:
```python3
export FLASK_APP=stechuhr_server/server.py
export FLASK_ENV=development
poetry run flask run --cert=adhoc
```

## Run with python3-ven in production

Make sure `python3-venv` is installed:

```bash
sudo apt install python3-venv
```

Then clone the repo and enter it:

```bash
git clone ssh://git@code.hfbk.net:4242/pandemic_response/stechuhr-server.git
cd stechuhr-server
```

Create a new venv environment, activate it, install the reuqirements from requirements.txt and start the server
```
python3 -m venv env
source env/bin/activate
pip3 install -r requirements.txt
python3 stechuhr_server/server.py
```



## Deployment

The _stechuhr-server_ is meant to run behind a reverse proxy server (e.g. NGINX) and as a systemd service on a Linux system. Gunicorn acts as a runner.

Follow the steps listed above in _Run with python3-ven in production_. To install the stechuhr server. If the software runs in an initial test we need to set up a production environment

1. Create a user called `wwwrun` 
2. Copy the systemd unit file `stechuhr-server.service` to `/etc/systemd/system/stechuhr-server.service` and have a look at it. Note the line where it says: 
    ```Environment="STECHUHR-SERVER_CONFIG_PATH=/etc/stechuhr-server/config.toml"```
    This is where the stechuhr-server default config will be created on first startup. Make sure the user `wwwrun` is allowed to write the file there`
3. Copy the stechuhr-server directory to `/srv/stechuhr-server`
4. Create the directory `/srv/stechuhr-data` and `chown wwwrun:wwwrun /srv/stechuhr-data`
5. Enable the service via `systemctl enable stechuhr-server`
6. Start the service via `systemctl start stechuhr-server`
7. Check the status via `systemctl status stechuhr-server` or display the log via `journalctl -fu stechuhr-server`

After first start the default config file should be created, have a look at it and change the defaults (e.g. with `vim /etc/stechuhr-server/config.toml`). To update the changes run `systemctl restart stechuhr-server`.

To make the server reachable from the outside a reverse proxy (like NGINX) needs to be setup. For this have a look at the example configuration file: `stechuhr.server.nginx.config` You may need to change a few things like the host or proxy_pass port.

### Data Retention

You may be required by law to delete data after a certain period of time. To do so a a data retention script can be found in `stechuhr_server/retention.py`. 

To run it once execute it with the python in your `env` directory like this (make sure to set the right config path, retention duration in days is read from there):

```bash
export STECHUHR-SERVER_CONFIG_PATH=/etc/stechuhr-server/config.toml
/path/to/my/install/stechuhr-server/env/bin/python stechuhr_server/retention.py
```

To add it as a cron job just create a script at `/etc/cron.daily/stechuhr_data_retention`, add the following contents:

```bash
#! /bin/bash
export STECHUHR-SERVER_CONFIG_PATH=/etc/stechuhr-server/config.toml
/path/to/my/install/stechuhr-server/env/bin/python stechuhr_server/retention.py
```

and finally make it executable with

```bash
chmod +x /etc/cron.daily/stechuhr_data_retention
```



## Configuration

### Application
Application related settings. Here the database can be exposed via a GET request for debugging purposes. Make sure this is off in production, or make sure no such http requests can be made from the public internet.

### Database

Set the path to change where the database file is stored. Make sure that the path is writeable by the service user

### ID verification

in `config.toml` you can add a list of regex patterns that stechuhr (*both on server and on client!*) uses to verify the Card IDs. These two patterns for example allow upper/lowercase hex strings with lengths either between 6 and 16 characters OR exactly 24 characters:

```toml
id_patterns = [
    "^806[A-Z0-9]{9}04$",
    "^FB6A1E60$",
    "^FB6D6950$",
    "^FB6A9DE0$",
    "^FB67D500$",
]
```

If in doubt consider [testing your regexes here](https://regexplained.com/)