Miguel Barão / perguntations

Download as
Browse Code »

Commit c7ca2f4e19b1bdf885b201c6ddf25fc187b361ec

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

update README.md

Showing 1 changed file with 63 additions and 39 deletions   Show diff stats
@@ -30,7 +30,6 @@ format=columns @@ -30,7 +30,6 @@ format=columns
30 30
31 The file is in `~/.config/pip/` in Linux/FreeBSD and `~/Library/Application Support/pip/pip.conf` in MacOS. 31 The file is in `~/.config/pip/` in Linux/FreeBSD and `~/Library/Application Support/pip/pip.conf` in MacOS.
32 32
33 -  
34 --- 33 ---
35 34
36 ## 2. Installation 35 ## 2. Installation
@@ -38,12 +37,16 @@ The file is in `~/.config/pip/` in Linux/FreeBSD and `~/Library/Application Supp @@ -38,12 +37,16 @@ The file is in `~/.config/pip/` in Linux/FreeBSD and `~/Library/Application Supp
38 Download and install (`USERNAME` is your account on bitbucket): 37 Download and install (`USERNAME` is your account on bitbucket):
39 38
40 ```bash 39 ```bash
  40 +cd ~
41 git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git 41 git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
42 cd perguntations 42 cd perguntations
43 npm install 43 npm install
44 pip3 install . 44 pip3 install .
45 ``` 45 ```
46 46
  47 +Here, the repository is installed in the user home directory.
  48 +You may wish to adjust to somewhere else.
  49 +
47 The command `npm` installs the javascript libraries and `pip3` installs the 50 The command `npm` installs the javascript libraries and `pip3` installs the
48 python webserver. 51 python webserver.
49 This will also automatically install the python dependencies required. 52 This will also automatically install the python dependencies required.
@@ -64,8 +67,6 @@ case). @@ -64,8 +67,6 @@ case).
64 mkdir -p ~/.local/share/certs 67 mkdir -p ~/.local/share/certs
65 ``` 68 ```
66 69
67 -### Selfsigned certificates  
68 -  
69 Self-signed certificates are not certified by a recognised authority and 70 Self-signed certificates are not certified by a recognised authority and
70 browsers will complain that the certificate is not trusted. 71 browsers will complain that the certificate is not trusted.
71 72
@@ -74,36 +75,9 @@ cd ~/.local/share/certs @@ -74,36 +75,9 @@ cd ~/.local/share/certs
74 openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out cert.pem -days 365 -nodes 75 openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out cert.pem -days 365 -nodes
75 ``` 76 ```
76 77
77 -### LetsEncript (FreeBSD)  
78 -  
79 -Generating certificates for a public server (FreeBSD) requires a registered  
80 -domain with fixed IP.  
81 -  
82 -```sh  
83 -sudo pkg install py27-certbot # FreeBSD  
84 -sudo service pf stop # disable pf firewall (FreeBSD)  
85 -sudo certbot certonly --standalone -d www.example.com  
86 -sudo service pf start # enable pf firewall  
87 -```  
88 -  
89 -Certificates are saved in `/usr/local/etc/letsencrypt/live/www.example.com/`.  
90 -Copy them to the `certs` directory and change permissions:  
91 -  
92 -```sh  
93 -chmod 400 cert.pem privkey.pem  
94 -```  
95 -  
96 -Certificate renewals can be done as follows:  
97 -  
98 -```sh  
99 -sudo service pf stop # shutdown firewall  
100 -sudo certbot renew  
101 -sudo service pf start # start firewall  
102 -```  
103 -  
104 -Again, copy certificate files `privkey.pem` and `cert.pem` to the `certs`  
105 -directory.  
106 - 78 +To have a true certificate, like the ones issued by LetsEncrypt, the host
  79 +must have a registered domain name.
  80 +See instructions for FreeBSD at the end of this page.
107 81
108 --- 82 ---
109 83
@@ -115,29 +89,49 @@ as a template for your own tests and questions. @@ -115,29 +89,49 @@ as a template for your own tests and questions.
115 To run the demonstration test you need to initialize the database using one of 89 To run the demonstration test you need to initialize the database using one of
116 the following methods: 90 the following methods:
117 91
118 -```.bash  
119 -cd demo 92 +```bash
  93 +cd ~/perguntations/demo
