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

Miguel Barão
1 parent d23257c6
Showing 1 changed file with 36 additions and 21 deletions Show diff stats
README.md
@@ -10,8 +10,9 @@
 The webserver is a python application and requires `python3.6` and `pip` to be installed, plus the following additional packages:
-- CherryPy
-- Mako
+- ~~CherryPy~~
+- ~~Mako~~
+- tornado
 - Markdown
 - PyYAML
 - Pygments
@@ -23,7 +24,7 @@ These can be installed for a single user (recommended), in a python virtual envi
 #### Installing packages for a single user (recommended)
 ```.bash
-pip install --user cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt
+pip3 install --user tornado markdown pyyaml pygments sqlalchemy bcrypt
 ```
 #### Installing packages in a virtual environment (alternative)
@@ -32,7 +33,7 @@ pip install --user cherrypy mako markdown pyyaml pygments sqlalchemy bcrypt
 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
+pip3 install tornado markdown pyyaml pygments sqlalchemy bcrypt
 ```
 #### Installing packages system wide (alternative)
@@ -42,7 +43,9 @@ I personally prefer python packages to be installed for a single user, but if a 
 - Linux: apt-get, etc
 - macOS: macports, etc
-### Installing perguntations
+### Install and setup perguntations
+
+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:
 ```.bash
 cd WHERE/TO/PUT/THE/SOFTWARE
@@ -51,6 +54,25 @@ git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
 where USERNAME is your account on bitbucket.
+The server will run an https server and requires valid certificates.
+To generate certificates, there are two possibilities: public server with static IP address or a private server.
+
+#### Generating certificates for a public server
+
+For a public server, `letsencrypt` will allow a certificate to be generated.
+
+TODO: explain...
+
+Copy certificates `cert.crt` and `cert.key` to the `perguntations/certs/` directory.
+
+#### Generating self-signed certificates
+
+Self-signed certificates are not certified by a recognised authority and browsers will complain that the certificate is not trusted.
+
+TODO: explain...
+
+Copy certificates `cert.crt` and `cert.key` to the `perguntations/certs/` directory.
+
 ## Running a demo
 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
 # 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
+./initdb.py                 # only adds the administrator account
 mv students.db demo/
-# create directory to put the student's answered tests
+# create directory to save the student's tests
 mkdir demo/ans
 # edit test configuration and check if everything looks right
@@ -80,17 +102,17 @@ We are now ready to run the server:
 ./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
+By default the server listens on port 8443 and on all IPs of all network interfaces.
+Open the browser at `http://127.0.0.1:8443/` 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.
+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.
 The server can be stoped from the terminal with `^C`.
-## Running on port 80
+## Running on lower ports 80 or 443
-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.
+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.
 ### debian:
@@ -132,16 +154,9 @@ Edit `rc.conf`
 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`
-
+* The server tries to run `python3.6` so this command must be accessible from user accounts. 
 * 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.
@@ -162,4 +177,4 @@ Try running `locale` on the terminal and see if there are any error messages. So
 ### Contacts ###
-* Miguel Barão mjsb@di.uevora.pt
 \ No newline at end of file
+* Miguel Barão mjsb@uevora.pt
 \ No newline at end of file