- updates README.md

- updates javascript libraries

- updates README.md
- updates javascript libraries
Miguel Barão
1 parent e4b33601
Showing 3 changed files with 55 additions and 37 deletions Show diff stats
README.md
package-lock.json
package.json
 # User Manual
 1. [Requirements](#requirements)
-1. [Installation](#installation)
-1. [Setup](#setup)
-1. [Running a demo](#running-a-demo)
-1. [Running on lower ports](#running-on-lower-ports)
-1. [Troubleshooting](#troubleshooting)
+2. [Installation](#installation)
+3. [Setup](#setup)
+4. [Running a demo](#running-a-demo)
+5. [Running on lower ports](#running-on-lower-ports)
+6. [Troubleshooting](#troubleshooting)
 ---
 ## Requirements
-The webserver is a python application that requires `>=python3.7` and `pip` to 
-be installed. Node package management `npm` is also necessary in order to 
-install the javascript libraries.
+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.
-```bash
-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
+```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)
 ```
-The file `pip.conf` should be configured to the following:
+To make the `pip` install packages to a local directory, the file `pip.conf` should be configured as follows:
 ```ini
 [global]
@@ -32,7 +30,7 @@ format=columns
 ```
 This file is usually in `~/.config/pip/` in Linux and FreeBSD. In MacOS it's in
-`~/Library/Application Support/pip/`.
+`~/Library/Application Support/pip/`. You may have to create it, if it doesn't exist yet.
 ---
@@ -40,16 +38,16 @@ This file is usually in `~/.config/pip/` in Linux and FreeBSD. In MacOS it&#39;s in
 Download and install:
-```bash
+```sh
 git clone https://git.xdi.uevora.pt/perguntations.git
 cd perguntations
 npm install
-pip3 install .
+pip3 install .        # this must come last
 ```
-The command `npm` installs the javascript libraries and `pip3` installs the
-python webserver.
-This will also install any required dependencies.
+The command `npm` installs the javascript libraries and then `pip3` 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.
 ---
@@ -64,14 +62,14 @@ There are two possibilities to generate the certificates:
 Certificates must be saved in the `$XDG_DATA_HOME` path if defined in the
 environment, otherwise in `~/.local/share/certs` (I will assume the latter).
-```bash
+```sh
 mkdir -p ~/.local/share/certs
 ```
 Self-signed certificates are not certified by a recognised authority and
 browsers will complain that the certificate is not trusted. That's ok.
-```bash
+```sh
 cd ~/.local/share/certs
 openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out cert.pem -days 365 -nodes
 ```
@@ -90,7 +88,7 @@ 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:
-```bash
+```sh
 cd perguntations/demo
 initdb students.csv                 # initialize from a CSV file
@@ -109,13 +107,13 @@ 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:
-```bash
+```sh
 mkdir ans                           # directory where the tests will be saved
 ```
 Start the server and run the `demo.yaml` test:
-```bash
+```sh
 perguntations demo.yaml         # run demo test
 ```
@@ -149,7 +147,7 @@ The details depend on the operating system/firewall.
 FIXME: Untested
-```.bash
+```.sh
 iptables -t nat -I PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-ports 8443
 ```
@@ -219,6 +217,26 @@ Again, copy certificate files `privkey.pem` and `cert.pem` to `~/.local/share/ce
 ---
+## 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:
+
+```sh
+pip list --outdated         # lists upgradable packages
+pip install -U something    # upgrade something 
+```
+
+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
+```
+
 ## Troubleshooting
 - The server tries to run `python3` so this command must be accessible from
@@ -3,9 +3,9 @@
   "lockfileVersion": 1,
   "dependencies": {
     "@fortawesome/fontawesome-free": {
-      "version": "5.11.1",
-      "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-free/-/fontawesome-free-5.11.1.tgz",
-      "integrity": "sha512-DtXLVYAkDU0ce1cFUgLvZaMd1R2J/LviBYih9xr4ZLhQMrgvYX7w2vOxlpKLRALfIj5GyC5zoVrcACOkLcFgvg=="
+      "version": "5.11.2",
+      "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-free/-/fontawesome-free-5.11.2.tgz",
+      "integrity": "sha512-XiUPoS79r1G7PcpnNtq85TJ7inJWe0v+b5oZJZKb0pGHNIV6+UiNeQWiFGmuQ0aj7GEhnD/v9iqxIsjuRKtEnQ=="
     },
     "bootstrap": {
       "version": "4.3.1",
@@ -13,9 +13,9 @@
       "integrity": "sha512-rXqOmH1VilAt2DyPzluTi2blhk17bO7ef+zLLPlWvG494pDxcM234pJ8wTc/6R40UWizAIIMgxjvxZg5kmsbag=="
     },
     "codemirror": {
-      "version": "5.48.4",
-      "resolved": "https://registry.npmjs.org/codemirror/-/codemirror-5.48.4.tgz",
-      "integrity": "sha512-pUhZXDQ6qXSpWdwlgAwHEkd4imA0kf83hINmUEzJpmG80T/XLtDDEzZo8f6PQLuRCcUQhmzqqIo3ZPTRaWByRA=="
+      "version": "5.49.0",
+      "resolved": "https://registry.npmjs.org/codemirror/-/codemirror-5.49.0.tgz",
+      "integrity": "sha512-Hyzr0HToBdZpLBN9dYFO/KlJAsKH37/cXVHPAqa+imml0R92tb9AkmsvjnXL+SluEvjjdfkDgRjc65NG5jnMYA=="
     },
     "commander": {
       "version": "3.0.1",
@@ -63,9 +63,9 @@
       "integrity": "sha512-yJxrWBHCjFZEHsZgfs7m5g9OSCNzsVYadW6f6lX3pgZL67vmodtSW/4zhsYmuDKweXfHs0M1kJge1uQIasWA+g=="
     },
     "popper.js": {
-      "version": "1.15.0",
-      "resolved": "https://registry.npmjs.org/popper.js/-/popper.js-1.15.0.tgz",
-      "integrity": "sha512-w010cY1oCUmI+9KwwlWki+r5jxKfTFDVoadl7MSrIujHU5MJ5OR6HTDj6Xo8aoR/QsA56x8jKjA59qGH4ELtrA=="
+      "version": "1.16.0",
+      "resolved": "https://registry.npmjs.org/popper.js/-/popper.js-1.16.0.tgz",
+      "integrity": "sha512-+G+EkOPoE5S/zChTpmBSSDYmhXJ5PsW8eMhH8cP/CQHMFPBG/kC9Y5IIw6qNYgdJ+/COf0ddY2li28iHaZRSjw=="
     },
     "speech-rule-engine": {
       "version": "3.0.0-beta.6",
@@ -2,12 +2,12 @@
     "description": "Javascript libraries required to run the server",
     "email": "mjsb@uevora.pt",
     "dependencies": {
-        "@fortawesome/fontawesome-free": "^5.11.1",
+        "@fortawesome/fontawesome-free": "^5.11.2",
         "bootstrap": "^4.3",
-        "codemirror": "^5.48",
+        "codemirror": "^5.49.0",
         "datatables": "^1.10",
         "jquery": "^3.4.1",
         "mathjax": "^3",
-        "popper.js": "^1.15"
+        "popper.js": "^1.16.0"
     }
 }
	@@ -2,12 +2,12 @@		@@ -2,12 +2,12 @@
2	"description": "Javascript libraries required to run the server",	2	"description": "Javascript libraries required to run the server",
3	"email": "mjsb@uevora.pt",	3	"email": "mjsb@uevora.pt",
4	"dependencies": {	4	"dependencies": {
5	- "@fortawesome/fontawesome-free": "^5.11.1",	5	+ "@fortawesome/fontawesome-free": "^5.11.2",
6	"bootstrap": "^4.3",	6	"bootstrap": "^4.3",
7	- "codemirror": "^5.48",	7	+ "codemirror": "^5.49.0",
8	"datatables": "^1.10",	8	"datatables": "^1.10",
9	"jquery": "^3.4.1",	9	"jquery": "^3.4.1",
10	"mathjax": "^3",	10	"mathjax": "^3",
11	- "popper.js": "^1.15"	11	+ "popper.js": "^1.16.0"
12	}	12	}
13	}	13	}