Miguel Barão / aprendizations

Download as
Browse Code »

Commit 5d859a41613f491f983851096eeee5b8cbbb3755

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

update documentation

Showing 2 changed files with 64 additions and 40 deletions   Show diff stats
README.md
  Diff comments   View file @5d859a4
1 1 # Getting Started
2 2  
  3 +
  4 +## Installation
  5 +
3 6 To complete the installation we will need to perform the following steps:
4 7  
5 8 1. install python3.7, pip and npm
6 9 1. download aprendizations from the repository
7 10 1. install javascript libraries (with npm)
8 11 1. install aprendizations (with pip)
9   -1. initialize database
10 12 1. generate SSL certificates
11 13 1. configure the firewall (optional)
12   -1. try running `aprendizations demo.yaml`
13 14  
14   -These steps are explained next in detail.
  15 +To use the software we need to:
  16 +
  17 +1. initialize database
  18 +1. go to the demo directory (or an existing course)
  19 +1. run `aprendizations demo.yaml`
  20 +
  21 +Each of these steps is explained below.
15 22  
16 23 ### Install python3.7 with sqlite3 support and npm
17 24  
... ... @@ -47,16 +54,21 @@ This will install python locally under `~/.local/bin`. Make sure to add it to yo
47 54  
48 55 ### Install pip
49 56  
50   -Python usually includes pip which is accessible through `python -m pip install something`, but it's also convenient to have the `pip` command installed.
51   -If the `pip` command is not yet installed, run one of these:
  57 +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.
  58 +To install `pip` from the system package manager:
52 59  
53 60 ```sh
54 61 sudo apt install python3.7-pip # Ubuntu 19.04+
55   -python3.7 -m pip install pip # Ubuntu 18.04
56 62 sudo pkg py37-pip # FreeBSD
57 63 sudo port install py37-pip # MacOS
58 64 ```
59 65  
  66 +otherwise run:
  67 +
  68 +```sh
  69 +python3.7 -m pip install pip # install in user area
  70 +```
  71 +
60 72 The latter will install `pip` in your user account under `~/.local/bin`.
61 73 In the end you should be able to run `pip --version` and
62 74 `python3 -c "import sqlite3"` without errors.
... ... @@ -73,7 +85,7 @@ user = yes
73 85  
74 86 This will set pip to install modules in the user area (recommended).
75 87  
76   -### Install aprendizations and dependencies:
  88 +### Download and install aprendizations:
77 89  
78 90 ```sh
79 91 git clone https://git.xdi.uevora.pt/mjsb/aprendizations.git
... ... @@ -82,8 +94,7 @@ npm install # install javascript libraries
82 94 pip install . # install aprendizations and dependencies
83 95 ```
84 96  
85   -Javascript libraries are initially installed in `aprendizations/node_modules` directory.
86   -These libraries already have symbolic links from `aprendizations/aprendizations/static`.
  97 +Javascript libraries are installed in `aprendizations/node_modules` and are linked from `aprendizations/aprendizations/static`.
87 98  
88 99 Python packages are usually installed in:
89 100  
... ... @@ -92,7 +103,7 @@ Python packages are usually installed in:
92 103  
93 104 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.
94 105  
95   -At this point, aprendizations is installed in
  106 +At this point `aprendizations` is installed in
