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
README.md
  Diff comments   View file @0fde121
... ... @@ -26,7 +26,7 @@ These can be installed for a single user (recommended), in a python virtual envi
26 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 31 ```.bash
32 32 pyvenv-3.5 venv/perguntations # or other virtualenv directory
... ... @@ -35,7 +35,7 @@ source venv/perguntations/bin/activate # activate virtualenv
35 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 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 53  
54 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 60 ```.bash
59 61 cd WHERE/YOU/INSTALLED/perguntations
... ... @@ -62,14 +64,13 @@ cd WHERE/YOU/INSTALLED/perguntations
62 64 ./initdb.py students.csv # from CSV file
63 65 ./initdb.py --demo # initialize with fake students
64 66 ./initdb.py # empty
65   -
66 67 mv students.db demo/
67 68  
  69 +# create directory to put the student's answered tests
  70 +mkdir demo/ans
  71 +
68 72 # edit test configuration and check if everything looks right
69 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 76 We are now ready to run the server:
... ... @@ -79,18 +80,47 @@ We are now ready to run the server:
79 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 86 1. Authorize students by clicking the checkboxes.
85 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 119 ## Troubleshooting
90 120  
91 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 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 126 - debian: fix it with `sudo dpkg-reconfigure locales`, select your UTF-8 locales and try again.
... ...