120 94
121 initdb students.csv # initialize from a CSV file 95 initdb students.csv # initialize from a CSV file
122 initdb --admin # only adds the administrator account 96 initdb --admin # only adds the administrator account
123 initdb --add 123 "Asterix Gaules" # add one student 97 initdb --add 123 "Asterix Gaules" # add one student
  98 +```
  99 +
  100 +This will create or update a `students.db` file that contains a sqlite3
  101 +database.
  102 +The database stores user passwords, and grades of the tests submitted by the
  103 +students.
  104 +
  105 +The actual tests are stored in JSON files in the following directory:
124 106
  107 +```bash
125 mkdir ans # directory where the student tests are saved 108 mkdir ans # directory where the student tests are saved
  109 +```
  110 +
  111 +A test is specified in a single `yaml` file.
  112 +The demo already includes one:
  113 +
  114 +```bash
  115 +$EDITOR tutorial.yaml # edit test configuration
  116 +```
126 117
127 -$EDITOR test-tutorial.yaml # edit test configuration 118 +To start the server with this test run:
128 119
129 -perguntations --help # get help 120 +```bash
130 perguntations tutorial.yaml # run demo test 121 perguntations tutorial.yaml # run demo test
131 ``` 122 ```
132 123
  124 +Several options are available, run `perguntations --help` for a list.
  125 +
133 The server listens on port 8443 of all IPs of all network interfaces. 126 The server listens on port 8443 of all IPs of all network interfaces.
134 Open the browser at `http://127.0.0.1:8443/` and login as user number `0` 127 Open the browser at `http://127.0.0.1:8443/` and login as user number `0`
135 (administrator) and choose any password. The administrator is redirected to the 128 (administrator) and choose any password. The administrator is redirected to the
136 administration page that shows all the students and their state. 129 administration page that shows all the students and their state.
137 130
138 1. Authorize students by clicking the checkboxes. 131 1. Authorize students by clicking the checkboxes.
139 -2. Open a different browser at `http://127.0.0.1:8443/` and login as one of the  
140 -authorized students. Answer the questions and submit. 132 +2. Open a different browser (or exit administrator) at `http://127.0.0.1:8443/`
  133 +and login as one of the authorized students.
  134 +Answer the questions and submit. You should get a grade at the end.
141 135
142 The server can be stoped from the terminal with `^C`. 136 The server can be stoped from the terminal with `^C`.
143 137
@@ -192,6 +186,36 @@ Optionally, to activate pf on boot, edit `rc.conf`: @@ -192,6 +186,36 @@ Optionally, to activate pf on boot, edit `rc.conf`:
192 pflog_flags="" 186 pflog_flags=""
193 pflog_logfile="/var/log/pflog" 187 pflog_logfile="/var/log/pflog"
194 188
  189 +## Generating certificates with LetsEncript (FreeBSD)
  190 +
  191 +Generating certificates for a public server (FreeBSD) requires a registered
  192 +domain with fixed IP.
  193 +
  194 +```sh
  195 +sudo pkg install py27-certbot # FreeBSD
  196 +sudo service pf stop # disable pf firewall (FreeBSD)
  197 +sudo certbot certonly --standalone -d www.example.com
  198 +sudo service pf start # enable pf firewall
  199 +```
  200 +
  201 +Certificates are saved in `/usr/local/etc/letsencrypt/live/www.example.com/`.
  202 +Copy them to the `certs` directory and change permissions:
  203 +
  204 +```sh
  205 +chmod 400 cert.pem privkey.pem
  206 +```
  207 +
  208 +Certificate renewals can be done as follows:
  209 +
  210 +```sh
  211 +sudo service pf stop # shutdown firewall
  212 +sudo certbot renew
  213 +sudo service pf start # start firewall
  214 +```
  215 +
  216 +Again, copy certificate files `privkey.pem` and `cert.pem` to the `certs`
  217 +directory.
  218 +
195 219
196 ## Troubleshooting 220 ## Troubleshooting
197 221