Miguel Barão / perguntations

Download as
Browse Code »

Commit 77ef8d7abf14fcb986a510116dfd316fda9e020a

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

- updated README.md documentation to the new tornado server.

Showing 1 changed file with 36 additions and 21 deletions   Show diff stats
README.md
  Diff comments   View file @77ef8d7
... ... @@ -10,8 +10,9 @@
10 10  
11 11 The webserver is a python application and requires `python3.6` and `pip` to be installed, plus the following additional packages:
12 12  
13   -- CherryPy
14   -- Mako
  13 +- ~~CherryPy~~
  14 +- ~~Mako~~
  15 +- tornado
15 16 - Markdown
16 17 - PyYAML
17 18 - Pygments
... ... @@ -23,7 +24,7 @@ These can be installed for a single user (recommended), in a python virtual envi
23 24 #### Installing packages for a single user (recommended)
24 25  
25 26 ```.bash
26   -pip install --user cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt
  27 +pip3 install --user tornado markdown pyyaml pygments sqlalchemy bcrypt
27 28 ```
28 29  
29 30 #### Installing packages in a virtual environment (alternative)
... ... @@ -32,7 +33,7 @@ pip install --user cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt
32 33 pyvenv-3.6 venv/perguntations # or other virtualenv directory
33 34 source venv/perguntations/bin/activate # activate virtualenv
34 35  
35   -pip install cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt
  36 +pip3 install tornado markdown pyyaml pygments sqlalchemy bcrypt
36 37 ```
37 38  
38 39 #### Installing packages system wide (alternative)
... ... @@ -42,7 +43,9 @@ I personally prefer python packages to be installed for a single user, but if a
42 43 - Linux: apt-get, etc
43 44 - macOS: macports, etc
44 45  
45   -### Installing perguntations
  46 +### Install and setup perguntations
  47 +
  48 +There is no installer, pip or otherwise. It's still in development and has to be run from sources. Use `git` to get the sources:
46 49  
47 50 ```.bash
48 51 cd WHERE/TO/PUT/THE/SOFTWARE
... ... @@ -51,6 +54,25 @@ git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
51 54  
52 55 where USERNAME is your account on bitbucket.
53 56  
  57 +The server will run an https server and requires valid certificates.
  58 +To generate certificates, there are two possibilities: public server with static IP address or a private server.
  59 +
  60 +#### Generating certificates for a public server
  61 +
  62 +For a public server, `letsencrypt` will allow a certificate to be generated.
  63 +
  64 +TODO: explain...
  65 +
  66 +Copy certificates `cert.crt` and `cert.key` to the `perguntations/certs/` directory.
  67 +
  68 +#### Generating self-signed certificates
  69 +
  70 +Self-signed certificates are not certified by a recognised authority and browsers will complain that the certificate is not trusted.
  71 +
  72 +TODO: explain...
  73 +
  74 +Copy certificates `cert.crt` and `cert.key` to the `perguntations/certs/` directory.
  75 +
54 76 ## Running a demo
55 77  
56 78 The directory `demo` includes a demo test that can be used as a template for your own tests and questions.
... ... @@ -63,10 +85,10 @@ cd WHERE/YOU/INSTALLED/perguntations
63 85 # create and initialize database using one of the following methods:
64 86 ./initdb.py students.csv # from CSV file
65 87 ./initdb.py --demo # initialize with fake students
66   -./initdb.py # empty
  88 +./initdb.py # only adds the administrator account
67 89 mv students.db demo/
68 90  
69   -# create directory to put the student's answered tests
  91 +# create directory to save the student's tests
70 92 mkdir demo/ans
71 93  
72 94 # edit test configuration and check if everything looks right
... ... @@ -80,17 +102,17 @@ We are now ready to run the server:
80 102 ./serve.py demo/test.yaml # run demo test
81 103 ```
82 104  
83   -By default the server listens on port 8080 and 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
  105 +By default the server listens on port 8443 and on all IPs of all network interfaces.
  106 +Open the browser at `http://127.0.0.1:8443/` and login as user number `0` (administrator) and choose any password. Then
85 107  
86 108 1. Authorize students by clicking the checkboxes.
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.
  109 +2. Open a different browser at `http://127.0.0.1:8443/` and login as one of the authorized students. Answer the questions and submit.
88 110  
89 111 The server can be stoped from the terminal with `^C`.
90 112  
91   -## Running on port 80
  113 +## Running on lower ports 80 or 443
92 114  
93   -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.
  115 +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 443 to 8443 where the server is listening. The details depend on the operating system.
94 116  
95 117 ### debian:
96 118  
... ... @@ -132,16 +154,9 @@ Edit `rc.conf`
132 154  
133 155 Reboot.
134 156  
135   -## Enabling SSL
136   -
137   -Todo...
138   -
139 157 ## Troubleshooting
140 158  
141   -* 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:
142   - - macOS/macports: `sudo port select --set python3 python36`
143   - - FreeBSD 11: `cd /usr/local/bin; ln -s python3.6 python3`
144   -
  159 +* The server tries to run `python3.6` so this command must be accessible from user accounts.
145 160 * 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.
146 161 Try running `locale` on the terminal and see if there are any error messages. Solutions:
147 162 - debian: fix it with `sudo dpkg-reconfigure locales`, select your UTF-8 locales and try again.
... ... @@ -162,4 +177,4 @@ Try running `locale` on the terminal and see if there are any error messages. So
162 177  
163 178 ### Contacts ###
164 179  
165   -* Miguel Barão mjsb@di.uevora.pt
166 180 \ No newline at end of file
  181 +* Miguel Barão mjsb@uevora.pt
167 182 \ No newline at end of file
... ...