diff --git a/README.md b/README.md index 55a1cf5..4326ab6 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ These can be installed for a single user (recommended), in a python virtual envi pip install --user cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt ``` -#### Installing packages in a virtual environment +#### Installing packages in a virtual environment (alternative) ```.bash pyvenv-3.5 venv/perguntations # or other virtualenv directory @@ -35,7 +35,7 @@ source venv/perguntations/bin/activate # activate virtualenv pip install cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt ``` -#### Installing packages system wide +#### 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`: @@ -53,7 +53,9 @@ where USERNAME is your account on bitbucket. ## Running a demo -The following commands show how to run a demonstration test: +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: ```.bash cd WHERE/YOU/INSTALLED/perguntations @@ -62,14 +64,13 @@ cd WHERE/YOU/INSTALLED/perguntations ./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 - -# edit server configuration and check if everything looks right -vi config/server.conf ``` We are now ready to run the server: @@ -79,18 +80,47 @@ We are now ready to run the server: ./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: +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. +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: + +```.bash +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 + - 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. -- libgit2 0.21.2