How to install and set up an `ftracker` instance
================================================

## Installation

There are 2 methods: Docker and Manual

Docker is usually easier and faster but might not suit your needs.

### Method A: Docker

Pull the container from docker hub using

```bash
sudo docker pull fasttube/ftracker
```

OR build the container locally with

```bash
sudo docker build . -t fasttube/ftracker
```

Then, if you want the container to also handle SSL so it can run standalone you
need to pass it a domain and email so it can obtain a certificate from `Let's
encrypt`. Use the first path in the `-v` option to point to your config file
(see below for customization options):

```bash
sudo docker run \
	-it --rm \
	--name ftracker \
	-e DOMAIN=example.com \
	-e LE_EMAIL=admin@example.com \
	-p 80:80 \
	-p 443:443 \
	-v /your/full/path/to/config.ini:/etc/ftracker/config.ini \
	fasttube/ftracker
```

Otherwise you can run it without SSL (maybe behind your own web+ssl server)
using just

```bash
sudo docker run \
	-it --rm \
	--name ftracker \
	-p 80:80 \
	-v /your/full/path/to/config.ini:/etc/ftracker/config.ini \
	fasttube/ftracker
```

If those work in the foreground and everything looks okay, you can start them
without `-it --rm` and with `-d` instead to run them in the background. Keep in
mind that it can take around 10 seconds to fully start.

To stop/start/uninstall the container afterwards, run:

```bash
sudo docker stop ftracker  # might take a few seconds
sudo docker start ftracker # continue running
sudo docker rm -f ftracker # uninstall
```

### Method B: Manual

#### 1. FTracker Backend

Install backend system wide:
```bash
# clone, cd into repo
sudo -H pip install . # Use -e if you want to hack on the backend while installed.
```

#### 2. WSGI Server + Service file

You need a WSGI Middleware (using `Flask`'s included `werkzeug` is discouraged
for production environments). I recommend `uwsgi` since it's flexible, fast and
has `nginx` integration. A sample configuration file as well as service
description files for both `systemd` and `rc` are included in `res/` for you to
adapt (file paths etc.) and install to your system (The `systemd` service file
still untested though, feel free to leave feedback).

#### 3. Webserver

You need a webserver. I recommend `nginx` because it's the industry standard
and fast. A sample config file is included in `res/` for you to adapt (domain,
SSL certs) and install to your system. The configuration should include:
Webroot in `web/` with a fallback to the WSGI handler for the backend.

Enabling SSL (https) and redirecting http to https is strongly encouraged, i
recommend using `Let's Encrypt`'s `certbot` to easily obtain certificates.

#### 4. Start/Restart

Edit `config.ini` to your liking. Restart the backend by restarting the `uwsgi`
service, e.g. `sudo systemctl restart ftracker` or `sudo service ftracker
restart`. see below for customization options.

## Customization

`ftracker` has a couple of ways you can make it your own. Here is a breakdown
of the functionalities.

The configuration file is in the `ini` format and all options are in the
`[global]` section. It should be placed in/mounted at
`/etc/ftracker/config.ini` or passed to the python module as the first
argument.

### Storage

`ftracker` uses `TinyDB` for data storage, which is essentially a `json` file.
For manual installations, you can decide where on your filesystem it should be
using the `db_file` option. We recommend something like `/var/ftracker/db.json`
for which you'd need to create the `/var/ftracker` directory and set its
permissions to your webserver user. The docker container handles this
internally.

### Data access

The 'data view' at `/view` is used to view the attendance data. It is protected
using a hard-configured username/password combo because i'm lazy and we didn't
need anything more fancy. We recommend you choose a safe, unguessable password
to protect the attendance data using the `admin_user` and `admin_pass` config
options. Please note: Location data is very sensitive data and has to be
handled carefully under the GDPR. Make sure all users know what happens to
their data and who has access to it.

### Guidelines

When arriving/signing in, users have to agree to a set of guidelines. Insert
a link to a publicly hosted version of your guideline document in the
`guideline_url` option to allow users to find it easily.

### List of allowed names

Some places might require all users arriving/signing in to be in a list of
pre-approved users (i.e. users that signed a permit). To block all names not in
such a list, provide a CSV file with all approved names (and optionally email
adresses for future features ;)) and enter the file's full location in the
`name_file` option. The recommended location is `/var/ftracker/namelist.csv` or
similar.

If you're using docker, you need to mount this file to the location specified
in `name_file` when `run`ning the container using an argument like `-v
/your/host/path/to/namelist.csv:/var/ftracker/namelist.csv`.

The CSV format is:

```
Jane,Doe,j.doe@example.com
First Name,Last Name,f.lastname@example.com
```

Users have to enter their full name like `Jane Doe` in order to be admitted.
The names are slugified for comparison, meaning case, accents and double spaces
are ignored (i.e.

```
jänE   doé
```

would still work, but `Jane D` wouldn't).

### Automatic data deletion (GDPR compliance)

The `delete_after_days` configuration option can be set to a number of days
after which attendance records are purged from the database. If it is not set
(or empty) automatic deletion is deactivated. Automatic deletion is final and
non-recoverable. This option is intended to help make the system fully GDPR
compliant by guaranteeing deletion after a certain period. Keep in mind that a
legally binding data protection guideline and user consent are still required.

### User notification on forgotten sign-out

`ftracker` is capable of notifying users if they forgot to sign-out at the end
of a day using modern web push notifications using the VAPID system. To make
this work, a few things are needed:

Firstly, you need an EC-Prime256v1 keypair in base64url encoding. If you're
using the Docker container, this is automatically generated for you. If not,
the easiest way to create one is to install the `web-push` `npm` package and
run it:

```bash
sudo npm install -g web-push
web-push generate-vapid-keys
```

The keys then need to be copied into the config options `push_public_key` and
`push_private_key` respectively so the backend can handle the rest.

Next, to be VAPID compliant you have to announce an contact address claim to
the push services so they can contact you if anything is going wrong with your
notifications. Do this by entering your email address as a `mailto:` link in
the `push_sender_info` option, like `mailto:it@fasttube.de`.

Finally, you can use the `notify_after_hrs` option to specify how long the
system should wait after a user's arrival to notify them of their missing
departure.