Miguel Barão / perguntations

Download as
Browse Code »

Commit 1dfeb553c6cfacc198086fbceb049441d00e11c8

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

update README.md

Showing 2 changed files with 42 additions and 37 deletions   Show diff stats
1 1
2 # BUGS 2 # BUGS
3 3
4 -- usar npm para instalar javascript  
5 - impedir os eventos copy/paste. alunos usam isso para trazer codigo ja feito nos computadores. Obrigar a fazer reset? fazer um copy automaticamente? 4 - impedir os eventos copy/paste. alunos usam isso para trazer codigo ja feito nos computadores. Obrigar a fazer reset? fazer um copy automaticamente?
6 - a revisao do teste não mostra as imagens. 5 - a revisao do teste não mostra as imagens.
7 - melhorar o botao de autorizar (desliga-se), usar antes um botao? 6 - melhorar o botao de autorizar (desliga-se), usar antes um botao?
@@ -10,13 +9,13 @@ ou usar push (websockets?) @@ -10,13 +9,13 @@ ou usar push (websockets?)
10 - pymips: nao pode executar syscalls do spim. 9 - pymips: nao pode executar syscalls do spim.
11 - perguntas checkbox [right,wrong] com pelo menos uma opção correcta. 10 - perguntas checkbox [right,wrong] com pelo menos uma opção correcta.
12 - questions.py textarea has a abspath which does not make sense! why is it there? not working for perguntations, but seems to work for aprendizations 11 - questions.py textarea has a abspath which does not make sense! why is it there? not working for perguntations, but seems to work for aprendizations
13 -- submissao faz um post ajax.  
14 - eventos unfocus? 12 - eventos unfocus?
15 - servidor nao esta a lidar com eventos scroll/resize. ignorar? 13 - servidor nao esta a lidar com eventos scroll/resize. ignorar?
16 - Test.reset_answers() unused. 14 - Test.reset_answers() unused.
17 15
18 # TODO 16 # TODO
19 17
  18 +- submissao fazer um post ajax?
20 - fazer package para instalar perguntations com pip. 19 - fazer package para instalar perguntations com pip.
21 - adicionar opcao para eliminar um teste em curso. 20 - adicionar opcao para eliminar um teste em curso.
22 - gerar teste qd o prof autoriza? melhor nao, pode apagar o teste em curso. gerar previamente e manter uma pool de testes gerados? 21 - gerar teste qd o prof autoriza? melhor nao, pode apagar o teste em curso. gerar previamente e manter uma pool de testes gerados?
@@ -63,6 +62,7 @@ ou usar push (websockets?) @@ -63,6 +62,7 @@ ou usar push (websockets?)
63 62
64 # FIXED 63 # FIXED
65 64
  65 +- usar npm para instalar javascript
