Commit 31518d0c authored by rexxnor's avatar rexxnor

updated documentation and README, removed an unused md file

parent 7c644bad
[![pipeline status](https://git.chaostreffbern.ch/rexxnor/prepaid-mate-website/badges/master/pipeline.svg)](https://git.chaostreffbern.ch/rexxnor/prepaid-mate-website/commits/master)
[![coverage report](https://git.chaostreffbern.ch/rexxnor/prepaid-mate-website/badges/master/coverage.svg)](https://git.chaostreffbern.ch/rexxnor/prepaid-mate-website/commits/master)
# Prepaidmate Backend
This repository contains the backend codebase for the prepaidmatewebsite.
# Prepaidmate
This repository contains the full package needed to install, use and maintain a
Prepaidmate system.
## Administration Guide
To run this server you need to have a current version of python and django installed.
Further you will need to have python-pip and python-virtualenv installed.
Prepaidmate is a project developed for use within a club that allows solving
the problem of not having enough change to buy things, as well as providing a
way to pay on premise things without the need to always have cash on hand.
* Clone the repository to your computer.
```
git clone https://git.chaostreffbern.ch/rexxnor/prepaid-mate-website.git
```
* Change to the cloned repositories directory
```
cd prepaid-mate-website
```
* Make a virtual environment with the following command
```
python3 -m venv .venv
```
* Source the python virtualenvironment from the git root
```
source .venv/bin/activate
```
* Install required packages
```
pip install -r requirements.txt
```
* execute from the git root:
```
python prepaidmatewebsite/manage.py runserver
```
This will start up a test instance locally.
Now you can just connect to it via a browser at http://localhost:8000/
## Testing
To run tests run the following command when your Virtual environment is activated
```bash
python prepaidmatewebsite/manage.py test prepaid
```
Tests are all located in the directory prepaidmatewebsite/prepaid/tests.py
Therefore it is kept very basic and only allows spending in user specified
amounts according to price tags.
## User Documentation
All the following operations assume that you have openend the index page of a
Prepaidmate instance.
### Buying something
* User clicks on "Buy something"
* User specifies an amount
* Clicks on OK
* User enters their User ID
* Selects second input box
* User enters their PIN
* Clicks on OK
* Remaining Balance is shown to user with link to add funds
* User specifies an amount
* Clicks on OK
* Confirmation box with amount is shown to user
* Clicks on OK
* Remaining Balance is shown to user
* After 10 seconds the user is automatically redirected to the index.html
### Checking Balance
......@@ -60,7 +35,7 @@ Tests are all located in the directory prepaidmatewebsite/prepaid/tests.py
* Selects second input box
* User enters their PIN
* Clicks on OK
* User is presented with their current balance and link to add funds
* User is presented with their current balance
* After 10 seconds the user is redirected to the index.html
### Adding funds
......@@ -70,5 +45,156 @@ Tests are all located in the directory prepaidmatewebsite/prepaid/tests.py
* Funds are added and the user is shown their current balance
* After 10 seconds the user automatically is redirected to the index.html
### Generating the monthly report
* Generate the report via /generatereport/
## Developer Guide
The setup for developers is quite simple, as it behaves like a standard django
environment. A template settings.py file is provided within the directory
structure.
### Directories
Django has a rather unintuitive directory structure. The most important
directories are the following:
```shell
# Contains the entire codebase
prepaidmatewebsite/
# app prepaid with all associated files including models, views, etc.
prepaidmatewebsite/prepaid/
# contains all the root configuration and url file
prepaidmatewebsite/prepaidmatewebsite/
```
If you want to change the application logic, the changes need to be made within
the prepaid app and not withing the prepaidmatewebsite root project folder.
### Development Setup
To set up a development environment, execute the following commands on your
system:
```shell
# clone the repository
git clone https://git.chaostreffbern.ch/rexxnor/prepaid-mate-website.git
cd prepaid-mate-website
# create python virtualenv and install required packages
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# create database and start development server
python prepaidmatewebsite/manage.py migrate
python prepaidmatewebsite/manage.py runserver
```
This will start up a test instance locally.
Now you can just connect to it via a browser at http://localhost:8000/
With the provided settings.py file sqlite is used as a database backend and with
the migrate command the database will be created if it does not already exist.
### Testing
To run tests, run the following command when your Virtual environment is activated
```shell
python prepaidmatewebsite/manage.py test prepaid
```
Tests are all located in the directory prepaidmatewebsite/prepaid/tests.py
## Installation Guide
For installation on Debian and Debian-like systems, there are several ansible
playbooks included within the `ansible/` directory that allow easy installation
on these systems.
Of course you can install it by hand but this is not covered here.
### Installation using sqlite database
* Clone the repository to your computer.
```shell
git clone https://git.chaostreffbern.ch/rexxnor/prepaid-mate-website.git
cd prepaid-mate-website
cd ansible
# add hosts as desired to the hosts file with a username
[prepaidmate]
127.0.0.1 ansible_user=admin
# run the installstandalone playbook (use -K if you need to pass sudo password)
ansible-playbook -i hosts installstandalone.yml
```
After the playbook has run successfully, your instance of Prepaidmate should be
ready and browsable. You might need to change up some values in the
settings.py.j2 template, located at `ansible/teamplates/settings.py.j2`. Namely
the allowed hosts directive is important to allow for custom URLs.
## Administrator Guide
So you now have installed Prepaidmate on a system but are not sure how to manage
and maintain it.
First of all you need an admin user to be able to create cards and manage your
users. Also if someone wants to change their pin number, you need an admin user
for this.
```shell
# create super user (needs user input)
python prepaidmatewebsite/manage.py createsuperuser
```
After that you can login in the `/admin/` page of your local instance with the
credentials you just specified. There you will see a listing with the app
'prepaid' and Cards. Click on add and for the username, enter a numerical value
that does not exist yet, and a (nick)name for the user. If you want to have a
correct reporting system, do not set the balance of a user here. It has to be
numerical as the frontend only allows the input of numbers when using a
touchscreen.
Click on save or save and add another to add the user to the database. Now for
giving the user a password, you will need to go back to the main administration
page and click on "Change" in the "Administration and Authorization" part of the
site, in the line "Users".
Then you will see the all the users on your system, including the superusers.
Click on the recently created user and in the password section, there is a link
called "this form". Click on this and set the users pin.
The pin you enter needs to be a SHA256 hash of a numerical value (as only
numerical values can be entered using the touchscreen). There is this very
simple and easy script that generates the hash on user input which can be found
below. Simply enter this hash into both password and repeat password fields and
click "Change Password".
```bash
#!/bin/bash
echo "enter a pin"
read -s pin
echo -n "$pin" | sha256sum
unset pin
```
Now the user can charge their balance using the frontend of the system and start
using the system as intended.
### Reporting
Prepaidmate comes with three very handy reporting tools. First of all is a
report that shows all the relevant information in the current fiscal period.
This view can be opened when logged in as a superuser when visiting the URL
`/admin/prepaid/report/currentreport/`. This presents the superuser with the
current balance on all cards, as well as how much balance has been charged
within this period and how much money has been spent. When clicking the green
"Commit" button, the superuser is prompted with a dialog to ensure that no
accidental click occurred.
After a commit the superuser is redirected to
`/admin/prepaid/report/periodreport/$i/` where $i is the ID of the report just
generated.
These reports can be printed directly or printed to PDF format. They allow clean
accounting for the maintainers.
Furthermore, there are two views that allow viewing of monthly and yearly
reports on spending and charging. These can be accessed under
`/admin/prepaid/report/monthlyreport/$year/$month` and
`/admin/prepaid/report/yearlyreport/$year/` respectively. Obviously, you will
need change $year and $month to values you want.
# User documentation for using this django app
There are three different views defined on the Django side.
- validatepin
- buydrink
- generatereport
## validatepin
This view can be called via the url http://<Server-IP>/prepaid/validatepin/?ean=<ean-number of card to valiate>&pin=<sha256sum of pin>
Depending on the validity of the submitted input it will return a success or fail.
## buydrink
This view can be called via the url http://<Server-IP>/prepaid/buydrink/?drinkean=<ean-number of drink>&pin=<sha256sum of pin>&cardean=<cardean>
It will check multiple criteria for validity before actually doing the transaction.
After checking all necessary values for validity a Transaction is entered into the database.
Thereafter the amount will also be subtracted from the cards current balance.
## generatereport
This view is called via the url http://<Server-IP>/prepaid/generatereport/
In the future this will return the sum of all transactions within the last month. Or alternatively of this month.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment