Merge branch 'dev' of https://git.xdi.uevora.pt/mjsb/perguntations into dev

Miguel Barão
2 parents 981734c0 0b27f204
Showing 2 changed files with 84 additions and 77 deletions Show diff stats
README.md
package.json
@@ -11,26 +11,27 @@
 ## Requirements
-The webserver is a python application that requires `>=python3.7` and the package installer for python `pip`. The node package management `npm` is also necessary in order to install the javascript libraries.
+The webserver is a python application that requires `>=python3.8` and the
+package installer for python `pip`. The node package management `npm` is also
+necessary in order to install the javascript libraries.
 ```sh
 sudo apt install python3 python3-pip npm                     # Ubuntu
-sudo pkg install python37 py37-sqlite3 py37-pip npm          # FreeBSD
-sudo port install python37 py37-pip py37-setuptools npm6     # MacOS (macports)
+sudo pkg install python38 py38-sqlite3 py38-pip npm          # FreeBSD
+sudo port install python38 py38-pip py38-setuptools npm6     # MacOS (macports)
 ```
-To make the `pip` install packages to a local directory, the file `pip.conf` should be configured as follows:
+To make the `pip` install packages to a local directory, the file `pip.conf`
+should be configured as follows:
 ```ini
 [global]
 user=yes
-
-[list]
-format=columns
 ```
 This file is usually in `~/.config/pip/` in Linux and FreeBSD. In MacOS it's in
-`~/Library/Application Support/pip/`. You may have to create it, if it doesn't exist yet.
+`~/Library/Application Support/pip/`. You may have to create it, if it doesn't
+exist yet.
 ---
@@ -42,19 +43,21 @@ Download and install:
 git clone https://git.xdi.uevora.pt/mjsb/perguntations.git
 cd perguntations
 npm install
-pip3 install .
+pip install .
 ```
-The command `npm` installs the javascript libraries and then `pip3` installs the python webserver. This will also install any required dependencies.
+The command `npm` installs the javascript libraries and then `pip` installs the
+python webserver. This will also install any required dependencies.
-**Atention!** `pip3 install .` must run **after** `npm install`, otherwise the javascript libraries will not be found during the install.
+**Atention!** `pip install .` must be run **after** `npm install`, otherwise
+the javascript libraries will not be found during the install.
 ---
 ## Setup
-The server will run a `https` server and requires valid certificates.
-There are two possibilities to generate the certificates:
+The server will run a `https` server and requires valid certificates.  There
+are two possibilities to generate the certificates:
 - public server with static IP address and registered domain name;
 - private server on a local network isolated from the internet.
@@ -74,38 +77,35 @@ cd ~/.local/share/certs
 openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out cert.pem -days 365 -nodes
 ```
-To have a true certificate, like the ones issued by LetsEncrypt, the host
-must have a registered domain name.
-See instructions for FreeBSD at the end of this page.
+To have a true certificate, like the ones issued by LetsEncrypt, the host must
+have a registered domain name.  See instructions for FreeBSD at the end of this
+page.
 ---
 ## Running a demo
-The directory `demo` in the repository includes a demo test that can be used
-as a template for your own tests and questions.
-
-To run the demonstration test you need to initialize the database using one of
-the following methods:
+The directory `demo` in the repository includes a demo test that can be used as
+a template for your own tests and questions.  To run the demonstration test you
+need to initialize the database using one of the following methods:
 ```sh
 cd perguntations/demo
-
 initdb students.csv                 # initialize from a CSV file
 initdb --admin                      # only adds the administrator account
 initdb --add 123 "Asterix Gaules"   # add one student
 ```
 This will create or update a `students.db` file that contains a sqlite3
-database.
-The database stores user passwords and grades, but not the actual tests.
+database.  The database stores user passwords and grades, but not the actual
+tests.
-A test is specified in a single `yaml` file.
-The demo already includes the `demo.yaml` that you can play with.
+A test is specified in a single `yaml` file.  The file `demo.yaml` is a test
+specification that you can play with.
-The complete tests submitted by the students are stored in JSON files in the
-directory defined in `demo.yaml` under the option `answers_dir: ans`.
-We also have to create this directory manually:
+The answered tests submitted by the students are stored in JSON files in a
+directory defined in `demo.yaml` under the option `answers_dir: ans`.  We also
+have to create this directory manually:
 ```sh
 mkdir ans                           # directory where the tests will be saved
@@ -114,38 +114,36 @@ mkdir ans                           # directory where the tests will be saved
 Start the server and run the `demo.yaml` test:
 ```sh
-perguntations demo.yaml         # run demo test
+perguntations demo.yaml             # run demo test
 ```
 Several options are available, run `perguntations --help` for a list.
-The server listens on port 8443 of all IPs of all network interfaces.
-Open the browser at `http://127.0.0.1:8443/` and login as user number `0`
+The server listens on port 8443 of 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 you want. The password is defined on
 first login.
+
 After logging in, you will be redirected to the administration page that shows
 all the students and their current state.
 1. Authorize students by clicking the checkboxes.
 2. Open a different browser (or exit administrator) at `http://127.0.0.1:8443/`
