README

1. Installation
2. Running a demo
3. 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)

pip install --user cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt

Installing packages in a virtual environment (alternative)

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

pip install cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt

Installing packages system wide (alternative)

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

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 directory demo includes a demo test that can be used as a template for your own tests and questions.

To run the demonstration test:

cd WHERE/YOU/INSTALLED/perguntations

# create and initialize database using one of the following methods:
./initdb.py students.csv    # from CSV file
./initdb.py --demo          # initialize with fake students
./initdb.py                 # empty
mv students.db demo/

# create directory to put the student's answered tests
mkdir demo/ans

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

We are now ready to run the server:

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

By default the server listens on all IPs of all network interfaces. Open the browser at http://127.0.0.1:8080/ and login as user number 0 (administrator) and choose any password. Then

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 ^C.

Running on port 80

Port 80 is reserved for the root user and and this software should NOT be run as root. Instead, the firewall should be configured to forward tcp traffic from port 80 to 8080 where the server is listening. The details depend on the operating system.

debian:

iptables -t nat -I PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-ports 8080

Explanation:

• -t nat is the table consulted when a packet creates a new connection.
• -I PREROUTING inserts rules at the head of the chain.
• -p tcp selected protocol.
• -s 0/0 source network address/mask.
• -i eth0 interface via which the packet was received.
• --dport 80 destination port.
• -j REDIRECT what to do when packet matches the rule.
• --to-ports 8080 where to redirect the packets.

freebsd

Todo...

Enabling SSL

Todo...

Troubleshooting

• The server tries to run python3. If only a python3.5 command is available, you need to set the default python using the OS package manager or manually create a symbolic link:

  • macOS/macports: sudo port select --set python3 python35
  • FreeBSD 11: cd /usr/local/bin; ln -s python3.5 python3

• 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