Miguel Barão / perguntations

Download as
Browse Code »

Commit 0fde12117eb5d46e525a9b8ccba7ac50a8a818dc

Authored by Miguel Barão
1 parent 4f413490
Exists in master and in 1 other branch dev

- README.md update

Showing 1 changed file with 41 additions and 11 deletions   Show diff stats
@@ -26,7 +26,7 @@ These can be installed for a single user (recommended), in a python virtual envi @@ -26,7 +26,7 @@ These can be installed for a single user (recommended), in a python virtual envi
26 pip install --user cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt 26 pip install --user cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt
27 ``` 27 ```
28 28
29 -#### Installing packages in a virtual environment 29 +#### Installing packages in a virtual environment (alternative)
30 30
31 ```.bash 31 ```.bash
32 pyvenv-3.5 venv/perguntations # or other virtualenv directory 32 pyvenv-3.5 venv/perguntations # or other virtualenv directory
@@ -35,7 +35,7 @@ source venv/perguntations/bin/activate # activate virtualenv @@ -35,7 +35,7 @@ source venv/perguntations/bin/activate # activate virtualenv
35 pip install cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt 35 pip install cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt
36 ``` 36 ```
37 37
38 -#### Installing packages system wide 38 +#### Installing packages system wide (alternative)
39 39
40 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`: 40 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`:
41 41
@@ -53,7 +53,9 @@ where USERNAME is your account on bitbucket. @@ -53,7 +53,9 @@ where USERNAME is your account on bitbucket.
53 53
54 ## Running a demo 54 ## Running a demo
55 55
56 -The following commands show how to run a demonstration test: 56 +The directory `demo` includes a demo test that can be used as a template for your own tests and questions.
  57 +
  58 +To run the demonstration test:
57 59
58 ```.bash 60 ```.bash
59 cd WHERE/YOU/INSTALLED/perguntations 61 cd WHERE/YOU/INSTALLED/perguntations
@@ -62,14 +64,13 @@ cd WHERE/YOU/INSTALLED/perguntations @@ -62,14 +64,13 @@ cd WHERE/YOU/INSTALLED/perguntations
62 ./initdb.py students.csv # from CSV file 64 ./initdb.py students.csv # from CSV file
63 ./initdb.py --demo # initialize with fake students 65 ./initdb.py --demo # initialize with fake students
64 ./initdb.py # empty 66 ./initdb.py # empty
65 -  
66 mv students.db demo/ 67 mv students.db demo/
67 68
  69 +# create directory to put the student's answered tests
  70 +mkdir demo/ans
  71 +
68 # edit test configuration and check if everything looks right 72 # edit test configuration and check if everything looks right
69 vi demo/test.yaml 73 vi demo/test.yaml
70 -  
71 -# edit server configuration and check if everything looks right  
72 -vi config/server.conf  
73 ``` 74 ```
74 75
75 We are now ready to run the server: 76 We are now ready to run the server:
@@ -79,18 +80,47 @@ We are now ready to run the server: @@ -79,18 +80,47 @@ We are now ready to run the server:
79 ./serve.py demo/test.yaml # run demo test 80 ./serve.py demo/test.yaml # run demo test
80 ``` 81 ```
81 82
82 -Open the browser at `http://127.0.0.1:8080/` and login as user number `0` (administrator) and: 83 +By default the server listens on all IPs of all network interfaces.
  84 +Open the browser at `http://127.0.0.1:8080/` and login as user number `0` (administrator) and choose any password. Then
83 85
84 1. Authorize students by clicking the checkboxes. 86 1. Authorize students by clicking the checkboxes.
85 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. 87 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.
86 88
87 -The server can be stoped from the terminal with <kbd>^C</kbd>. 89 +The server can be stoped from the terminal with `^C`.
  90 +
  91 +## Running on port 80
  92 +
  93 +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.
  94 +
  95 +### debian:
  96 +
  97 +```.bash
  98 +iptables -t nat -I PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-ports 8080
  99 +```
  100 +
  101 +Explanation:
  102 + - `-t nat` is the table consulted when a packet creates a new connection.
  103 + - `-I PREROUTING` inserts rules at the head of the chain.
  104 + - `-p tcp` selected protocol.
  105 + - `-s 0/0` source network address/mask.
  106 + - `-i eth0` interface via which the packet was received.
  107 + - `--dport 80` destination port.
  108 + - `-j REDIRECT` what to do when packet matches the rule.
  109 + - `--to-ports 8080` where to redirect the packets.
  110 +
  111 +### freebsd
  112 +
  113 +Todo...
  114 +
  115 +## Enabling SSL
  116 +
  117 +Todo...
88 118
89 ## Troubleshooting 119 ## Troubleshooting
90 120
91 * 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: 121 * 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:
92 - - macOS/macports: sudo port select --set python3 python35  
93 - - FreeBSD 11: cd /usr/local/bin; ln -s python3.5 python3 122 + - macOS/macports: `sudo port select --set python3 python35`
  123 + - FreeBSD 11: `cd /usr/local/bin; ln -s python3.5 python3`
94 124
95 * 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: 125 * 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:
96 - debian: fix it with `sudo dpkg-reconfigure locales`, select your UTF-8 locales and try again. 126 - debian: fix it with `sudo dpkg-reconfigure locales`, select your UTF-8 locales and try again.