- updated BUGS and README

Miguel Barão
1 parent 189342c6
Showing 2 changed files with 29 additions and 15 deletions Show diff stats
BUGS.md
README.md
  
 # BUGS
  
+- se submissão falhar (aluno desconectado da rede) nao pode sair da página para nao perder o teste. possiveis solucoes:
+  - botao submeter valida se esta online com um post willing_to_submit, se estiver online, mostra mensagem de confirmacao, caso contrario avisa que nao esta online.
+  - periodicamente, cada user faz um post keep-alive. warning nos logs se offline.
+  - Cada pergunta respondida é logo submetida.
+
 - ctrl-c should ask for confirmation before exiting.
 - eventos unfocus?
 - servidor nao esta a lidar com eventos scroll/resize. ignorar?
@@ -10,10 +10,8 @@
  
 The webserver is a python application and requires `python3.6` and `pip` to be installed, plus the following additional packages:
  
-- ~~CherryPy~~
-- ~~Mako~~
 - tornado
-- Markdown
+- mistune
 - PyYAML
 - Pygments
 - SQLAlchemy
@@ -24,30 +22,40 @@ These can be installed for a single user (recommended), in a python virtual envi
 #### Installing packages for a single user (recommended)
  
 ```.bash
-pip3 install --user tornado markdown pyyaml pygments sqlalchemy bcrypt
+pip3 install --user tornado mistune pyyaml pygments sqlalchemy bcrypt
 ```
  
 #### Installing packages in a virtual environment (alternative)
  
-```.bash
+```bash
 pyvenv-3.6 venv/perguntations              # or other virtualenv directory
 source venv/perguntations/bin/activate     # activate virtualenv
  
-pip3 install tornado markdown pyyaml pygments sqlalchemy bcrypt
+pip3 install tornado mistune pyyaml pygments sqlalchemy bcrypt
 ```
  
 #### Installing packages system wide (alternative)
  
 I personally prefer python packages to be installed for a single user, but if a system wide installation is required, it is probably better to use the operating system package manager instead of `pip`:
  
-- Linux: apt-get, etc
-- macOS: macports, etc
+Linux: 
+
+```bash
+apt-get install py36-tornado py36-mistune? py36-yaml py36-pygments...
+```
+
+macOS macports: 
+
+```bash
+port install py36-py36-tornado py36-mistune? py36-yaml py36-pygments...
+```
+
  
 ### Install and setup perguntations
  
 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:
  
-```.bash
+```bash
 cd WHERE/TO/PUT/THE/SOFTWARE
 git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
 ```
@@ -69,9 +77,10 @@ Copy certificates `cert.crt` and `cert.key` to the `perguntations/certs/` direct
  
 Self-signed certificates are not certified by a recognised authority and browsers will complain that the certificate is not trusted.
  
-TODO: explain...
-
-Copy certificates `cert.crt` and `cert.key` to the `perguntations/certs/` directory.
+```bash
+cd perguntations/certs/
+openssl req -x509 -newkey rsa:4096 -keyout cert.key -out cert.crt -days -nodes
+```
  
 ## Running a demo
  
@@ -92,14 +101,14 @@ mv students.db demo/
 mkdir demo/ans
  
 # edit test configuration and check if everything looks right
-vi demo/test.yaml
+vi demo/test-tutorial.yaml
 ```
  
 We are now ready to run the server:
  
 ```.bash