66 - se aluno entrar com l12345 rebenta. numa funcao get_... ver imagem no ipad 66 - se aluno entrar com l12345 rebenta. numa funcao get_... ver imagem no ipad
67 - no test3 está contar 1.0 valores numa pergunta do tipo info? acontece para type: info, e não para type: information 67 - no test3 está contar 1.0 valores numa pergunta do tipo info? acontece para type: info, e não para type: information
68 - default correct in checkbox must be 1.0, so that the pairs (right,wrong) still work with `correct` left undefined. 68 - default correct in checkbox must be 1.0, so that the pairs (right,wrong) still work with `correct` left undefined.
1 -# README # 1 + # README #
2 2
3 -1. [Installation](#installation)  
4 -2. [Running a demo](#running-a-demo)  
5 -3. [Troubleshooting](#troubleshooting) 3 +[Requirements](#requirements)
  4 +[Installation](#installation)
  5 +[Setup](#setup)
  6 +[Running a demo](#running-a-demo)
  7 +[Running on lower ports](#running-on-lower-ports)
  8 +[Troubleshooting](#troubleshooting)
6 9
7 --- 10 ---
8 11
9 -## 1. Requirements 12 +## Requirements
10 13
11 The webserver is a python application that requires `>=python3.6` and `pip` to be 14 The webserver is a python application that requires `>=python3.6` and `pip` to be
12 installed. `npm` (Node package management) is also necessary to install the 15 installed. `npm` (Node package management) is also necessary to install the
13 javascript libraries. 16 javascript libraries.
14 17
15 ```bash 18 ```bash
16 -sudo apt install python3 python3-pip npm # debian, ubuntu, mint, ... 19 +sudo apt install python3 python3-pip python3-setuptools npm # Ubuntu
17 sudo pkg install python36 py36-sqlite3 py36-pip py36-setuptools npm # FreeBSD 20 sudo pkg install python36 py36-sqlite3 py36-pip py36-setuptools npm # FreeBSD
18 -sudo port install python37 py37-pip py37-setuptools npm6 # MacOS 21 +sudo port install python37 py37-pip py37-setuptools npm6 # MacOS
19 ``` 22 ```
20 23
21 The file `pip.conf` should be configured to the following: 24 The file `pip.conf` should be configured to the following:
@@ -28,11 +31,12 @@ user=yes @@ -28,11 +31,12 @@ user=yes
28 format=columns 31 format=columns
29 ``` 32 ```
30 33
31 -The file is in `~/.config/pip/` in Linux/FreeBSD and `~/Library/Application Support/pip/pip.conf` in MacOS. 34 +This file is usually in `~/.config/pip/` in Linux and FreeBSD. In MacOS it's in
  35 +`~/Library/Application Support/pip/`.
32 36
33 --- 37 ---
34 38
35 -## 2. Installation 39 +## Installation
36 40
37 Download and install (`USERNAME` is your account on bitbucket): 41 Download and install (`USERNAME` is your account on bitbucket):
38 42
@@ -49,26 +53,27 @@ You may wish to adjust to somewhere else. @@ -49,26 +53,27 @@ You may wish to adjust to somewhere else.
49 53
50 The command `npm` installs the javascript libraries and `pip3` installs the 54 The command `npm` installs the javascript libraries and `pip3` installs the
51 python webserver. 55 python webserver.
52 -This will also automatically install the python dependencies required. 56 +This will also install any required dependencies.
53 57
54 --- 58 ---
55 59
56 -## 3 Setup 60 +## Setup
57 61
58 -The server will run an https server and requires valid certificates.  
59 -To generate certificates, there are two possibilities: public server with  
60 -static IP address or a private server on a local network. 62 +The server will run a `https` server and requires valid certificates.
  63 +There are two possibilities to generate the certificates:
  64 +
  65 +- public server with static IP address and registered domain name;
  66 +- private server on a local network isolated from the internet.
61 67
62 Certificates must be saved in the `$XDG_DATA_HOME` path if defined in the 68 Certificates must be saved in the `$XDG_DATA_HOME` path if defined in the
63 -environment, otherwise in `~/.local/share/certs` (I will assume the latter  
64 -case). 69 +environment, otherwise in `~/.local/share/certs` (I will assume the latter).
65 70
66 ```bash 71 ```bash
67 mkdir -p ~/.local/share/certs 72 mkdir -p ~/.local/share/certs
68 ``` 73 ```
69 74
70 Self-signed certificates are not certified by a recognised authority and 75 Self-signed certificates are not certified by a recognised authority and
71 -browsers will complain that the certificate is not trusted. 76 +browsers will complain that the certificate is not trusted. That's ok.
72 77
73 ```bash 78 ```bash
74 cd ~/.local/share/certs 79 cd ~/.local/share/certs
@@ -92,33 +97,28 @@ the following methods: @@ -92,33 +97,28 @@ the following methods:
92 ```bash 97 ```bash
93 cd ~/perguntations/demo 98 cd ~/perguntations/demo
94 99
95 -initdb students.csv # initialize from a CSV file  
96 -initdb --admin # only adds the administrator account  
97 -initdb --add 123 "Asterix Gaules" # add one student 100 +initdb students.csv # initialize from a CSV file
  101 +initdb --admin # only adds the administrator account
  102 +initdb --add 123 "Asterix Gaules" # add one student
98 ``` 103 ```
99 104
100 This will create or update a `students.db` file that contains a sqlite3 105 This will create or update a `students.db` file that contains a sqlite3
101 database. 106 database.
102 -The database stores user passwords, and grades of the tests submitted by the  
103 -students. 107 +The database stores user passwords and grades (but not the actual tests).
104 108
105 -The actual tests are stored in JSON files in the following directory: 109 +The complete tests are stored in JSON files in the following directory:
106 110
107 ```bash 111 ```bash
108 -mkdir ans # directory where the student tests are saved 112 +mkdir ans # directory where the tests will be saved
109 ``` 113 ```
110 114
111 A test is specified in a single `yaml` file. 115 A test is specified in a single `yaml` file.
112 -The demo already includes one: 116 +The demo already includes the `tutorial.yaml` that you can play with.
113 117
114 -```bash  
115 -$EDITOR tutorial.yaml # edit test configuration  
116 -```  
117 -  
118 -To start the server with this test run: 118 +Start the server and run this test:
119 119
120 ```bash 120 ```bash
121 -perguntations tutorial.yaml # run demo test 121 +perguntations tutorial.yaml # run demo test
122 ``` 122 ```
123 123
124 Several options are available, run `perguntations --help` for a list. 124 Several options are available, run `perguntations --help` for a list.
@@ -135,13 +135,15 @@ Answer the questions and submit. You should get a grade at the end. @@ -135,13 +135,15 @@ Answer the questions and submit. You should get a grade at the end.
135 135
136 The server can be stoped from the terminal with `^C`. 136 The server can be stoped from the terminal with `^C`.
137 137
138 -## Running on lower ports 80 or 443 138 +---
  139 +
  140 +## Running on lower ports
139 141
140 Ports 80 and 443 are reserved for the root user and and this software **should 142 Ports 80 and 443 are reserved for the root user and and this software **should
141 NOT be run as root**. 143 NOT be run as root**.
142 -Instead, the firewall should be configured to forward tcp traffic from port 443  
143 -to 8443 where the server is listening.  
144 -The details depend on the operating system. 144 +Instead, tcp traffic can be forwarded from port 443 to 8443 where the server is
  145 +listening.
  146 +The details depend on the operating system/firewall.
145 147
146 ### debian: 148 ### debian:
147 149
@@ -216,6 +218,7 @@ sudo service pf start # start firewall @@ -216,6 +218,7 @@ sudo service pf start # start firewall
216 Again, copy certificate files `privkey.pem` and `cert.pem` to the `certs` 218 Again, copy certificate files `privkey.pem` and `cert.pem` to the `certs`
217 directory. 219 directory.
218 220
  221 +---
219 222
220 ## Troubleshooting 223 ## Troubleshooting
221 224
@@ -238,6 +241,8 @@ Solutions: @@ -238,6 +241,8 @@ Solutions:
238 :lang=en_US.UTF-8: 241 :lang=en_US.UTF-8:
239 ``` 242 ```
240 243
  244 +---
  245 +
241 ## Contribute ### 246 ## Contribute ###
242 247
243 * Writing questions in yaml format 248 * Writing questions in yaml format