diff --git a/README.md b/README.md index 2db4ac82a..8c0c07bcf 100644 --- a/README.md +++ b/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 ` + 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 /``/sitestatic/booth Alias /verifier /``/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,11 +345,19 @@ 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. @@ -313,6 +365,9 @@ Outra personalização disponível, acessível por meio da aplicação de admini 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).