43785de6
Miguel Barão
- added documenta...
|
1
|
# Getting Started
|
a96cd2c7
Miguel Barão
- added logging s...
|
2
|
|
1e8f0810
Miguel Barão
update setup.py a...
|
3
|
|
5d859a41
Miguel Barão
update documentation
|
4
5
6
|
## Requirements
Before installing the server, we will need to install python3.7 with some additional packages, and npm (Node package management).
|
93e13002
Miguel Barão
updates README.md.
|
7
|
|
a96cd2c7
Miguel Barão
- added logging s...
|
8
|
### Install python3.7 with sqlite3 support and npm
|
39126690
Miguel Barão
removes npm and n...
|
9
10
11
12
|
This can be done using the system package management, downloaded from [http://www.python.org](), or compiled from sources.
- Installing from the system package manager:
|
f540e673
Miguel Barão
- added README.md
|
13
|
|
5d859a41
Miguel Barão
update documentation
|
14
15
|
```sh
sudo port install python37 npm5 # MacOS
|
39126690
Miguel Barão
removes npm and n...
|
16
|
sudo pkg install python37 py37-sqlite3 npm # FreeBSD
|
443a1eea
Miguel Barão
Update to latest ...
|
17
|
sudo apt install python3.7 npm # Linux
|
39126690
Miguel Barão
removes npm and n...
|
18
|
```
|
5d859a41
Miguel Barão
update documentation
|
19
20
|
- Installing from source:
|
43785de6
Miguel Barão
- added documenta...
|
21
|
|
39126690
Miguel Barão
removes npm and n...
|
22
|
Download from [http://www.python.org]() and
|
43785de6
Miguel Barão
- added documenta...
|
23
|
|
39126690
Miguel Barão
removes npm and n...
|
24
25
|
```sh
unxz Python-3.7.tar.xz
|
c54ee176
Miguel Barão
update javascript...
|
26
27
|
tar xvf Python-3.7.tar
cd Python-3.7
|
39126690
Miguel Barão
removes npm and n...
|
28
29
|
./configure --prefix=$HOME/.local/bin
make && make install
|
1e8f0810
Miguel Barão
update setup.py a...
|
30
|
```
|
93e13002
Miguel Barão
updates README.md.
|
31
32
|
This will install python locally under `~/.local/bin`. Make sure to add it to your `PATH` (edit `~/.profile` in MacOS or FreeBSD).
|
43785de6
Miguel Barão
- added documenta...
|
33
|
|
59213008
Miguel Barão
- fixed user path...
|
34
|
|
443a1eea
Miguel Barão
Update to latest ...
|
35
|
### Install pip
|
a96cd2c7
Miguel Barão
- added logging s...
|
36
|
|
43785de6
Miguel Barão
- added documenta...
|
37
|
If the `pip` command is not yet installed, run
|
39126690
Miguel Barão
removes npm and n...
|
38
39
|
```sh
|
1e8f0810
Miguel Barão
update setup.py a...
|
40
|
python3.7 -m ensurepip --user
|
43785de6
Miguel Barão
- added documenta...
|
41
|
```
|
f540e673
Miguel Barão
- added README.md
|
42
|
|
443a1eea
Miguel Barão
Update to latest ...
|
43
44
|
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`).
|
39126690
Miguel Barão
removes npm and n...
|
45
|
|
5d859a41
Miguel Barão
update documentation
|
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
|
1e8f0810
Miguel Barão
update setup.py a...
|
47
48
49
50
51
|
```ini
[global]
user = yes
```
|
5dae401a
Miguel Barão
update README.md
|
52
|
|
f540e673
Miguel Barão
- added README.md
|
53
|
### Install python packages and javascript libraries:
|
43785de6
Miguel Barão
- added documenta...
|
54
55
56
57
|
Replace USER by your bitbucket username:
```sh
|
f540e673
Miguel Barão
- added README.md
|
58
|
cd path/to/some/directory
|
39126690
Miguel Barão
removes npm and n...
|
59
|
git clone https://USER@bitbucket.org/mjsb/aprendizations.git
|
f540e673
Miguel Barão
- added README.md
|
60
|
cd aprendizations
|
43785de6
Miguel Barão
- added documenta...
|
61
|
pip install . # install aprendizations and dependencies
|
39126690
Miguel Barão
removes npm and n...
|
62
|
npm install # install javascript libraries
|
43785de6
Miguel Barão
- added documenta...
|
63
|
```
|
f540e673
Miguel Barão
- added README.md
|
64
|
|
c3eba869
Miguel Barão
update README.md
|
65
|
Python packages are usually installed in:
|
a96cd2c7
Miguel Barão
- added logging s...
|
66
|
|
443a1eea
Miguel Barão
Update to latest ...
|
67
|
- `~/.local/lib/python3.7/site-packages/` in Linux/FreeBSD.
|
1e8f0810
Miguel Barão
update setup.py a...
|
68
|
- `~/Library/python/3.7/lib/python/site-packages/` in MacOS.
|
a96cd2c7
Miguel Barão
- added logging s...
|
69
|
|
443a1eea
Miguel Barão
Update to latest ...
|
70
|
Javascript libraries are installed in `aprendizations/node_modules` directory.
|
39126690
Miguel Barão
removes npm and n...
|
71
|
This libraries are linked from the `aprendizations/aprendizations/static` directory.
|
f540e673
Miguel Barão
- added README.md
|
72
|
|
39126690
Miguel Barão
removes npm and n...
|
73
74
|
At this point aprendizations can be run anywhere with the command `aprendizations`.
|
5dae401a
Miguel Barão
update README.md
|
75
76
|
## Configuration
|
93e13002
Miguel Barão
updates README.md.
|
77
|
### Database
|
1e8f0810
Miguel Barão
update setup.py a...
|
78
|
|
5dae401a
Miguel Barão
update README.md
|
79
80
|
The user data is maintained in a sqlite3 database file. We first need to create the database:
|
93e13002
Miguel Barão
updates README.md.
|
81
|
```sh
|
b4ceb7fc
Miguel Barão
minor change in l...
|
82
|
cd demo
|
93e13002
Miguel Barão
updates README.md.
|
83
84
85
|
initdb-aprendizations # show or initialize database
initdb-aprendizations --admin # add admin user
initdb-aprendizations inscricoes.csv # add students from CSV
|
39126690
Miguel Barão
removes npm and n...
|
86
|
initdb-aprendizations --add 1184 "Aladino da Silva" # add user
|
93e13002
Miguel Barão
updates README.md.
|
87
|
initdb-aprendizations --update 1184 --pw alibaba # update password
|
f540e673
Miguel Barão
- added README.md
|
88
|
initdb-aprendizations --help # for the available options
|
59213008
Miguel Barão
- fixed user path...
|
89
90
|
```
|
443a1eea
Miguel Barão
Update to latest ...
|
91
92
|
The default password is equal to the user name used to login.
|
c288f8c6
Miguel Barao
- updated documen...
|
93
|
|
443a1eea
Miguel Barão
Update to latest ...
|
94
95
96
|
### SSL Certificates
We need certificates for https. Certificates can be self-signed or validated by a trusted authority.
|
c288f8c6
Miguel Barao
- updated documen...
|
97
|
|
93e13002
Miguel Barão
updates README.md.
|
98
|
Self-signed can be used locally for development and testing, but browsers will complain.
|
f540e673
Miguel Barão
- added README.md
|
99
|
LetsEncrypt issues trusted and free certificates, but the server must have a registered publicly accessible domain name.
|
b4ceb7fc
Miguel Barão
minor change in l...
|
100
|
|
59213008
Miguel Barão
- fixed user path...
|
101
|
#### Selfsigned
|
43785de6
Miguel Barão
- added documenta...
|
102
103
104
|
Generate a selfsigned certificate and place it in `aprendizations/certs`.
|
59213008
Miguel Barão
- fixed user path...
|
105
|
```sh
|
93e13002
Miguel Barão
updates README.md.
|
106
107
108
|
openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out cert.pem -days 365 -nodes
```
|
bbc1c506
Miguel Barão
- documentation u...
|
109
|
#### LetsEncrypt
|
43785de6
Miguel Barão
- added documenta...
|
110
|
|
443a1eea
Miguel Barão
Update to latest ...
|
111
|
```sh
|
5d859a41
Miguel Barão
update documentation
|
112
|
sudo pkg install py27-certbot # FreeBSD
|
43785de6
Miguel Barão
- added documenta...
|
113
|
```
|
bbc1c506
Miguel Barão
- documentation u...
|
114
|
|
443a1eea
Miguel Barão
Update to latest ...
|
115
116
|
Shutdown the firewall and any web server that might be running. Then run the script to generate the certificate:
|
bbc1c506
Miguel Barão
- documentation u...
|
117
|
```sh
|
43785de6
Miguel Barão
- added documenta...
|
118
|
sudo service pf stop # disable pf firewall (FreeBSD)
|
93e13002
Miguel Barão
updates README.md.
|
119
120
|
sudo certbot certonly --standalone -d www.example.com
sudo service pf start # enable pf firewall
|
43785de6
Miguel Barão
- added documenta...
|
121
|
```
|
bbc1c506
Miguel Barão
- documentation u...
|
122
|
|
443a1eea
Miguel Barão
Update to latest ...
|
123
124
125
|
Certificates are saved under `/usr/local/etc/letsencrypt/live/www.example.com/`. Copy them to `aprendizations/certs` and change permissions to be readable:
```sh
|
bbc1c506
Miguel Barão
- documentation u...
|
126
|
sudo cp /usr/local/etc/letsencrypt/live/www.example.com/cert.pem .
|
43785de6
Miguel Barão
- added documenta...
|
127
|
sudo cp /usr/local/etc/letsencrypt/live/www.example.com/privkey.pem .
|
443a1eea
Miguel Barão
Update to latest ...
|
128
|
chmod 400 cert.pem privkey.pem
|
43785de6
Miguel Barão
- added documenta...
|
129
130
131
132
|
```
Renews can be done as follows:
|
bbc1c506
Miguel Barão
- documentation u...
|
133
|
```sh
|
5d859a41
Miguel Barão
update documentation
|
134
135
136
137
|
sudo service pf stop # shutdown firewall
sudo certbot renew
sudo service pf start # start firewall
```
|
443a1eea
Miguel Barão
Update to latest ...
|
138
139
|
and then copy the `cert.pem` and `privkey.pem` files to `aprendizations/certs` directory. Change permissions and ownership as appropriate.
|
39126690
Miguel Barão
removes npm and n...
|
140
|
|
5d859a41
Miguel Barão
update documentation
|
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
### Testing
The application includes a small example in `demo/demo.yaml`. Run it with
```sh
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.
### Firewall configuration
|
93e13002
Miguel Barão
updates README.md.
|
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.
|
c55940af
Miguel Barão
- minor change in...
|
157
|
|
39126690
Miguel Barão
removes npm and n...
|
158
|
#### FreeBSD and pf
|
443a1eea
Miguel Barão
Update to latest ...
|
159
|
|
f540e673
Miguel Barão
- added README.md
|
160
|
Edit `/etc/pf.conf`:
|
43785de6
Miguel Barão
- added documenta...
|
161
|
|
3ec49458
Miguel Barão
fix README.md and...
|
162
|
```sh
|
39126690
Miguel Barão
removes npm and n...
|
163
|
ext_if="em0" # this should be the correct network interface
|
43785de6
Miguel Barão
- added documenta...
|
164
|
rdr on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 port 8080
|
59213008
Miguel Barão
- fixed user path...
|
165
|
rdr on $ext_if proto tcp from any to any port 443 -> 127.0.0.1 port 8443
|
443a1eea
Miguel Barão
Update to latest ...
|
166
167
|
```
|
93e13002
Miguel Barão
updates README.md.
|
168
|
Under virtualbox with guest additions use `ext_if="vtnet0"`.
|
443a1eea
Miguel Barão
Update to latest ...
|
169
170
|
Edit `/etc/rc.conf`
|
c288f8c6
Miguel Barao
- updated documen...
|
171
|
|
59213008
Miguel Barão
- fixed user path...
|
172
173
|
```sh
pf_enable="YES"
|
443a1eea
Miguel Barão
Update to latest ...
|
174
175
176
|
pf_flags=""
pf_rules="/etc/pf.conf"
|
59213008
Miguel Barão
- fixed user path...
|
177
178
179
180
181
|
# optional logging:
pflog_enable="YES"
pflog_flags=""
pflog_logfile="/var/log/pflog"
```
|
43785de6
Miguel Barão
- added documenta...
|
182
|
|
93e13002
Miguel Barão
updates README.md.
|
183
|
Reboot or `sudo service pf start`.
|
43785de6
Miguel Barão
- added documenta...
|
184
185
186
|
## Troubleshooting
|
59213008
Miguel Barão
- fixed user path...
|
187
|
|
5d859a41
Miguel Barão
update documentation
|
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.
|
59213008
Miguel Barão
- fixed user path...
|
189
|
|
43785de6
Miguel Barão
- added documenta...
|
190
|
Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and `~/.config/aprendizations/logger-debug.yaml`.
|
59213008
Miguel Barão
- fixed user path...
|
191
|
|
43785de6
Miguel Barão
- added documenta...
|
192
193
194
195
|
#### 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.
|
59213008
Miguel Barão
- fixed user path...
|
196
|
|
43785de6
Miguel Barão
- added documenta...
|
197
198
199
200
201
|
- FreeBSD fix: edit `~/.login_conf` to use UTF-8, for example:
```sh
me:\
:charset=UTF-8:\
|
59213008
Miguel Barão
- fixed user path...
|
202
|
:lang=en_US.UTF-8:
|
ea4ff4d2
Miguel Barão
- radio: added su...
|
203
|
```
|
59213008
Miguel Barão
- fixed user path...
|
204
|
|
39126690
Miguel Barão
removes npm and n...
|
205
206
|
- Debian fix: check `locale`...
|
93e13002
Miguel Barão
updates README.md.
|
207
208
209
210
|
## FAQ
- Which students did at least one topic?
|
39126690
Miguel Barão
removes npm and n...
|
211
212
|
```sh
sqlite3 students.db "select distinct student_id from studenttopic"
|
443a1eea
Miguel Barão
Update to latest ...
|
213
214
215
|
```
- How many topics has each student done?
|
39126690
Miguel Barão
removes npm and n...
|
216
|
|
a203d3cc
Miguel Barão
- new http server...
|
217
|
```sh
|
5d859a41
Miguel Barão
update documentation
|
218
219
220
221
222
|
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?
|
39126690
Miguel Barão
removes npm and n...
|
223
|
```sh
|
5d859a41
Miguel Barão
update documentation
|
224
225
|
sqlite3 students.db "select count(ref), ref from answers where grade<1.0 group by ref order by count(ref) desc"
```
|
59213008
Miguel Barão
- fixed user path...
|
|
|
443a1eea
Miguel Barão
Update to latest ...
|
|
|
5dae401a
Miguel Barão
update README.md
|
|
|
43785de6
Miguel Barão
- added documenta...
|
|
|
443a1eea
Miguel Barão
Update to latest ...
|
|
|
5dae401a
Miguel Barão
update README.md
|
|
|
43785de6
Miguel Barão
- added documenta...
|
|
|
443a1eea
Miguel Barão
Update to latest ...
|
|
|
43785de6
Miguel Barão
- added documenta...
|
|
|
443a1eea
Miguel Barão
Update to latest ...
|
|
|
59213008
Miguel Barão
- fixed user path...
|
|
|
443a1eea
Miguel Barão
Update to latest ...
|
|
|
5dae401a
Miguel Barão
update README.md
|
|
|
59213008
Miguel Barão
- fixed user path...
|
|
|
443a1eea
Miguel Barão
Update to latest ...
|
|
|
59213008
Miguel Barão
- fixed user path...
|
|
|
43785de6
Miguel Barão
- added documenta...
|
|
|
f75a344f
Miguel Barão
- README.md updat...
|
|
|
443a1eea
Miguel Barão
Update to latest ...
|
|
|
db04e658
Miguel Barão
- added option to...
|
|
|
43785de6
Miguel Barão
- added documenta...
|
|
|
f75a344f
Miguel Barão
- README.md updat...
|
|
|
93e13002
Miguel Barão
updates README.md.
|
|
|
f75a344f
Miguel Barão
- README.md updat...
|
|
|
43785de6
Miguel Barão
- added documenta...
|
|
|
d187aad4
Miguel Barão
- adds courses
|
|
|
43785de6
Miguel Barão
- added documenta...
|
|
|
f75a344f
Miguel Barão
- README.md updat...
|
|
|
d187aad4
Miguel Barão
- adds courses
|
|
|
f75a344f
Miguel Barão
- README.md updat...
|
|
|
43785de6
Miguel Barão
- added documenta...
|
|
|
93e13002
Miguel Barão
updates README.md.
|
|
|
f75a344f
Miguel Barão
- README.md updat...
|
|
|
93e13002
Miguel Barão
updates README.md.
|
|
|
443a1eea
Miguel Barão
Update to latest ...
|
|
|
f75a344f
Miguel Barão
- README.md updat...
|
|
|
93e13002
Miguel Barão
updates README.md.
|
|
|
443a1eea
Miguel Barão
Update to latest ...
|
|
|
93e13002
Miguel Barão
updates README.md.
|
|
|