From 5dae401a2f5442b9481a94842e1fda354318e5f6 Mon Sep 17 00:00:00 2001 From: Miguel Barão Date: Sat, 20 Apr 2019 23:55:47 +0100 Subject: [PATCH] update README.md --- README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index b1bfa10..6bd2643 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,8 @@ ## Requirements -Before installing the server, we will need to install python3.7 with some additional packages, and npm (Node package management). +This application requires python3.7+ and a few additional python packages. +It also uses npm (Node package management) to install javascript libraries. ### Install python3.7 with sqlite3 support and npm @@ -34,16 +35,23 @@ This will install python locally under `~/.local/bin`. Make sure to add it to yo ### Install pip -If the `pip` command is not yet installed, run +If the `pip` command is not yet installed, run one of these: ```sh -python3.7 -m ensurepip --user +sudo apt install python3.7-pip # Ubuntu +sudo pkg py37-pip # FreeBSD +sudo port install py37-pip # MacOS +python3.7 -m ensurepip --user # otherwise ``` -This will install pip in your user account under `~/.local/bin`. -In the end you should be able to run `pip3 --version` and `python3 -c "import sqlite3"` without errors (sometimes `pip3` is `pip`, `pip3.7` or `pip-3.7`). +The latter will install `pip` in your user account under `~/.local/bin`. +In the end you should be able to run `pip3 --version` and +`python3 -c "import sqlite3"` without errors (sometimes `pip3` is `pip`, +`pip3.7` or `pip-3.7`). -If you want to always install python modules on the user account (recommended), edit the pip configuration file `~/.config/pip/pip.conf` (FreeBSD, Linux) or `Library/Application Support/pip/pip.conf` (MacOS) and add the lines +If you want to always install python modules on the user account (recommended), +edit the pip configuration file `~/.config/pip/pip.conf` (FreeBSD, Linux) or +`Library/Application Support/pip/pip.conf` (MacOS) and add the lines ```ini [global] @@ -55,8 +63,8 @@ user = yes Replace USER by your bitbucket username: ```sh -cd path/to/some/directory -git clone https://USER@bitbucket.org/mjsb/aprendizations.git +cd somewhere +git clone https://git.xdi.uevora.pt/mjsb/aprendizations.git cd aprendizations pip install . # install aprendizations and dependencies npm install # install javascript libraries @@ -68,18 +76,29 @@ Python packages are usually installed in: - `~/Library/python/3.7/lib/python/site-packages/` in MacOS. Javascript libraries are installed in `aprendizations/node_modules` directory. -This libraries are linked from the `aprendizations/aprendizations/static` directory. +This libraries have symbolic links from `aprendizations/aprendizations/static`. -At this point aprendizations can be run anywhere with the command `aprendizations`. +At this point aprendizations is installed in + +```sh +~/Library/Python/3.7/bin # MacOS +~/.local/bin # FreeBSD/Linux +``` + +and can be run with the command `aprendizations` (make sure this directory is +in your `$PATH`). ## Configuration ### Database -The user data is maintained in a sqlite3 database file. We first need to create the database: +The user data is maintained in a sqlite3 database file. We first need to create +the database. +At the moment, the database should be located in the same directory as the main +configuration file (see below). As an example, do ```sh -cd demo +cd demo # contains a small example initdb-aprendizations # show or initialize database initdb-aprendizations --admin # add admin user initdb-aprendizations inscricoes.csv # add students from CSV @@ -93,10 +112,12 @@ The default password is equal to the user name used to login. ### 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. +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. #### Selfsigned @@ -148,12 +169,19 @@ cd demo aprendizations demo.yaml ``` -and open a browser at [https://127.0.0.1:8443](). If it everything looks good, check at the correct address `https://www.example.com` (requires port forward in the firewall). The option `--debug` provides more verbose logging and might be useful during testing. +and open a browser at [https://127.0.0.1:8443](). If it everything looks good, +check at the correct address `https://www.example.com` (requires port forward +in the firewall). The option `--debug` provides more verbose logging and might +be useful during testing. The option `--check` generates all the questions once +before running the server to check for any obvious syntax error. ### Firewall configuration -Ports 80 and 443 are only usable by root. For security reasons it is better to run the server as an unprivileged user on higher ports like 8080 for http and 8443 for https. For this, we can configure port forwarding in the firewall to redirect incoming tcp traffic from 80 to 8080 and 443 to 8443. +Ports 80 and 443 are only usable by root. For security reasons it is better to +run the server as an unprivileged user on higher ports like 8080 for http and +8443 for https. For this, we can configure port forwarding in the firewall to +redirect incoming tcp traffic from 80 to 8080 and 443 to 8443. #### FreeBSD and pf @@ -185,14 +213,20 @@ Reboot or `sudo service pf start`. ## Troubleshooting -To help with troubleshooting, use the option `--debug` when running the server. This will increase logs in the terminal and will present the python exception errors in the browser. +To help with troubleshooting, use the option `--debug` when running the server. +This will increase logs in the terminal and will present the python exception +errors in the browser. -Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and `~/.config/aprendizations/logger-debug.yaml`. +Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and +`~/.config/aprendizations/logger-debug.yaml`. #### 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 exception. +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 +exception. - FreeBSD fix: edit `~/.login_conf` to use UTF-8, for example: -- libgit2 0.21.2