Miguel Barão / aprendizations

Download as
Browse Code »

Commit 5dae401a2f5442b9481a94842e1fda354318e5f6

Authored by Miguel Barão
1 parent fc1563cc
Exists in master and in 1 other branch dev

update README.md

Showing 1 changed file with 54 additions and 20 deletions   Show diff stats
README.md
  Diff comments   View file @5dae401
... ... @@ -3,7 +3,8 @@
3 3  
4 4 ## Requirements
5 5  
6   -Before installing the server, we will need to install python3.7 with some additional packages, and npm (Node package management).
  6 +This application requires python3.7+ and a few additional python packages.
  7 +It also uses npm (Node package management) to install javascript libraries.
7 8  
8 9 ### Install python3.7 with sqlite3 support and npm
9 10  
... ... @@ -34,16 +35,23 @@ This will install python locally under `~/.local/bin`. Make sure to add it to yo
34 35  
35 36 ### Install pip
36 37  
37   -If the `pip` command is not yet installed, run
  38 +If the `pip` command is not yet installed, run one of these:
38 39  
39 40 ```sh
40   -python3.7 -m ensurepip --user
  41 +sudo apt install python3.7-pip # Ubuntu
  42 +sudo pkg py37-pip # FreeBSD
  43 +sudo port install py37-pip # MacOS
  44 +python3.7 -m ensurepip --user # otherwise
41 45 ```
42 46  
43   -This will install pip in your user account under `~/.local/bin`.
44   -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`).
  47 +The latter will install `pip` in your user account under `~/.local/bin`.
  48 +In the end you should be able to run `pip3 --version` and
  49 +`python3 -c "import sqlite3"` without errors (sometimes `pip3` is `pip`,
  50 +`pip3.7` or `pip-3.7`).
45 51  
46   -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
  52 +If you want to always install python modules on the user account (recommended),
  53 +edit the pip configuration file `~/.config/pip/pip.conf` (FreeBSD, Linux) or
  54 +`Library/Application Support/pip/pip.conf` (MacOS) and add the lines
47 55  
48 56 ```ini
49 57 [global]
... ... @@ -55,8 +63,8 @@ user = yes
55 63 Replace USER by your bitbucket username:
56 64  
57 65 ```sh
58   -cd path/to/some/directory
59   -git clone https://USER@bitbucket.org/mjsb/aprendizations.git
  66 +cd somewhere
  67 +git clone https://git.xdi.uevora.pt/mjsb/aprendizations.git
60 68 cd aprendizations
61 69 pip install . # install aprendizations and dependencies
62 70 npm install # install javascript libraries
... ... @@ -68,18 +76,29 @@ Python packages are usually installed in:
68 76 - `~/Library/python/3.7/lib/python/site-packages/` in MacOS.
69 77  
70 78 Javascript libraries are installed in `aprendizations/node_modules` directory.
71   -This libraries are linked from the `aprendizations/aprendizations/static` directory.
  79 +This libraries have symbolic links from `aprendizations/aprendizations/static`.
72 80  
73   -At this point aprendizations can be run anywhere with the command `aprendizations`.
  81 +At this point aprendizations is installed in
  82 +
  83 +```sh
  84 +~/Library/Python/3.7/bin # MacOS
  85 +~/.local/bin # FreeBSD/Linux
  86 +```
  87 +
  88 +and can be run with the command `aprendizations` (make sure this directory is
  89 +in your `$PATH`).
74 90  
75 91 ## Configuration
76 92  
77 93 ### Database
78 94  
79   -The user data is maintained in a sqlite3 database file. We first need to create the database:
  95 +The user data is maintained in a sqlite3 database file. We first need to create
  96 +the database.
  97 +At the moment, the database should be located in the same directory as the main
  98 +configuration file (see below). As an example, do
80 99  
81 100 ```sh
82   -cd demo
  101 +cd demo # contains a small example
83 102 initdb-aprendizations # show or initialize database
84 103 initdb-aprendizations --admin # add admin user
85 104 initdb-aprendizations inscricoes.csv # add students from CSV
... ... @@ -93,10 +112,12 @@ The default password is equal to the user name used to login.
93 112  
94 113 ### SSL Certificates
95 114  
96   -We need certificates for https. Certificates can be self-signed or validated by a trusted authority.
  115 +We need certificates for https. Certificates can be self-signed or validated by
  116 +a trusted authority.
97 117  
98   -Self-signed can be used locally for development and testing, but browsers will complain.
99   -LetsEncrypt issues trusted and free certificates, but the server must have a registered publicly accessible domain name.
  118 +Self-signed can be used locally for development and testing, but browsers will
  119 +complain. LetsEncrypt issues trusted and free certificates, but the server must
  120 +have a registered publicly accessible domain name.
100 121  
101 122 #### Selfsigned
102 123  
... ... @@ -148,12 +169,19 @@ cd demo
148 169 aprendizations demo.yaml
149 170 ```
150 171  
151   -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.
  172 +and open a browser at [https://127.0.0.1:8443](). If it everything looks good,
  173 +check at the correct address `https://www.example.com` (requires port forward
  174 +in the firewall). The option `--debug` provides more verbose logging and might
  175 +be useful during testing. The option `--check` generates all the questions once
  176 +before running the server to check for any obvious syntax error.
152 177  
153 178  
154 179 ### Firewall configuration
155 180  
156   -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.
  181 +Ports 80 and 443 are only usable by root. For security reasons it is better to
  182 +run the server as an unprivileged user on higher ports like 8080 for http and
  183 +8443 for https. For this, we can configure port forwarding in the firewall to
  184 +redirect incoming tcp traffic from 80 to 8080 and 443 to 8443.
157 185  
158 186 #### FreeBSD and pf
159 187  
... ... @@ -185,14 +213,20 @@ Reboot or `sudo service pf start`.
185 213  
186 214 ## Troubleshooting
187 215  
188   -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.
  216 +To help with troubleshooting, use the option `--debug` when running the server.
  217 +This will increase logs in the terminal and will present the python exception
  218 +errors in the browser.
189 219  
190   -Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and `~/.config/aprendizations/logger-debug.yaml`.
  220 +Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and
  221 +`~/.config/aprendizations/logger-debug.yaml`.
191 222  
192 223  
193 224 #### UnicodeEncodeError
194 225  
195   -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.
  226 +The server should not generate this error, but when using external scripts to
  227 +generate questions or to correct, these scripts can print unicode strings to
  228 +stdout. If the terminal does not support unicode, python will generate this
  229 +exception.
196 230  
197 231 - FreeBSD fix: edit `~/.login_conf` to use UTF-8, for example:
198 232  
... ...