-and login as one of the authorized students.
-Answer the questions and submit. You should get a grade at the end.
+   and login as one of the authorized students.  Answer the questions and
+   submit. You should get a grade at the end.
-The server can be stoped from the terminal with `^C`.
+The server can be stoped from the terminal with `^C` (Control+C).
 ---
 ## Running on lower ports
 Ports 80 and 443 are reserved for the root user and and this software **should
-NOT be run as root**.
-Instead, tcp traffic can be forwarded from port 443 to 8443 where the server is
-listening.
-The details depend on the operating system/firewall.
-
-### debian
+NOT be run as root**.  Instead, tcp traffic can be forwarded from port 443 to
+8443 where the server is listening.  The details depend on the operating
+system/firewall.
-FIXME: Untested
+### debian (FIXME: Untested)
 ```.sh
 iptables -t nat -I PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-ports 8443
@@ -166,25 +164,29 @@ Explanation:
 Edit `/etc/pf.conf`:
-    ext_if="wlan1"
-    rdr on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 port 8080
-    rdr on $ext_if proto tcp from any to any port 443 -> 127.0.0.1 port 8443
+```conf
+ext_if="wlan1"
+rdr on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 port 8080
+rdr on $ext_if proto tcp from any to any port 443 -> 127.0.0.1 port 8443
+```
-The `wlan1` should be the name of the network interface.
-Use `ext_if="vtnet0"` for guest additions under virtual box.
+The `wlan1` should be the name of the network interface.  Use `ext_if="vtnet0"`
+for guest additions under virtual box.
 Start firewall with `sudo service pf start`.
 Optionally, to activate pf on boot, edit `rc.conf`:
-    pf_enable="YES"
-    pf_flags=""
-    pf_rules="/etc/pf.conf"
+```conf
+pf_enable="YES"
+pf_flags=""
+pf_rules="/etc/pf.conf"
-    # optional logging:
-    pflog_enable="YES"
-    pflog_flags=""
-    pflog_logfile="/var/log/pflog"
+# optional logging:
+pflog_enable="YES"
+pflog_flags=""
+pflog_logfile="/var/log/pflog"
+```
 ## Generating certificates with LetsEncript (FreeBSD)
@@ -192,7 +194,7 @@ Generating certificates for a public server (FreeBSD) requires a registered
 domain with fixed IP.
 ```sh
-sudo pkg install py27-certbot                   # FreeBSD
+sudo pkg install py38-certbot                   # FreeBSD 13
 sudo service pf stop                            # disable pf firewall (FreeBSD)
 sudo certbot certonly --standalone -d www.example.com
 sudo service pf start                           # enable pf firewall
@@ -208,47 +210,52 @@ chmod 400 cert.pem privkey.pem
 Certificate renewals can be done as follows:
 ```sh
-sudo service pf stop   # shutdown firewall
+sudo service pf stop        # shutdown firewall
 sudo certbot renew
-sudo service pf start  # start firewall
+sudo service pf start       # start firewall
 ```
-Again, copy certificate files `privkey.pem` and `cert.pem` to `~/.local/share/certs`.
+Again, copy certificate files `privkey.pem` and `cert.pem` to
+`~/.local/share/certs`.
 ---
 ## Upgrading
-From time to time there can be updates to perguntations, python packages and javascript libraries.
-
-Python packages can be upgraded independently of the rest using pip:
+From time to time there can be updates to perguntations, python packages and
+javascript libraries.  Python packages can be upgraded independently of the
+rest using pip:
 ```sh
-pip list --outdated         # lists upgradable packages
+pip list --outdated --user  # lists upgradable packages
 pip install -U something    # upgrade something
 ```
+Attention: don't upgrade blindly. Some upgrades can be incompatible with
+perguntations and break things! All upgrades require testing of all the
+funcionalities.
+
 To upgrade perguntations and javascript libraries do:
 ```sh
 cd perguntations
 git pull                    # get latest version of perguntations
 npm update                  # get latest versions of javascript libraries
-pip3 install -U .           # upgrade perguntations
+pip install -U .            # upgrade perguntations
 ```
 ## Troubleshooting
 - The server tries to run `python3` so this command must be accessible from
-user accounts. Currently, the minimum supported python version is 3.7.
-
+  user accounts. Currently, the minimum supported python version is 3.8.
 - 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:
+  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: `sudo dpkg-reconfigure locales` and select your UTF-8 locales.
   - FreeBSD: edit `~/.login_conf` to use UTF-8, for example:
@@ -2,12 +2,12 @@
     "description": "Javascript libraries required to run the server",
     "email": "mjsb@uevora.pt",
     "dependencies": {
-        "@fortawesome/fontawesome-free": "^5.15.1",
-        "bootstrap": "^4.5",
-        "codemirror": "^5.58.1",
+        "@fortawesome/fontawesome-free": "^5.15.3",
+        "bootstrap": "^4.6.0",
+        "codemirror": "^5.61.1",
         "datatables": "^1.10",
-        "jquery": "^3.5.1",
-        "mathjax": "^3.1.2",
-        "underscore": "^1.11.0"
+        "jquery": "^3.6.0",
+        "mathjax": "^3.1.4",
+        "underscore": "^1.13.1"
     }
 }