96 107  
97 108 ```sh
98 109 ~/.local/bin # Linux/FreeBSD
... ... @@ -106,29 +117,6 @@ aprendizations --version
106 117 aprendizations --help
107 118 ```
108 119  
109   -## Configuration
110   -
111   -### Database
112   -
113   -User data is maintained in a sqlite3 database which has to be created manually using the command `initdb-aprendizations`.
114   -The database file should be located in the same directory as the main
115   -YAML configuration file.
116   -
117   -For example, to run the included demo do:
118   -
119   -```sh
120   -cd demo # contains a small example
121   -initdb-aprendizations # show or initialize database
122   -initdb-aprendizations --admin # add admin user
123   -initdb-aprendizations inscricoes.csv # add students from CSV
124   -initdb-aprendizations --add 1184 "Aladino da Silva" # add new user
125   -initdb-aprendizations --update 1184 --pw alibaba # update password
126   -initdb-aprendizations --help # for available options
127   -```
128   -
129   -The default password is equal to the user name, if left undefined.
130   -
131   -
132 120 ### SSL Certificates
133 121  
134 122 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:
150 138  
151 139 ```sh
152 140 sudo pkg install py36-certbot # FreeBSD
153   -sudo apt install certbot # Linux Ubuntu
  141 +sudo apt install certbot # Ubuntu
154 142 ```
155 143  
156 144 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 .
168 156 chmod 400 cert.pem privkey.pem
169 157 ```
170 158  
  159 +
  160 +## Configuration
  161 +
  162 +### Database
  163 +
  164 +User data is maintained in a sqlite3 database which has to be created manually using the `initdb-aprendizations` command.
  165 +The database file should be located in the same directory as the main
  166 +YAML configuration file.
  167 +
  168 +For example, to run the included demo do:
  169 +
  170 +```sh
  171 +cd demo # contains a small example
  172 +initdb-aprendizations # show or initialize database
  173 +initdb-aprendizations --admin # add admin user
  174 +initdb-aprendizations inscricoes.csv # add students from CSV
  175 +initdb-aprendizations --add 1184 "Aladino da Silva" # add new user
  176 +initdb-aprendizations --update 1184 --pw alibaba # update password
  177 +initdb-aprendizations --help # for available options
  178 +```
  179 +
  180 +The default password is equal to the user name, if left undefined.
  181 +
  182 +
171 183 ### Running the demo
172 184  
173 185 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
178 190 ```
179 191  
180 192 Open the browser at [https://127.0.0.1:8443](https://127.0.0.1:8443).
181   -If it everything looks good, check at the correct address
  193 +If everything looks good, check at the correct address
182 194 `https://www.example.com:8443`.
183 195 The option `--debug` provides more verbose logging and might
184 196 be useful during testing.
... ... @@ -198,7 +210,7 @@ rdr on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 port 8080
198 210 rdr on $ext_if proto tcp from any to any port 443 -> 127.0.0.1 port 8443
199 211 ```
200 212  
201   -Under virtualbox with guest additions use `ext_if="vtnet0"`.
  213 +Virtualbox with guest additions uses `ext_if="vtnet0"`.
202 214  
203 215 Edit `/etc/rc.conf`
204 216  
... ... @@ -228,6 +240,17 @@ Make sure the following steps have been done:
228 240 - (optional) configure the firewall to do port forwarding
229 241 - run `aprendizations demo.yaml --check`
230 242  
  243 +## Keeping aprendizations updated
  244 +
  245 +To update aprendizations to the latest version do:
  246 +
  247 +```sh
  248 +cd aprendizations
  249 +git pull # get latest version
  250 +npm update # update javascript libraries
  251 +pip install -U . # updates installed version to latest
  252 +```
  253 +
231 254 ## Troubleshooting
232 255  
233 256 To help with troubleshooting, use the option `--debug` when running the server.
... ...
aprendizations/main.py
  Diff comments   View file @5d859a4
... ... @@ -186,16 +186,17 @@ def main():
186 186 logging.critical(f'SSL certificates missing in {certs_dir}')
187 187 print('--------------------------------------------------------------')
188 188 print('Certificates should be issued by a certificate authority (CA),')
189   - print('such as https://letsencrypt.org, and then copied to: ')
190   - print(' ')
191   - print(f' {certs_dir:<62}')
192   - print(' ')
  189 + print('such as https://letsencrypt.org. ')
193 190 print('For testing purposes a selfsigned certificate can be generated')
194 191 print('locally by running: ')
195 192 print(' ')
196 193 print(' openssl req -x509 -newkey rsa:4096 -keyout privkey.pem \\ ')
197 194 print(' -out cert.pem -days 365 -nodes ')
198 195 print(' ')
  196 + print('Copy the cert.pem and privkey.pem files to: ')
  197 + print(' ')
  198 + print(f' {certs_dir:<62}')
  199 + print(' ')
199 200 print('--------------------------------------------------------------')
200 201 sys.exit(1)
201 202  
... ...