update documentation

Miguel Barão
1 parent 8d260b30
Showing 2 changed files with 64 additions and 40 deletions Show diff stats
README.md
aprendizations/main.py
 # Getting Started
+
+## 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. initialize database
 1. generate SSL certificates
 1. configure the firewall (optional)
-1. try running `aprendizations demo.yaml`
-These steps are explained next in detail.
+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`
+
+Each of these steps is explained below.
 ### Install python3.7 with sqlite3 support and npm
@@ -47,16 +54,21 @@ This will install python locally under `~/.local/bin`. Make sure to add it to yo
 ### 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 installed. 
-If the `pip` command is not yet installed, run one of these:
+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+
-python3.7 -m pip install pip       # Ubuntu 18.04
 sudo pkg py37-pip                  # FreeBSD
 sudo port install py37-pip         # MacOS
 ```
+otherwise run:
+
+```sh
+python3.7 -m pip install pip        # install in user area
+```
+
 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.
@@ -73,7 +85,7 @@ user = yes
 This will set pip to install modules in the user area (recommended).
-### Install aprendizations and dependencies:
+### Download and install aprendizations:
 ```sh
 git clone https://git.xdi.uevora.pt/mjsb/aprendizations.git
@@ -82,8 +94,7 @@ npm install             # install javascript libraries
 pip install .           # install aprendizations and dependencies
 ```
-Javascript libraries are initially installed in `aprendizations/node_modules` directory.
-These libraries already have symbolic links 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:
@@ -92,7 +103,7 @@ Python packages are usually installed in:
 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
+At this point `aprendizations` is installed in
 ```sh
 ~/.local/bin                          # Linux/FreeBSD
@@ -106,29 +117,6 @@ aprendizations --version
 aprendizations --help
 ```
-## Configuration
-
-### Database
-
-User data is maintained in a sqlite3 database which has to be created manually using the command `initdb-aprendizations`.
-The database file should be located in the same directory as the main 
-YAML configuration file.
-
-For example, to run the included demo do:
-
-```sh
-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
-initdb-aprendizations --add 1184 "Aladino da Silva"   # add new user
-initdb-aprendizations --update 1184 --pw alibaba      # update password
-initdb-aprendizations --help          # for available options
-```
-
-The default password is equal to the user name, if left undefined.
-
-
 ### SSL Certificates
 We need certificates for https. Certificates can be self-signed or validated by a trusted authority.
@@ -150,7 +138,7 @@ Install the certbot from LetsEncrypt:
 ```sh
 sudo pkg install py36-certbot       # FreeBSD
-sudo apt install certbot            # Linux Ubuntu
+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. 
@@ -168,6 +156,30 @@ 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.
+
+For example, to run the included demo do:
+
+```sh
+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
+initdb-aprendizations --add 1184 "Aladino da Silva"   # add new user
+initdb-aprendizations --update 1184 --pw alibaba      # update password
+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
@@ -178,7 +190,7 @@ aprendizations demo.yaml
 ```
 Open the browser at [https://127.0.0.1:8443](https://127.0.0.1:8443). 
-If it everything looks good, check at the correct address 
+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.
@@ -198,7 +210,7 @@ rdr on $ext_if proto tcp from any to any port 80 -&gt; 127.0.0.1 port 8080
 rdr on $ext_if proto tcp from any to any port 443 -> 127.0.0.1 port 8443
 ```
-Under virtualbox with guest additions use `ext_if="vtnet0"`.
+Virtualbox with guest additions uses `ext_if="vtnet0"`.
 Edit `/etc/rc.conf`
@@ -228,6 +240,17 @@ Make sure the following steps have been done:
 - (optional) configure the firewall to do port forwarding
 - run `aprendizations demo.yaml --check`
+## Keeping aprendizations updated
+
+To update aprendizations to the latest version do:
+
+```sh
+cd aprendizations
+git pull                # get latest version
+npm update              # update javascript libraries
+pip install -U .        # updates installed version to latest
+```
+
 ## Troubleshooting
 To help with troubleshooting, use the option `--debug` when running the server. 
@@ -186,16 +186,17 @@ def main():
         logging.critical(f'SSL certificates missing in {certs_dir}')
         print('--------------------------------------------------------------')
         print('Certificates should be issued by a certificate authority (CA),')
-        print('such as https://letsencrypt.org, and then copied to:          ')
-        print('                                                              ')
-        print(f'  {certs_dir:<62}')
-        print('                                                              ')
+        print('such as https://letsencrypt.org.                              ')
         print('For testing purposes a selfsigned certificate can be generated')
         print('locally by running:                                           ')
         print('                                                              ')
         print('  openssl req -x509 -newkey rsa:4096 -keyout privkey.pem \\   ')
         print('          -out cert.pem -days 365 -nodes                      ')
         print('                                                              ')
+        print('Copy the cert.pem and privkey.pem files to:                   ')
+        print('                                                              ')
+        print(f'  {certs_dir:<62}')
+        print('                                                              ')
         print('--------------------------------------------------------------')
         sys.exit(1)