ftracker/INSTALL.md

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

sudo docker pull fasttube/ftracker

OR build the container locally with

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):

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

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:

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:

# 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 running 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:

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.