From 79aee4f3998254f9b1f891a35135029bcdfdcf7f Mon Sep 17 00:00:00 2001 From: Miguel Barão Date: Thu, 8 Jul 2021 20:00:54 +0100 Subject: [PATCH] update README.md --- README.md | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------------------------------------------------------- mypy.ini | 2 +- 2 files changed, 86 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index 345ded3..660b363 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,53 @@ # Getting Started +Latest review: 2021-07-08 ## Installation To complete the installation we will need to perform the following steps: -1. install python3.7, pip and npm -1. download aprendizations from the repository -1. install javascript libraries (with npm) -1. install aprendizations (with pip) -1. generate SSL certificates -1. configure the firewall (optional) +1. install python3, pip and npm +2. download aprendizations from the repository +3. install javascript libraries (with npm) +4. install aprendizations (with pip) +5. generate SSL certificates +6. configure the firewall (optional) To use the software we need to: 1. initialize database -1. go to the demo directory (or an existing course) -1. run `aprendizations demo.yaml` +2. go to the demo directory (or an existing course) +3. run `aprendizations demo.yaml` Each of these steps is explained below. -### Install python3.7 with sqlite3 support and npm +### Install python3 with sqlite3 support and npm -Python can be installed either from the system package management or compiled from sources. +Python can be installed either from the system package management or compiled +from sources. #### Installing from the system package manager ```sh -sudo apt install python3.7 npm # Linux (Ubuntu) -sudo pkg install python37 py37-sqlite3 npm # FreeBSD -sudo port install python37 npm6 # MacOS +sudo pkg install python3 npm # FreeBSD +sudo apt install python3 npm # Linux (Ubuntu) +sudo port install python38 npm7 # MacOS ``` -#### Installing from source +In FreeBSD also install `py3X-sqlite3` where `X` is the python version. + +#### Installing from source (outdated) Make sure that the build tools and libraries are installed: ```sh # Ubuntu: -sudo apt install build-essential libssl-dev zlib1g-dev libncurses5-dev libncursesw5-dev libreadline-dev libsqlite3-dev libgdbm-dev libdb5.3-dev libbz2-dev libexpat1-dev liblzma-dev tk-dev libffi-dev +sudo apt install build-essential libssl-dev zlib1g-dev libncurses5-dev \ + libncursesw5-dev libreadline-dev libsqlite3-dev libgdbm-dev libdb5.3-dev \ + libbz2-dev libexpat1-dev liblzma-dev tk-dev libffi-dev ``` -Download python from [http://www.python.org]() and +Download [python](http://www.python.org) and ```sh tar xvfJ Python-3.7.tar.xz @@ -50,30 +56,25 @@ cd Python-3.7 make && make install ``` -This will install python locally under `~/.local/bin`. Make sure to add it to your `PATH` in `~/.profile`. If `~/bin` is already in the path, you may just make a symbolic link `ln -s ~/.local/bin ~/bin`. +This will install python locally under `~/.local/bin`. Make sure to add it to +your `PATH` in `~/.profile`. If `~/bin` is already in the path, just make a +symbolic link `ln -s ~/.local/bin ~/bin`. ### Install pip -Python usually includes pip which is accessible through `python -m pip install something`, but it's also convenient to have the `pip` command directly available in the terminal. -To install `pip` from the system package manager: - -```sh -sudo apt install python3.7-pip # Ubuntu 19.04+ -sudo pkg py37-pip # FreeBSD -sudo port install py37-pip # MacOS -``` - -otherwise run: +Install `pip` from the system package manager: ```sh -python3.7 -m pip install pip # install in user area +sudo apt install python3-pip # Ubuntu +sudo pkg py38-pip # FreeBSD +sudo port install py39-pip # MacOS ``` -The latter will install `pip` in your user account under `~/.local/bin`. -In the end you should be able to run `pip --version` and -`python3 -c "import sqlite3"` without errors. -Sometimes the `pip` command is named `pip3`, -`pip3.7` or `pip-3.7`. +Then run `python3 -m pip install -U pip` to install latest version into your +user account under `~/.local/bin`. +In the end you should be able to run `pip --version` and `python3 -c "import +sqlite3"` without errors. +In some systems, `pip` can be named `pip3`, `pip3.8` or `pip-3.8`. Edit the configuration file `~/.config/pip/pip.conf` (FreeBSD, Linux) or `Library/Application Support/pip/pip.conf` (MacOS) and add the lines @@ -85,7 +86,7 @@ user = yes This will set pip to install modules in the user area (recommended). -### Download and install aprendizations: +### Download and install aprendizations ```sh git clone https://git.xdi.uevora.pt/mjsb/aprendizations.git @@ -94,20 +95,23 @@ npm install # install javascript libraries pip install . # install aprendizations and dependencies ``` -Javascript libraries are installed in `aprendizations/node_modules` and are linked from `aprendizations/aprendizations/static`. +Javascript libraries are installed in `aprendizations/node_modules` and are +linked from `aprendizations/aprendizations/static`. Python packages are usually installed in: -- `~/.local/lib/python3.7/site-packages/` in Linux/FreeBSD. -- `~/Library/python/3.7/lib/python/site-packages/` in MacOS. +* `~/.local/lib/python3.8/site-packages/` in Linux/FreeBSD. +* `~/Library/python/3.9/lib/python/site-packages/` in MacOS. -When aprendizations is installed with pip, all the dependencies are also installed. The javascript libraries previously installed with npm are copied to the above directory and the cloned repository is no longer needed. +When aprendizations is installed with pip, all the dependencies are also +installed. The javascript libraries previously installed with npm are copied to +the above directory and the cloned repository is no longer needed. At this point `aprendizations` is installed in ```sh ~/.local/bin # Linux/FreeBSD -~/Library/Python/3.7/bin # MacOS +~/Library/Python/3.9/bin # MacOS ``` and can be run from the terminal: @@ -119,10 +123,12 @@ aprendizations --help ### SSL Certificates -We need certificates for https. Certificates can be self-signed or validated by a trusted authority. +We need certificates for https. Certificates can be self-signed or validated by +a trusted authority. Self-signed can be used locally for development and testing, but browsers will -complain. LetsEncrypt issues trusted and free certificates, but the server must have a registered publicly accessible domain name. +complain. LetsEncrypt issues trusted and free certificates, but the server must +have a registered publicly accessible domain name. #### Generating selfsigned certificates @@ -137,18 +143,21 @@ openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out cert.pem -days 365 - Install the certbot from LetsEncrypt: ```sh -sudo pkg install py36-certbot # FreeBSD +sudo pkg install py38-certbot # FreeBSD sudo apt install certbot # Ubuntu ``` -To generate or renew the certificates, ports 80 and 443 have to be accessible. **The firewall and webserver have to be stopped**. +To generate or renew the certificates, ports 80 and 443 must be accessible. +**Any firewall and webserver have to be stopped**. ```sh sudo certbot certonly --standalone -d www.example.com # first time sudo certbot renew # renew ``` -Certificates are saved under `/usr/local/etc/letsencrypt/live/www.example.com/`. Copy them to `~/.local/share/certs` and change permissions to be readable: +Certificates are saved under +`/usr/local/etc/letsencrypt/live/www.example.com/`. Copy them to +`~/.local/share/certs` and change permissions to be readable: ```sh cd ~/.local/share/certs @@ -157,14 +166,13 @@ sudo cp /usr/local/etc/letsencrypt/live/www.example.com/privkey.pem . chmod 400 cert.pem privkey.pem ``` - ## Configuration ### Database -User data is maintained in a sqlite3 database which has to be created manually using the `initdb-aprendizations` command. -The database file should be located in the same directory as the main -YAML configuration file. +User data is maintained in a sqlite3 database which has to be created manually +using the `initdb-aprendizations` command. The database file should be located +in the same directory as the main YAML configuration file. For example, to run the included demo do: @@ -180,10 +188,10 @@ initdb-aprendizations --help # for available options The default password is equal to the user name, if left undefined. - ### Running the demo -The application includes a small example in `demo/demo.yaml` that can be used for initial testing. Run it with +The application includes a small example in `demo/demo.yaml` that can be used +for initial testing. Run it with ```sh cd demo @@ -193,13 +201,14 @@ aprendizations demo.yaml Open the browser at [https://127.0.0.1:8443](https://127.0.0.1:8443). If everything looks good, check at the correct address `https://www.example.com:8443`. -The option `--debug` provides more verbose logging and might -be useful during testing. +The option `--debug` provides more verbose logging and might be useful during +testing. ### Firewall configuration -Ports 80 and 443 are only usable by root. For security reasons the server runs as an unprivileged user on port 8443 for https. -To access the server in the default https port (443), port forwarding can be configured in the firewall. +Ports 80 and 443 are only usable by root. For security reasons the server runs +as an unprivileged user on port 8443 for https. To access the server in the +default https port (443), port forwarding must be configured in the firewall. #### FreeBSD and pf @@ -232,14 +241,14 @@ Reboot or `sudo service pf start`. Make sure the following steps have been done: -- installed python3.7, pip and npm -- git-cloned the aprendizations from the main repository -- installed javascript libraries with npm -- installed aprendizations with pip -- initialized database with at least 1 user -- generate and copy certificates to the appropriate place -- (optional) configure the firewall to do port forwarding -- run `aprendizations demo.yaml --check` +* installed python3, pip and npm +* git-cloned the aprendizations from the main repository +* installed javascript libraries with npm +* installed aprendizations with pip +* initialized database with at least 1 user +* generate and copy certificates to the appropriate place +* (optional) configure the firewall to do port forwarding +* run `aprendizations demo.yaml --check` ## Keeping aprendizations updated @@ -249,7 +258,7 @@ To update aprendizations to the latest version do: cd aprendizations git pull # get latest version npm update # update javascript libraries -pip install -U . # updates installed version to latest +pip install -U . # updates installed version ``` ## Troubleshooting @@ -261,16 +270,17 @@ errors in the browser. Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and `~/.config/aprendizations/logger-debug.yaml`. -If these files do not yet exist, there are examples in `aprendizations/config` that can be copied to `~/.config/aprendizations`. +If these files do not yet exist, there are examples in `aprendizations/config` +that can be copied to `~/.config/aprendizations`. -#### UnicodeEncodeError +### UnicodeEncodeError The server should not generate this error, but when using external scripts to generate questions or to correct, these scripts can print unicode strings to -stdout. If the terminal does not support unicode, python will generate this +stdout. If the terminal does not support unicode, python will generate an exception. -- FreeBSD fix: edit `~/.login_conf` to use UTF-8, for example: +* FreeBSD fix: edit `~/.login_conf` to use UTF-8, for example: ```sh me:\ @@ -278,10 +288,9 @@ me:\ :lang=en_US.UTF-8: ``` -- Debian fix: check `locale`... +* Debian fix: check `locale`... - -#### The application runs but questions do not show up +### The application runs but questions do not show up Some operating systems have an option to disable animations to try to avoid motion sickness in some people. Browsers will check this option with the OS and @@ -290,12 +299,11 @@ these will will not work and nothing is shown on the page. To fix this issue you need to allow animations in the Operating System: -- On windows 10, go to System Preferences, search for "Show animations in +* On windows 10, go to System Preferences, search for "Show animations in windows" and turn it **ON**. -- On MacOS or iOS search for reduced motion and switch it **OFF** +* On MacOS or iOS search for reduced motion and switch it **OFF** (Preferences -> Acessibility -> Display -> Reduce motion). - ## FAQ Common database manipulations: @@ -312,8 +320,10 @@ Some common database queries: sqlite3 students.db "select distinct student_id from studenttopic" # How many topics has each student done? -sqlite3 students.db "select student_id, count(topic_id) from studenttopic group by student_id order by count(topic_id) desc" +sqlite3 students.db "select student_id, count(topic_id) from studenttopic \ + group by student_id order by count(topic_id) desc" # Which questions have more wrong answers? -sqlite3 students.db "select count(ref), ref from answers where grade<1.0 group by ref order by count(ref) desc" +sqlite3 students.db "select count(ref), ref from answers where grade<1.0 \ + group by ref order by count(ref) desc" ``` diff --git a/mypy.ini b/mypy.ini index 2f66baf..e7ab926 100644 --- a/mypy.ini +++ b/mypy.ini @@ -1,5 +1,5 @@ [mypy] -python_version = 3.7 +python_version = 3.8 warn_return_any = True warn_unused_configs = True -- libgit2 0.21.2