Commit ec1dd9a64524ca20b717620918a6dde94ba844a2
Exists in
master
and in
1 other branch
Merge branch 'dev'
Showing
3 changed files
with
55 additions
and
37 deletions
Show diff stats
README.md
| 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 | ... | ... |
package-lock.json
| ... | ... | @@ -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", | ... | ... |
package.json
| ... | ... | @@ -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 | } | ... | ... |