Newer
Older
# 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.
To make a development server run on localhost:
```python3
## 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
```
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. You can display the used paths and the resulting config by running `stechuhr_server/config.py test`):
```bash
/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
/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
```
Stechuhr-Server allows you to use _multiple_ configuration files, each overriding the previous one either in full or partly. In any case a default configuration is used, which might or might not fit your purpose (probably not).
Stechuhr-server will use _all_ *.toml files found in the specified directories in alphabetical order (e.g. `/etc/stechuhr-server`, for more see the config script below)
To maintain control a helper script exists at `stechuhr_server/config.py` which allows you to create a new config, print the currently used ones, etc. If your system python has the `toml` dependency installed run it using `python3 stechuhr_server/config.py` or `poetry run config`and it will display the help. If you _don't_ have the toml dependency installed you can:
1. Install it
2. Use the python in env (see installation above): `path/to/env/bin/python stechuhr_server/config.py`
3. Use python poetry: `poetry run config`
### Config section: 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.
Set the path to change where the database file is stored. Make sure that the path is writeable by the service user
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/)
### Config section: retention
You might not be allowed to keep the collected data around for later. Here you can specify the number of days you wanna keep the data around (in Germany this might be 28 days, but inform yourself). You will additionally need to [install the data retention script](#Data Retention)