-./serve.py --help            # get help
-./serve.py demo/test.yaml    # run demo test
+./serve.py --help                     # get help
+./serve.py demo/test-tutorial.yaml    # run demo test
 ```
  
 By default the server listens on port 8443 and on all IPs of all network interfaces.
1	1
2	2	# BUGS
3	3
	4	+- se submissão falhar (aluno desconectado da rede) nao pode sair da página para nao perder o teste. possiveis solucoes:
	5	+ - botao submeter valida se esta online com um post willing_to_submit, se estiver online, mostra mensagem de confirmacao, caso contrario avisa que nao esta online.
	6	+ - periodicamente, cada user faz um post keep-alive. warning nos logs se offline.
	7	+ - Cada pergunta respondida é logo submetida.
	8	+
4	9	- ctrl-c should ask for confirmation before exiting.
5	10	- eventos unfocus?
6	11	- servidor nao esta a lidar com eventos scroll/resize. ignorar?
...	...
...	...	@@ -10,10 +10,8 @@
10	10
11	11	The webserver is a python application and requires `python3.6` and `pip` to be installed, plus the following additional packages:
12	12
13		-- ~~CherryPy~~
14		-- ~~Mako~~
15	13	- tornado
16		-- Markdown
	14	+- mistune
17	15	- PyYAML
18	16	- Pygments
19	17	- SQLAlchemy
...	...	@@ -24,30 +22,40 @@ These can be installed for a single user (recommended), in a python virtual envi
24	22	#### Installing packages for a single user (recommended)
25	23
26	24	```.bash
27		-pip3 install --user tornado markdown pyyaml pygments sqlalchemy bcrypt
	25	+pip3 install --user tornado mistune pyyaml pygments sqlalchemy bcrypt
28	26	```
29	27
30	28	#### Installing packages in a virtual environment (alternative)
31	29
32		-```.bash
	30	+```bash
33	31	pyvenv-3.6 venv/perguntations # or other virtualenv directory
34	32	source venv/perguntations/bin/activate # activate virtualenv
35	33
36		-pip3 install tornado markdown pyyaml pygments sqlalchemy bcrypt
	34	+pip3 install tornado mistune pyyaml pygments sqlalchemy bcrypt
37	35	```
38	36
39	37	#### Installing packages system wide (alternative)
40	38
41	39	I personally prefer python packages to be installed for a single user, but if a system wide installation is required, it is probably better to use the operating system package manager instead of `pip`:
42	40
43		-- Linux: apt-get, etc
44		-- macOS: macports, etc
	41	+Linux:
	42	+
	43	+```bash
	44	+apt-get install py36-tornado py36-mistune? py36-yaml py36-pygments...
	45	+```
	46	+
	47	+macOS macports:
	48	+
	49	+```bash
	50	+port install py36-py36-tornado py36-mistune? py36-yaml py36-pygments...
	51	+```
	52	+
45	53
46	54	### Install and setup perguntations
47	55
48	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:
49	57
50		-```.bash
	58	+```bash
51	59	cd WHERE/TO/PUT/THE/SOFTWARE
52	60	git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
53	61	```
...	...	@@ -69,9 +77,10 @@ Copy certificates `cert.crt` and `cert.key` to the `perguntations/certs/` direct
69	77
70	78	Self-signed certificates are not certified by a recognised authority and browsers will complain that the certificate is not trusted.
71	79
72		-TODO: explain...
73		-
74		-Copy certificates `cert.crt` and `cert.key` to the `perguntations/certs/` directory.
	80	+```bash
	81	+cd perguntations/certs/
	82	+openssl req -x509 -newkey rsa:4096 -keyout cert.key -out cert.crt -days -nodes
	83	+```
75	84
76	85	## Running a demo
77	86
...	...	@@ -92,14 +101,14 @@ mv students.db demo/
92	101	mkdir demo/ans
93	102
94	103	# edit test configuration and check if everything looks right
95		-vi demo/test.yaml
	104	+vi demo/test-tutorial.yaml
96	105	```
97	106
98	107	We are now ready to run the server:
99	108
100	109	```.bash
101		-./serve.py --help # get help
102		-./serve.py demo/test.yaml # run demo test
	110	+./serve.py --help # get help
	111	+./serve.py demo/test-tutorial.yaml # run demo test
103	112	```
104	113
105	114	By default the server listens on port 8443 and on all IPs of all network interfaces.
...	...