Miguel Barão / perguntations

Download as
Browse Code »

Commit cab247c9f11c2a51a1510a48b6513c3685cd473d

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

updated README and BUGS

Showing 2 changed files with 43 additions and 13 deletions   Show diff stats
@@ -19,6 +19,9 @@ ou usar push (websockets?) @@ -19,6 +19,9 @@ ou usar push (websockets?)
19 19
20 # TODO 20 # TODO
21 21
  22 +- gerar teste qd o prof autoriza.
  23 +- enviar resposta de cada pergunta individualmente.
  24 +
22 - experimentar gerador de svg que inclua no markdown da pergunta e ver se funciona. 25 - experimentar gerador de svg que inclua no markdown da pergunta e ver se funciona.
23 - imagens jpg/png nas perguntas. 26 - imagens jpg/png nas perguntas.
24 - suportar cotacao to teste diferente de 20 (e.g. para juntar perguntas em papel). opcao "points: 18" que normaliza total para 18 em vez de 20. 27 - suportar cotacao to teste diferente de 20 (e.g. para juntar perguntas em papel). opcao "points: 18" que normaliza total para 18 em vez de 20.
@@ -4,9 +4,9 @@ @@ -4,9 +4,9 @@
4 2. [Running a demo](#running-a-demo) 4 2. [Running a demo](#running-a-demo)
5 3. [Troubleshooting](#troubleshooting) 5 3. [Troubleshooting](#troubleshooting)
6 6
7 -## Installation 7 +## 1. Installation
8 8
9 -### Requirements 9 +### 1.1 Requirements
10 10
11 The webserver is a python application and requires `python3.6` and `pip` to be installed, plus the following additional packages: 11 The webserver is a python application and requires `python3.6` and `pip` to be installed, plus the following additional packages:
12 12
@@ -16,13 +16,14 @@ The webserver is a python application and requires `python3.6` and `pip` to be i @@ -16,13 +16,14 @@ The webserver is a python application and requires `python3.6` and `pip` to be i
16 - Pygments 16 - Pygments
17 - SQLAlchemy 17 - SQLAlchemy
18 - bcrypt 18 - bcrypt
  19 +- markdown
19 20
20 These can be installed for a single user (recommended), in a python virtual environment or system wide. 21 These can be installed for a single user (recommended), in a python virtual environment or system wide.
21 22
22 #### Installing packages for a single user (recommended) 23 #### Installing packages for a single user (recommended)
23 24
24 ```.bash 25 ```.bash
25 -pip3 install --user tornado mistune pyyaml pygments sqlalchemy bcrypt 26 +pip3 install --user tornado mistune pyyaml pygments sqlalchemy bcrypt markdown
26 ``` 27 ```
27 28
28 #### Installing packages in a virtual environment (alternative) 29 #### Installing packages in a virtual environment (alternative)
@@ -31,7 +32,7 @@ pip3 install --user tornado mistune pyyaml pygments sqlalchemy bcrypt @@ -31,7 +32,7 @@ pip3 install --user tornado mistune pyyaml pygments sqlalchemy bcrypt
31 pyvenv-3.6 venv/perguntations # or other virtualenv directory 32 pyvenv-3.6 venv/perguntations # or other virtualenv directory
32 source venv/perguntations/bin/activate # activate virtualenv 33 source venv/perguntations/bin/activate # activate virtualenv
33 34
34 -pip3 install tornado mistune pyyaml pygments sqlalchemy bcrypt 35 +pip3 install tornado mistune pyyaml pygments sqlalchemy bcrypt markdown
35 ``` 36 ```
36 37
37 #### Installing packages system wide (alternative) 38 #### Installing packages system wide (alternative)
@@ -51,7 +52,7 @@ port install py36-py36-tornado py36-mistune? py36-yaml py36-pygments... @@ -51,7 +52,7 @@ port install py36-py36-tornado py36-mistune? py36-yaml py36-pygments...
51 ``` 52 ```
52 53
53 54
54 -### Install and setup perguntations 55 +### 1.2 Install and setup perguntations
55 56
56 There is no installer, pip or otherwise. It's still in development and has to be run from sources. Use `git` to get the sources: 57 There is no installer, pip or otherwise. It's still in development and has to be run from sources. Use `git` to get the sources:
57 58
@@ -65,11 +66,35 @@ where USERNAME is your account on bitbucket. @@ -65,11 +66,35 @@ where USERNAME is your account on bitbucket.
65 The server will run an https server and requires valid certificates. 66 The server will run an https server and requires valid certificates.
66 To generate certificates, there are two possibilities: public server with static IP address or a private server. 67 To generate certificates, there are two possibilities: public server with static IP address or a private server.
67 68
68 -#### Generating certificates for a public server 69 +#### Generating certificates for a public server (FreeBSD)
69 70
70 -For a public server, `letsencrypt` will allow a certificate to be generated. 71 +```sh
  72 +sudo pkg install py27-certbot # FreeBSD
  73 +```
  74 +
  75 +Shutdown the firewall and any server running. Then run the script to generate the certificate:
  76 +
  77 +```sh
  78 +sudo service pf stop # disable pf firewall (FreeBSD)
  79 +sudo certbot certonly --standalone -d www.example.com
  80 +sudo service pf start # enable pf firewall
  81 +```
  82 +
  83 +Certificates are saved under `/usr/local/etc/letsencrypt/live/www.example.com/`. Copy them to `aprendizations/certs` and change permissions to be readable:
71 84
72 -TODO: explain... 85 +```sh
  86 +sudo cp /usr/local/etc/letsencrypt/live/www.example.com/cert.pem .
  87 +sudo cp /usr/local/etc/letsencrypt/live/www.example.com/privkey.pem .
  88 +chmod 400 cert.pem privkey.pem
  89 +```
  90 +
  91 +Renews can be done as follows:
  92 +
  93 +```sh
  94 +sudo service pf stop # shutdown firewall
  95 +sudo certbot renew
  96 +sudo service pf start # start firewall
  97 +```
73 98
74 Copy certificates `cert.crt` and `cert.key` to the `perguntations/certs/` directory. 99 Copy certificates `cert.crt` and `cert.key` to the `perguntations/certs/` directory.
75 100
@@ -79,7 +104,7 @@ Self-signed certificates are not certified by a recognised authority and browser @@ -79,7 +104,7 @@ Self-signed certificates are not certified by a recognised authority and browser
79 104
80 ```bash 105 ```bash
81 cd perguntations/certs/ 106 cd perguntations/certs/
82 -openssl req -x509 -newkey rsa:4096 -keyout cert.key -out cert.crt -days -nodes 107 +openssl req -x509 -newkey rsa:4096 -keyout cert.key -out cert.crt -days 365 -nodes
83 ``` 108 ```
84 109
85 ## Running a demo 110 ## Running a demo
@@ -92,12 +117,14 @@ To run the demonstration test: @@ -92,12 +117,14 @@ To run the demonstration test:
92 cd WHERE/YOU/INSTALLED/perguntations 117 cd WHERE/YOU/INSTALLED/perguntations
93 118
94 # create and initialize database using one of the following methods: 119 # create and initialize database using one of the following methods:
95 -./initdb.py students.csv # from CSV file  
96 -./initdb.py --demo # initialize with fake students  
97 -./initdb.py # only adds the administrator account 120 +./initdb.py students.csv # initialize from a CSV file
  121 +./initdb.py --admin # only adds the administrator account
  122 +./initdb.py --add 123 "Asterix Gaules" # add one student
  123 +
  124 +# a database file "students.db" is created
98 mv students.db demo/ 125 mv students.db demo/
99 126
100 -# create directory to save the student's tests 127 +# create directory to save the finished tests
101 mkdir demo/ans 128 mkdir demo/ans
102 129
103 # edit test configuration and check if everything looks right 130 # edit test configuration and check if everything looks right