# README #

1. [Installation](#installation)
2. [Running a demo](#running-a-demo)
3. [Troubleshooting](#troubleshooting)

## Installation

### Requirements

The webserver is a python application and requires `python3.5` and `pip` to be installed, plus the following additional packages:

- CherryPy
- Mako
- Markdown
- PyYAML
- Pygments
- SQLAlchemy
- bcrypt

These can be installed for a single user (recommended), in a python virtual environment or system wide.

#### Installing packages for a single user (recommended)

```.bash
pip install --user cherrypy
pip install --user mako
pip install --user markdown
pip install --user pyyaml
pip install --user pygments
pip install --user sqlalchemy
pip install --user bcrypt
```

#### Installing packages in a virtual environment

```.bash
pyvenv-3.5 venv/perguntations              # or other virtualenv directory
source venv/perguntations/bin/activate     # activate virtualenv

pip install cherrypy
pip install mako
pip install markdown
pip install pyyaml
pip install pygments
pip install sqlalchemy
pip install bcrypt
```

#### Installing packages system wide

I personally prefer python packages to be installed for a single user, but if a system wide installation is required, it is probably better to use the operating system package manager instead of `pip`:

- Linux: apt-get, etc
- macOS: macports, etc

### Installing perguntations

```.bash
cd WHERE/TO/PUT/THE/SOFTWARE
git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
```

where USERNAME is your account on bitbucket.

## Running a demo

The following commands will show how to run a demonstration test:

```.bash
cd WHERE/YOU/INSTALLED/perguntations

# create database.
# a database with fake students is created if no CSV file is provided
./initdb.py OPTIONAL_CSV_FILE
mv students.db demo/

# edit test configuration and check if everything looks right
vi demo/test.yaml

# edit server configuration and check if everything looks right
vi config/server.conf
```

We are now ready to run the server:

```.bash
./serve.py --help            # get help
./serve.py demo/test.yaml    # run demo test
```

Open the browser at `http://127.0.0.1:8080/` and login as user number `0` (administrator) and:

1. Authorize students by clicking the checkboxes.
2. Open a different browser at `http://127.0.0.1:8080/` and login as one of the authorized students. Answer the questions and submit.

The server can be stoped from the terminal with <kbd>^C</kbd>.

## Troubleshooting

* If you are getting any `UnicodeEncodeError` type of errors that's because the terminal is not supporting UTF-8. Try running `locale` on the terminal and see if there is any error messages. Solutions:
    - debian: fix it with `sudo dpkg-reconfigure locales`, select your UTF-8 locales and try again.

## Contribute ###

* Writing questions in yaml format
* Testing and reporting bugs
* Code review
* New features and ideas

### Contacts ###

* Miguel Barão mjsb@di.uevora.pt