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
README.md
  Diff comments   View file @c7ca2f4
... ... @@ -30,7 +30,6 @@ format=columns
30 30  
31 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 35 ## 2. Installation
... ... @@ -38,12 +37,16 @@ The file is in `~/.config/pip/` in Linux/FreeBSD and `~/Library/Application Supp
38 37 Download and install (`USERNAME` is your account on bitbucket):
39 38  
40 39 ```bash
  40 +cd ~
41 41 git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
42 42 cd perguntations
43 43 npm install
44 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 50 The command `npm` installs the javascript libraries and `pip3` installs the
48 51 python webserver.
49 52 This will also automatically install the python dependencies required.
... ... @@ -64,8 +67,6 @@ case).
64 67 mkdir -p ~/.local/share/certs
65 68 ```
66 69  
67   -### Selfsigned certificates
68   -
69 70 Self-signed certificates are not certified by a recognised authority and
70 71 browsers will complain that the certificate is not trusted.
71 72  
... ... @@ -74,36 +75,9 @@ cd ~/.local/share/certs
74 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 89 To run the demonstration test you need to initialize the database using one of
116 90 the following methods:
117 91  
118   -```.bash
119   -cd demo
  92 +```bash
  93 +cd ~/perguntations/demo
120 94  
121 95 initdb students.csv # initialize from a CSV file
122 96 initdb --admin # only adds the administrator account
123 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 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 121 perguntations tutorial.yaml # run demo test
131 122 ```
132 123  
  124 +Several options are available, run `perguntations --help` for a list.
  125 +
133 126 The server listens on port 8443 of all IPs of all network interfaces.
134 127 Open the browser at `http://127.0.0.1:8443/` and login as user number `0`
135 128 (administrator) and choose any password. The administrator is redirected to the
136 129 administration page that shows all the students and their state.
137 130  
138 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 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 186 pflog_flags=""
193 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 220 ## Troubleshooting
197 221  
... ...