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
BUGS.md
  Diff comments   View file @1dfeb55
1 1  
2 2 # BUGS
3 3  
4   -- usar npm para instalar javascript
5 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 5 - a revisao do teste não mostra as imagens.
7 6 - melhorar o botao de autorizar (desliga-se), usar antes um botao?
... ... @@ -10,13 +9,13 @@ ou usar push (websockets?)
10 9 - pymips: nao pode executar syscalls do spim.
11 10 - perguntas checkbox [right,wrong] com pelo menos uma opção correcta.
12 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 12 - eventos unfocus?
15 13 - servidor nao esta a lidar com eventos scroll/resize. ignorar?
16 14 - Test.reset_answers() unused.
17 15  
18 16 # TODO
19 17  
  18 +- submissao fazer um post ajax?
20 19 - fazer package para instalar perguntations com pip.
21 20 - adicionar opcao para eliminar um teste em curso.
22 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 62  
64 63 # FIXED
65 64  
  65 +- usar npm para instalar javascript
66 66 - se aluno entrar com l12345 rebenta. numa funcao get_... ver imagem no ipad
67 67 - no test3 está contar 1.0 valores numa pergunta do tipo info? acontece para type: info, e não para type: information
68 68 - default correct in checkbox must be 1.0, so that the pairs (right,wrong) still work with `correct` left undefined.
... ...
README.md
  Diff comments   View file @1dfeb55
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 14 The webserver is a python application that requires `>=python3.6` and `pip` to be
12 15 installed. `npm` (Node package management) is also necessary to install the
13 16 javascript libraries.
14 17  
15 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 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 24 The file `pip.conf` should be configured to the following:
... ... @@ -28,11 +31,12 @@ user=yes
28 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 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 53  
50 54 The command `npm` installs the javascript libraries and `pip3` installs the
51 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 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 71 ```bash
67 72 mkdir -p ~/.local/share/certs
68 73 ```
69 74  
70 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 78 ```bash
74 79 cd ~/.local/share/certs
... ... @@ -92,33 +97,28 @@ the following methods:
92 97 ```bash
93 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 105 This will create or update a `students.db` file that contains a sqlite3
101 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 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 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 120 ```bash
121   -perguntations tutorial.yaml # run demo test
  121 +perguntations tutorial.yaml # run demo test
122 122 ```
123 123  
124 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 135  
136 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 142 Ports 80 and 443 are reserved for the root user and and this software **should
141 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 148 ### debian:
147 149  
... ... @@ -216,6 +218,7 @@ sudo service pf start # start firewall
216 218 Again, copy certificate files `privkey.pem` and `cert.pem` to the `certs`
217 219 directory.
218 220  
  221 +---
219 222  
220 223 ## Troubleshooting
221 224  
... ... @@ -238,6 +241,8 @@ Solutions:
238 241 :lang=en_US.UTF-8:
239 242 ```
240 243  
  244 +---
  245 +
241 246 ## Contribute ###
242 247  
243 248 * Writing questions in yaml format
... ...