README

1. Installation
2. Running a demo
3. Troubleshooting

Installation

Requirements

The webserver is a python application and requires python3.6 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.6 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 port 8080 and 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

Ports 80 and 443 are 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 and pf

Edit /etc/pf.conf:

ext_if="em0"
rdr on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 port 8080
rdr on $ext_if proto tcp from any to any port 443 -> 127.0.0.1 port 8443

or ext_if="vtnet0" for guest additions under virtual box.

Edit rc.conf

pf_enable="YES"
pf_flags=""
pf_rules="/etc/pf.conf"

# optional logging:
pflog_enable="YES"
pflog_flags=""
pflog_logfile="/var/log/pflog"

Reboot.

Enabling SSL

Todo...

Troubleshooting

• The server tries to run python3. If only a python3.6 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 python36
  • FreeBSD 11: cd /usr/local/bin; ln -s python3.6 python3

• If you are getting any UnicodeEncodeError type of errors that's because the terminal is not supporting UTF-8. This error may occur when a unicode character is printed to the screen by the server or, when running question generator or correction scripts, a message is piped between the server and the scripts that includes unicode characters. Try running locale on the terminal and see if there are any error messages. Solutions:

  • debian: fix it with sudo dpkg-reconfigure locales, select your UTF-8 locales and try again.

  • FreeBSD: edit ~/.login_conf to use UTF-8, for example:

    me:\
            :charset=UTF-8:\
            :lang=en_US.UTF-8:
    

Contribute

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

Contacts

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