Update README

README.md

@@ -1,15 +1,43 @@
-# Guia de instalação e configuração do Helios
-
 > This README is intended for Portuguese audience
 > 
+
+
+- [Guia de instalação e configuração do Helios](#guia-de-instalação-e-configuração-do-helios)
+  - [Personalizações feitas no Helios](#personalizações-feitas-no-helios)
+  - [Instalação dos pacotes necessários (Ubuntu 18.04)](#instalação-dos-pacotes-necessários-ubuntu-1804)
+    - [Softwares necessários](#softwares-necessários)
+  - [Preparação do ambiente para instalação do Helios](#preparação-do-ambiente-para-instalação-do-helios)
+    - [Configuração do banco de dados PostgreSQL](#configuração-do-banco-de-dados-postgresql)
+    - [Compilando arquivos com as traduções para português](#compilando-arquivos-com-as-traduções-para-português)
+    - [Configuração dos módulos de autenticação](#configuração-dos-módulos-de-autenticação)
+      - [Autenticação em uma base LDAP](#autenticação-em-uma-base-ldap)
+    - [Testando a instalação em ambiente de desenvolvimento](#testando-a-instalação-em-ambiente-de-desenvolvimento)
+    - [Habilitando usuário com permissão de gestor de eleições](#habilitando-usuário-com-permissão-de-gestor-de-eleições)
+  - [Preparando ambiente de produção](#preparando-ambiente-de-produção)
+    - [Configuração apache](#configuração-apache)
+    - [Celery](#celery)
+  - [Configurações Gerais:](#configurações-gerais)
+  - [Outras personalizações feitas no Helios](#outras-personalizações-feitas-no-helios)
+    - [Habilitar Interface de Administração do Django](#habilitar-interface-de-administração-do-django)
+    - [Listar eleições na página inicial do Helios](#listar-eleições-na-página-inicial-do-helios)
+    - [Autenticação federada via shibboleth](#autenticação-federada-via-shibboleth)
+      - [Configuração da autenticação com o módulo apache shibboleth2](#configuração-da-autenticação-com-o-módulo-apache-shibboleth2)
+      - [Habilitando instituições da federação para usarem o serviço Helios](#habilitando-instituições-da-federação-para-usarem-o-serviço-helios)
+  - [Usando docker para desenvolvimento](#usando-docker-para-desenvolvimento)
+  - [Alguns lembretes finais cruciais para o ambiente de produção](#alguns-lembretes-finais-cruciais-para-o-ambiente-de-produção)
+
+# Guia de instalação e configuração do Helios
+
 > Este é um repositório particular em que novas funcionalidades, atualizações e outras atividades de interesse particular ou de pesquisa são realizadas. 
 > 
 > Se você está interessado em informações sobre o repositório de uso no IFSC (http://www.ifsc.edu.br), por favor acesse https://github.com/ifsc/helios-server
 
+
 Neste tutorial são descritos os principais passos para disponibilização do Helios em um servidor com a distribuição Linux Ubuntu (testado nas versões LTS 14.04, 16.04 e 18.04), embora já tenha sido feita instalação com sucesso no CentOS. 
 
 Para seguir esse tutorial é necessário tenha alguma experiência com administração de sistemas Linux (instalação de pacotes, configuração de serviços, etc.).
 
+
 ## Personalizações feitas no Helios
 
 Esse repositório contém as personalizações feitas no Helios. Ainda assim, buscará o sincronismo periódico com (sempre que possível e dentro do tempo possível) o projeto original do [Ben Adida](https://github.com/benadida/helios-server).
@@ -206,28 +234,38 @@ Execute o seguinte comando:
 python manage.py runserver 0.0.0.0:8000
 ```
 
-Abra um outro terminal para deixar o [celery](https://docs.celeryproject.org/en/stable/) em execução. Essa parte é importante, pois é celery quem vai gravar os votos, enviar emails, processar o arquivo de eleitores, etc.
+Além disso, você precisa ter o celery rodando, pois algumas tarefas como processamento de arquivo de eleitores e envio de emails dependem dele.
+
+Abra um outro terminal para deixar o [celery](https://docs.celeryproject.org/en/stable/) em execução. Se você estiver usando o virtualenv, lembre-se de ativá-lo nesse novo terminal também.
+
 
 ```bash
-python manage.py celeryd
+celery -A helios worker -l info
 ```
 
+> Refrisando, essa parte é importante, pois é o celery responsável pelas tarefas de gravação dos votos, envio de emails, processamento do arquivo de eleitores, etc.
+
+
 Feito isso, você pode acessar a URL http://endereco-do-seu-servidor-helios e se autenticar com algum usuário presente em sua base LDAP (ou um usuário de algum outro sistema de autenticação que tenha habilitado para o Helios).
 
-Esse usuário não conseguirá criar eleições ainda, mas esse passo é necessário para que seja criada uma entrada para esse usuário na base. No próximo passo, usaremos a aplicação `admin` do django para dar privilégio de gestor de eleição para esse usuário.
+Esse usuário não conseguirá criar eleições ainda, mas esse passo é necessário para que seja criada uma entrada para esse usuário na base. No próximo passo, [Habilitando usuário com permissão de criar eleições](#habilitando-usuário-com-permissão-de-criar-eleições),usaremos a aplicação `admin` do django para dar privilégio de gestor de eleição para esse usuário. 
+
+### Habilitando usuário com permissão de gestor de eleições
 
 Acesse a URL http://endereco-do-seu-servidor-helios/admin e se autentique com o usuário e senha de administração (você fez isso quando executou o script `reset.sh`). 
 
+>*Observação*: Se você não lembra qual senha você criou, mas lembra o usuário, então é possível mudar a senha executando o comando `python manage.py changepassword <usuario>`
+
 Na página de administração são apresentados os *apps* habilitados. Localize a opção `Helios_Auth` e clique em *Users*. Na página seguinte, escolha o usuário que você deseja editar (basta clicar somente o login do mesmo). Na página de edição, marque a opção *Admin_p* e salve.
 
 Pronto! O usuário em questão recebeu o papel de **gestor de eleição** e será capaz de criar e gerenciar eleições com o Helios.
 
-> **Atenção**: só será possível dar o privilégio `admin_p` para usuários que se autenticaram previamente na aplicação Helios
+> **Atenção**: só será possível dar o privilégio `admin_p` para usuários que se autenticaram previamente na aplicação Helios. Isso se deve à lógica de criação desse login, que é feita durante o login do usuário, caso ainda não exista. 
 
 
 ## Preparando ambiente de produção
 
-O servidor web usado na seção anterior é apenas para desenvolvimento e não deve ser usado em um ambiente de produção. 
+Na seção anterior foi usado o servidor web de desenvolvimento provido pelo próprio Django (`python manage.py runserver 0.0.0.0:8000`). No entanto, ele é apenas para desenvolvimento e **não deve** ser usado em um ambiente de produção.
 
 É possível trabalhar com diversos servidores web, porém no caso em questão optou-se pelo [Apache](https://docs.djangoproject.com/en/1.8/topics/install/#install-apache-and-mod-wsgi).
 
@@ -242,7 +280,7 @@ Para configurar o `httpd.conf` ou equivalente, siga as instruções em [How to u
 
 A parte de servir os arquivos estáticos é a mais trabalhosa. Essa configuração é necessária porque no servidor de desenvolvimento o django serve esses arquivos, porém na produção, eles precisam ser configurados para serem servidos pelo servidor *web*.
 
-Os arquivos estáticos não servidos pelo django são os "tradicionais":  css, javascript e imagens, por exemplo. Para coletar esses arquivos, é preciso executar o comando `collectstatic`, conforme descrito em [Collect static app](https://docs.djangoproject.com/en/1.8/ref/contrib/staticfiles//).
+Os arquivos estáticos não servidos pelo django são os "tradicionais":  css, javascript e imagens, por exemplo.
 
 No caso do Helios em particular, há módulos sendo servidos estaticamente (total ou parcial): o `heliosbooth` e o `heliosverifier`, os quais também precisam ser configurados.
 
@@ -255,8 +293,9 @@ Alias /booth /`<path_to_site>`/sitestatic/booth
 Alias /verifier /`<path_to_site>`/sitestatic/verifier
 ```
 
-Além desses, todos os demais arquivos a serem servidos diretamente pelo apache, como os do módulo `admin` do django estão com links simbólicos no diretório `sitestatic`, que está sob controle do git. Ou seja, não é necessário rodar o comando `collectstatic`, apenas configurar o apache para apontar para o diretório `sitestatic` contido neste projeto, conforme exemplo de configuração acima.
+Além desses, todos os demais arquivos a serem servidos diretamente pelo apache, como os do módulo `admin` do django estão com links simbólicos no diretório `sitestatic`, que está sob controle do git. 
 
+Ou seja, se você clonar este projeto e utilizar a estrutura tal como está, não é necessário rodar o comando `collectstatic`, apenas configurar o apache para apontar para o diretório `sitestatic` contido neste projeto, conforme exemplo de configuração acima. Normalmente, para coletar esses arquivos, é preciso executar o comando `collectstatic`, conforme descrito em [Collect static app](/https://docs.djangoproject.com/en/1.11/ref/contrib/staticfiles/).
 
 >**Observações:**
 >
@@ -270,26 +309,31 @@ Lembrando mais uma vez que o [celery](http://www.celeryproject.org/) precisa est
 
 Em produção é interessante rodar o celery com múltiplos processos, para acelerar por exemplo envio de emails.  Na prática, 5 processos em paralelo se mostrou suficiente. 
 
-O *script* `check-services.sh` foi criado para verificar se o serviço celery está execução e contém o comando para executar o celery com 5 processos paralelos. Ele pode ser adicionado à crontab, como no exemplo abaixo, no qual ele executa de 10 em 10 minutos.
+Com a atualização para o Django 1.11.28, o celery foi atualizado para a versão [4.2.1](https://docs.celeryproject.org/en/v4.2.1/index.html), na qual ele não depende mais de uma biblioteca separada para trabalhar com o Django (no caso, era usada a django-celery). Agora o celery suporta o  Django [*out of the box*](https://docs.celeryproject.org/en/v4.2.1/django/first-steps-with-django.html#using-celery-with-django). Essa alteração fez com que não fosse mais necessária a biblioteca django-celery, assim como mudou o *message broker* utilizado para a fila de mensagens. Não é mais possível utilizar a própria base de dados para enfileirar as mensagens. Dentre as opções disponíveis estão o RabbitMQ e o Redis, por exemplo. Tanto para o RabbitMQ como para o Redis, é necessário instalar os pacotes necessários. Optou-se pelo uso do Redis e se você optar por ele também, no diretório [docker](docker) há exemplo de configuração dele pra rodar supervisionado pelo supervisor, assim como no Dockerfile há indicação do pacote necessário (redis-server).
 
-```bash
-*/10 * * * *  /var/www/helios-server/check-services.sh >/dev/null 2>&1
-```
+Também mudou a forma como o celery é executado. Como agora não é utilizado através de uma biblioteca separada para trabalhar com o django, bastar rodar direto o próprio celery, como por exemplo:
 
-Nesse mesmo *script*, também é verificado o [celery beat](http://docs.celeryproject.org/en/latest/userguide/periodic-tasks.html), agendador de tarefas periódicas, como limpar a tabela `celery_taskmeta`, que mantém o *log* das tarefas e pode crescer bastante.
+`celery -A helios worker -l info --concurrency=5`
 
->**Observação:**
->Gerenciar esses processos com o [supervisor](http://supervisord.org/introduction.html) é mais recomendado, em momento oportuno essa documentação será atualizada com exemplos.
 
-No arquivo `settings.py` no presente repositório, colocou-se 60 dias como o prazo para apagar essas tarefas:
+Para que o resultado da execução das tarefas seja guardado no backend, adicionou-se o app `django_celery_results` e o `django_celery_beat` em INSTALLED_APPS.
 
-```bash
-CELERYBEAT_SCHEDULER = 'djcelery.schedulers.DatabaseScheduler'
+O celery beat, agendador de tarefas periódicas, como limpar a tabela de resultados de execução de tarefas de tempos em tempos (o que pode crescer bastante), pode ser executado pelo comando celery, mas passando o parâmetro *beat* ao invér de *worker*:
+
+`celery -A helios beat -l info`
 
-CELERY_TASK_RESULT_EXPIRES = 5184000 # 60 days
+No arquivo [`settings.py`](settings.py) , colocou-se 60 dias como o prazo para apagar essas tarefas:
+
+```bash
+CELERY_RESULT_EXPIRES = 5184000 # 60 days
 ```
 
-Após iniciar o celery beat, é possível ver uma tarefa periódica criada por meio da interface administrativa do django, sob Djecelery, periodic tasks. Se não desejar limpar da tabela dessa forma, basta não iniciar o celery beat.
+Se não desejar limpar da tabela de resultados das tarefas (`django_celery_results_taskresult`) dessa forma, basta não iniciar o celery beat.
+Conforme documentação, a tarefa de limpeza dessa tabela, considerando o prazo de expiração configurado, executa todo dia às 4 horas da manhã (GMT-3, então 1:00 da madrugada horário de Brasília). É possível ver esses resultados direto no banco na tabela `django_celery_results_taskresult` ou então via interface administrativa do django, na seção Celery Results -> Task results. A aplicação responsável por guardar esses resultados no backend do Django é a [django-celery-results)[https://docs.celeryproject.org/en/v4.2.1/django/first-steps-with-django.html#extensions].
+
+
+>**Observação:**
+>Todos esses processos podem ser gerenciados com o [supervisor](http://supervisord.org/introduction.html). Você encontra exemplos de uso em [docker/supervisor](docker/supervisor/)
 
 ## Configurações Gerais:
 
@@ -301,18 +345,29 @@ Após iniciar o celery beat, é possível ver uma tarefa periódica criada por m
 - Para que qualquer usuário que se logar no sistema possa receber automaticamente o papel de **gestor de eleição**, e por consequência, receber o privilégio para criar e gerir eleições, edite o arquivo `settings.py` e deixe como `False` a opção `HELIOS_ADMIN_ONLY`
 
 
-## Personalizações feitas no Helios
+## Outras personalizações feitas no Helios
+
+Além do que já foi relatado na seção [Personalizações feitas no Helios](#personalizações-feitas-no-helios), detalhamos aqui algumas das personalizações realizadas. 
+
+### Habilitar Interface de Administração do Django
+
+O projeto original do Helios não vem com essa aplicação habilitada. [A interface de administração automática](https://docs.djangoproject.com/en/1.11/ref/contrib/admin/) facilita algumas atividades de gerenciamento dentro da organização, como por exemplo dar permissão de criação de eleição para um usuário. Você encontra diversas referências a essa interface ao longo deste tutorial.
 
 ### Listar eleições na página inicial do Helios
 
-Outra personalização disponível, acessível por meio da aplicação de administração do django, é a opção de listar ou não uma eleição na página pública inicial do sistema. Se você quiser que uma eleição seja listada na página inicial do Helios, faça:
+Nessa personalização, as eleições que são listadas na página inicial são as que são explicitamente marcadas dessa forma via interface de administração do django (o módulo /admin que foi adicionado neste *fork*).
+
+Se você quiser que uma eleição seja listada na página inicial do Helios, faça:
 - Na página de administração do Django, localize a opção `Helios` e clique em *Elections*. 
 - Na página seguinte, clique no nome da eleição que você gostaria que fosse listada na página pública e na tela de edição, marque a opção *Featured p* e salve.
 
 ### Autenticação federada via shibboleth
 
 Para a utilização federada do Helios, diversas personalizações foram efetuadas tanto na página pública, quando na parte de gerenciamento de eleições. Essas personalizações estão hoje no ramo `helios_shibboleth` e somente no repositório https://github.com/shirlei/helios-server. 
 
+> Obs.: como esse branch não foi integrado ao branch principal, e desde a última versão estável várias atualizações, incluindo versões de software foram realizadas no branch principal(master), o branch `helios_shibboleth` precisará de trabalho de merge e resolução de possíveis conflitos.
+
+
 #### Configuração da autenticação com o módulo apache shibboleth2
 
 Além do módulo de autenticação LDAP, também foi desenvolvido um módulo de autenticação considerando o módulo shibboleth2 para o Apache. Nesse caso, o Helios funciona como um Provedor de Serviço (Service Provider - SP).