FaSTTUBe
/
ftracker
50
1
Fork 0
Code Issues 2 Pull Requests Releases 1 Wiki Activity

Add customization manual (Resolves #18)

This commit is contained in:
Oskar Winkels 2020-12-15 23:09:33 +01:00
parent 5bb7df157c
commit 8c5e359f5b
2 changed files with 168 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
INSTALL.md Normal file
View File

@ -0,0 +1,163 @@
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
docker stop ftracker # might take a few seconds
docker start ftracker # continue running
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).

96
README.md
View File

@ -22,102 +22,16 @@ pip install -e .
python3 -m ftracker python3 -m ftracker
``` ```
Edit `config.ini` to tune your installation. Edit `config.ini` to tune your installation (see
[INSTALL.md #customization](https://git.fasttube.de/FaSTTUBe/ft-corona-tracker/src/branch/master/INSTALL.md#customization)
for customization options).
Then, point your browser at <http://localhost:5000/>. Then, point your browser at <http://localhost:5000/>.
## Installation/Deployment ## Installation/Deployment
There are 2 methods: Docker and Manual. See
[INSTALL.md](https://git.fasttube.de/FaSTTUBe/ft-corona-tracker/src/branch/master/INSTALL.md)
### 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:
```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
docker stop ftracker # might take a few seconds
docker start ftracker # continue running
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. Customization
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`
## Open Sources ## Open Sources