- 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"
     }
 }
1	1	# User Manual
2	2
3	3	1. [Requirements](#requirements)
4		-1. [Installation](#installation)
5		-1. [Setup](#setup)
6		-1. [Running a demo](#running-a-demo)
7		-1. [Running on lower ports](#running-on-lower-ports)
8		-1. [Troubleshooting](#troubleshooting)
	4	+2. [Installation](#installation)
	5	+3. [Setup](#setup)
	6	+4. [Running a demo](#running-a-demo)
	7	+5. [Running on lower ports](#running-on-lower-ports)
	8	+6. [Troubleshooting](#troubleshooting)
9	9
10	10	---
11	11
12	12	## Requirements
13	13
14		-The webserver is a python application that requires `>=python3.7` and `pip` to
15		-be installed. Node package management `npm` is also necessary in order to
16		-install the javascript libraries.
	14	+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.
17	15
18		-```bash
19		-sudo apt install python3 python3-pip npm # Ubuntu
20		-sudo pkg install python37 py37-sqlite3 py37-pip npm # FreeBSD
21		-sudo port install python37 py37-pip py37-setuptools npm6 # MacOS
	16	+```sh
	17	+sudo apt install python3 python3-pip npm # Ubuntu
	18	+sudo pkg install python37 py37-sqlite3 py37-pip npm # FreeBSD
	19	+sudo port install python37 py37-pip py37-setuptools npm6 # MacOS (macports)
22	20	```
23	21
24		-The file `pip.conf` should be configured to the following:
	22	+To make the `pip` install packages to a local directory, the file `pip.conf` should be configured as follows:
25	23
26	24	```ini
27	25	[global]
...	...	@@ -32,7 +30,7 @@ format=columns
32	30	```
33	31
34	32	This file is usually in `~/.config/pip/` in Linux and FreeBSD. In MacOS it's in
35		-`~/Library/Application Support/pip/`.
	33	+`~/Library/Application Support/pip/`. You may have to create it, if it doesn't exist yet.
36	34
37	35	---
38	36
...	...	@@ -40,16 +38,16 @@ This file is usually in `~/.config/pip/` in Linux and FreeBSD. In MacOS it's in
40	38
41	39	Download and install:
42	40
43		-```bash
	41	+```sh
44	42	git clone https://git.xdi.uevora.pt/perguntations.git
45	43	cd perguntations
46	44	npm install
47		-pip3 install .
	45	+pip3 install . # this must come last
48	46	```
49	47
50		-The command `npm` installs the javascript libraries and `pip3` installs the
51		-python webserver.
52		-This will also install any required dependencies.
	48	+The command `npm` installs the javascript libraries and then `pip3` installs the python webserver. This will also install any required dependencies.
	49	+
	50	+Atention! `pip3 install .` must run after `npm install`, otherwise the javascript libraries will not be found during the install.
53	51
54	52	---
55	53
...	...	@@ -64,14 +62,14 @@ There are two possibilities to generate the certificates:
64	62	Certificates must be saved in the `$XDG_DATA_HOME` path if defined in the
65	63	environment, otherwise in `~/.local/share/certs` (I will assume the latter).
66	64
67		-```bash
	65	+```sh
68	66	mkdir -p ~/.local/share/certs
69	67	```
70	68
71	69	Self-signed certificates are not certified by a recognised authority and
72	70	browsers will complain that the certificate is not trusted. That's ok.
73	71
74		-```bash
	72	+```sh
75	73	cd ~/.local/share/certs
76	74	openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out cert.pem -days 365 -nodes
77	75	```
...	...	@@ -90,7 +88,7 @@ as a template for your own tests and questions.
90	88	To run the demonstration test you need to initialize the database using one of
91	89	the following methods:
92	90
93		-```bash
	91	+```sh
94	92	cd perguntations/demo
95	93
96	94	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
109	107	directory defined in `demo.yaml` under the option `answers_dir: ans`.
110	108	We also have to create this directory manually:
111	109
112		-```bash
	110	+```sh
113	111	mkdir ans # directory where the tests will be saved
114	112	```
115	113
116	114	Start the server and run the `demo.yaml` test:
117	115
118		-```bash
	116	+```sh
119	117	perguntations demo.yaml # run demo test
120	118	```
121	119
...	...	@@ -149,7 +147,7 @@ The details depend on the operating system/firewall.
149	147
150	148	FIXME: Untested
151	149
152		-```.bash
	150	+```.sh
153	151	iptables -t nat -I PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-ports 8443
154	152	```
155	153
...	...	@@ -219,6 +217,26 @@ Again, copy certificate files `privkey.pem` and `cert.pem` to `~/.local/share/ce
219	217
220	218	---
221	219
	220	+## Upgrading
	221	+
	222	+From time to time there can be updates to perguntations, python packages and javascript libraries.
	223	+
	224	+Python packages can be upgraded independently of the rest using pip:
	225	+
	226	+```sh
	227	+pip list --outdated # lists upgradable packages
	228	+pip install -U something # upgrade something
	229	+```
	230	+
	231	+To upgrade perguntations and javascript libraries do:
	232	+
	233	+```sh
	234	+cd perguntations
	235	+git pull # get latest version of perguntations
	236	+npm update # get latest versions of javascript libraries
	237	+pip3 install -U . # upgrade perguntations
	238	+```
	239	+
222	240	## Troubleshooting
223	241
224	242	- The server tries to run `python3` so this command must be accessible from
...	...
...	...	@@ -3,9 +3,9 @@
3	3	"lockfileVersion": 1,
4	4	"dependencies": {
5	5	"@fortawesome/fontawesome-free": {
6		- "version": "5.11.1",
7		- "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-free/-/fontawesome-free-5.11.1.tgz",
8		- "integrity": "sha512-DtXLVYAkDU0ce1cFUgLvZaMd1R2J/LviBYih9xr4ZLhQMrgvYX7w2vOxlpKLRALfIj5GyC5zoVrcACOkLcFgvg=="
	6	+ "version": "5.11.2",
	7	+ "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-free/-/fontawesome-free-5.11.2.tgz",
	8	+ "integrity": "sha512-XiUPoS79r1G7PcpnNtq85TJ7inJWe0v+b5oZJZKb0pGHNIV6+UiNeQWiFGmuQ0aj7GEhnD/v9iqxIsjuRKtEnQ=="
9	9	},
10	10	"bootstrap": {
11	11	"version": "4.3.1",
...	...	@@ -13,9 +13,9 @@
13	13	"integrity": "sha512-rXqOmH1VilAt2DyPzluTi2blhk17bO7ef+zLLPlWvG494pDxcM234pJ8wTc/6R40UWizAIIMgxjvxZg5kmsbag=="
14	14	},
15	15	"codemirror": {
16		- "version": "5.48.4",
17		- "resolved": "https://registry.npmjs.org/codemirror/-/codemirror-5.48.4.tgz",
18		- "integrity": "sha512-pUhZXDQ6qXSpWdwlgAwHEkd4imA0kf83hINmUEzJpmG80T/XLtDDEzZo8f6PQLuRCcUQhmzqqIo3ZPTRaWByRA=="
	16	+ "version": "5.49.0",
	17	+ "resolved": "https://registry.npmjs.org/codemirror/-/codemirror-5.49.0.tgz",
	18	+ "integrity": "sha512-Hyzr0HToBdZpLBN9dYFO/KlJAsKH37/cXVHPAqa+imml0R92tb9AkmsvjnXL+SluEvjjdfkDgRjc65NG5jnMYA=="
19	19	},
20	20	"commander": {
21	21	"version": "3.0.1",
...	...	@@ -63,9 +63,9 @@
63	63	"integrity": "sha512-yJxrWBHCjFZEHsZgfs7m5g9OSCNzsVYadW6f6lX3pgZL67vmodtSW/4zhsYmuDKweXfHs0M1kJge1uQIasWA+g=="
64	64	},
65	65	"popper.js": {
66		- "version": "1.15.0",
67		- "resolved": "https://registry.npmjs.org/popper.js/-/popper.js-1.15.0.tgz",
68		- "integrity": "sha512-w010cY1oCUmI+9KwwlWki+r5jxKfTFDVoadl7MSrIujHU5MJ5OR6HTDj6Xo8aoR/QsA56x8jKjA59qGH4ELtrA=="
	66	+ "version": "1.16.0",
	67	+ "resolved": "https://registry.npmjs.org/popper.js/-/popper.js-1.16.0.tgz",
	68	+ "integrity": "sha512-+G+EkOPoE5S/zChTpmBSSDYmhXJ5PsW8eMhH8cP/CQHMFPBG/kC9Y5IIw6qNYgdJ+/COf0ddY2li28iHaZRSjw=="
69	69	},
70	70	"speech-rule-engine": {
71	71	"version": "3.0.0-beta.6",
...	...
...	...	@@ -2,12 +2,12 @@
2	2	"description": "Javascript libraries required to run the server",
3	3	"email": "mjsb@uevora.pt",
4	4	"dependencies": {
5		- "@fortawesome/fontawesome-free": "^5.11.1",
	5	+ "@fortawesome/fontawesome-free": "^5.11.2",
6	6	"bootstrap": "^4.3",
7		- "codemirror": "^5.48",
	7	+ "codemirror": "^5.49.0",
8	8	"datatables": "^1.10",
9	9	"jquery": "^3.4.1",
10	10	"mathjax": "^3",
11		- "popper.js": "^1.15"
	11	+ "popper.js": "^1.16.0"
12	12	}
13	13	}
...	...