O objetivo deste projeto era inicialmente atender a necessidade N.47 do Plano Diretor de TI (PDTI) de 2013 do Instituto Federal de Santa Catarina (IFSC). No entanto, logo percebeu-se que outras instituições, especialmente as de ensino, poderiam se beneficiar das melhorias realizadas por nós no projeto original do Ben Adida.
Sendo assim, com intuito de contribuir com o público brasileiro, optamos por manter nesse repositório todas as melhorias feitas para que outras instituições possam se beneficiar do trabalho realizado pelo IFSC em cima do projeto original. Ou seja, aquilo que é praxe na comunidade de software livre (compartilhar) e na comunidade acadêmica (referenciar trabalhos de terceiros). Da mesma forma, esperamos receber contribuições dessas instituições para melhorar o código aqui disponibilizado. :punch:
Nota: Pode-se constatar que de fato esse projeto está beneficiando o público brasileiro. Em 2013, antes desse projeto, o Helios só era usado por 2 instituições de ensino no Brasil e ambas parecem ter usado a versão original e não compartilharam o código. Em 2020 sabemos que a versão modificada pelo IFSC está sendo usada por pelo menos 20 instituições de ensino (Institutos Federais, Universidades Estaduais e Universidades Federais), por órgãos do poder executivo, por organizações e associações de classes. Muitas nos citaram :blush:, mas nem todas :worried:. E recebemos contribuições de uma dessas instituições :clap:.
Esse repositório contém as personalizações feitas pelo IFSC 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.
Personalizações e contribuições que fizemos que estão aqui e que não foram para o upstream:
Publicamos dois artigos sobre essas personalizações (os PDFs estão disponíveis abaixo):
Para saber um pouco mais, acesse http://dtic.ifsc.edu.br/sistemas/sistema-de-votacao-on-line-helios/
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.).
Obs.:
- Para instalação dos pacotes apresentados acima foi necessário editar o arquivo
/etc/apt/sources.liste adicionar na seguinte linha a opçãouniverse:deb http://archive.ubuntu.com/ubuntu bionic main universeDepois é só fazer um
sudo apt updatee instalar os pacotes apresentados acima com osudo apt install
- Pode ser necessário instalar também o pacote libq-dev em atualizações mais recentes do Ubuntu. A biblioteca psycopg2 foi atualizada para a versão 2.8.5 e há relatos de que esse pacote é necessário.
- A versão do Django utilizada nesta versão do Helios é a 1.11.28.
Recomendo que crie um usuário no sistema específico para o helios, por exemplo, usuário helios.
Editar o arquivo pg_hba.conf e inserir a linha:
Logo acima da linha:
local all all peer
inserir a seguinte linha:
local all helios md5
A configuração acima corrige o seguinte erro:
Exception Type: OperationalError
Exception Value:
FATAL: Peer authentication failed for user "helios"
Observação: Com a configuração padrão do postgresql só é possível se conectar nele a partir da máquina em que ele está instalado. Caso você queira se conectar na base com um cliente como o pgAdmin, sem abrir a configuração para conexão a partir de outra máquina, basta utilizar um túnel ssh. Editar
~/.ssh/confige inserir a entrada abaixo, substituindo os valores em letra maiúscula pelas configurações da sua instalação (e não esquecer que precisa haver uma conexão ssh aberta com o servidor do banco para que a configuração abaixo seja efetiva!):Host NOMEDOHOST User NOMEDOUSER Hostname ENDERECODOHOST Port PORTASSH LocalForward PORTALOCAL 127.0.0.1:PORTAREMOTA
Todas as instruções abaixo devem ser executadas com o usuário helios e não com o superusuário (root).
Baixe o código fonte desse repositório:
git clone https://github.com/ifsc/helios-server.git
Não é obrigatório, mas é uma boa prática, criar um ambiente virtual python para a disponibilização do Helios, pois isso permite separar as dependências do projeto e não interferir em outros sistemas na mesma máquina.
Instale o virtualenv por meio do pip:
pip install virtualenv
Dentro do diretório onde o Helios foi baixado, execute o comando:
virtualenv venv
Isso criará um ambiente virtual python dentro do subdiretório chamado venv. Por fim, carregue o script venv/bin/activate para fazer uso do ambiente virtual:
source venv/bin/activate
Com o ambiente virtual ativado, instale os pacotes que estão listados no arquivo requirements.txt:
pip install -r requirements.txt
ATENÇÃO: Utilize o
requirements.txtdeste repositório para instalar o pacotedjango-auth-ldape outros necessários para as personalizações que foram feitas no Helios. Lembrando também que apesar de se pretender manter este repositório atualizado com o do Ben Adida, não necessariamente vai ser simultâneo, então se você utilizar o dele, pode haver versões diferentes de pacotes.
Edite o arquivo settings.py e localize a seção databases. Adicione as informações para conexão no banco de dados, conforme o exemplo:
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'NAME': 'helios',
'USER': 'helios',
'HOST': 'localhost',
'PASSWORD': 'SENHADOHELIOS'
}}
Por fim, você precisará executar o script reset.sh (não faça como root) que fará a inicialização do esquema no banco de dados (criará as tabelas, etc.)
./reset.sh
Observação: Se tiver algum problema ao executar o script acima, provavelmente vai ser relacionado à configuração do PostgreSQL e, nesse caso, o Google é seu amigo. Porém, o erro mais comum é que você tenha executado o script como root e o
postgresacuse que não há um usuário root. Recomendo criar um usuário que não seja root (por exemplo, helios) e usar o mesmo nome para usuário do banco. Ou executar os comandos contidos no script com o usuário adequado do banco.
A interface do Helios foi traduzida para o português e assim é necessário que compile os arquivos de tradução, caso queira usar a tradução que fizemos. Execute o seguinte comando a partir do diretório do Helios:
python manage.py compilemessages -l pt_BR
Após a compilação, arquivos .mo devem ter sido gerados em locale/pt_BR/LC_MESSAGES
Observação: Para alterar alguma tradução é possível utilizar o aplicativo POEDIT, os mesmo editar diretamente os arquivos
django.poedjangojs.pono editor de texto de sua preferência.
Se você adicionou alguma mensagem nova para ser traduzida e gostaria que fossem adicionadas aos arquivos de tradução, execute os comandos abaixo.
python manage.py makemessages -l pt_BR
python manage.py makemessages -d djangojs -l pt_BR --ignore=venv
Observação: Para a coleta de mensagens de arquivos .js, se você tiver criado o diretório de virtualenv relativo ao diretório do helios e chamado de por exemplo
venv, você pode passar o parâmetro--ignore=venvconforme acima, para ignorar esse diretório.
Você precisará habilitar em settings.py os módulos de autenticação que deseja. Por exemplo, poderia usar os módulos de autenticação do projeto original e permitir a autenticação de usuários por meio de contas Google, Facebook ou Twitter.
Na seção abaixo apresentamos as configurações necessárias para permitir a autenticação de usuários de uma base LDAP. Se não tiver um servidor LDAP e só queira testar o Helios, então talvez possa ser interessante tentar com os outros módulos de autenticação citados acima.
Habilite o módulo LDAP em settings.py:
AUTH_ENABLED_AUTH_SYSTEMS = get_from_env('AUTH_ENABLED_AUTH_SYSTEMS', 'ldap').split(",")
A documentação da biblioteca utilizada pode ser encontrada em http://pythonhosted.org/django-auth-ldap/example.html. Ela não é muito completa, mas as configurações principais estão no settings.py e são: AUTH_LDAP_SERVER_URI, AUTH_LDAP_BIND_PASSWORD, e AUTH_LDAP_USER_SEARCH.
As opções AUTH_LDAP_BIND_DN e AUTH_LDAP_BIND_PASSWORD deverão ter um valor configurado se o servidor LDAP exigir autenticação de usuário mesmo que seja para fazer consultas.
Observação: Você pode testar a conexão usando o próprio teste unitário do app de autenticação. Para tal, edite o arquivo helios_auth/tests.py, altere o usuário (euclid) e senha (password) que estão no teste usando o servidor de testes LDAP da ForumSys para um usuário e senha válidos no LDAP que você configurou no arquivo settings.py e execute
python manage.py test helios_auth
Ao executar o script reset.sh, você teve que criar um usuário de administração do django. Isso se deve ao fato de aplicação admin estar habilitada no arquivo settings.py (django.contrib.admin), pois iremos utilizá-la em algumas personalizações feitas para este fork do Helios.
Observação: você sempre pode criar um novo usuário para o django admin site executando o comando
python manage.py createsuperuser
Se tudo estiver correto até aqui, agora você poderá executar o servidor web para desenvolvimento que é provido pelo próprio django. Use esse servidor somente para verificar se a instalação foi feita com sucesso, porém não use-o caso queira colocar o Helios no ambiente de produção.
Execute o seguinte comando:
python manage.py runserver 0.0.0.0:8000
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 em execução. Se você estiver usando o virtualenv, lembre-se de ativá-lo nesse novo terminal também.
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, 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.
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_ppara 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.
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.
Módulos a serem habilitados, para a configuração exemplo:
sudo a2enmod rewrite
sudo a2enmod ssl
Para configurar o httpd.conf ou equivalente, siga as instruções em How to use Django with Apache and mod_wsgi.
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.
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.
Como o enfoque deste repositório está no desenvolvimento de novas funcionalidades e especialmente na personalização do Helios para o uso por entidades brasileiras, optou-se por uma solução menos elegante para os arquivos estáticos, mas que simplifica muito:
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, 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.
Observações:
Neste repositório há um arquivo exemplo de configuração do Apache, o arquivo helios-ssl.conf. É um exemplo funcional para ambiente de homologação/dev com >Apache, mas é bastante similar à ambiente de produção, especialmente com relação aos alias necessários.
Em algumas instalações mais recentes usando Apache tem havido relatos de problemas (internal server erros, com logs com registro de segmentation fault ou >outros), para o qual se identificou que atualizando a biblioteca pyscopg2 (para psycopg2-2.8.5) e instalando a libpq-dev, resolvia. Obrigada ao pessoal do IF >Sudeste MG por compartilhar a solução.
Lembrando mais uma vez que o celery precisa estar em execução, pois ele é o enfileirador de tarefas, como a tarefa de envio de emails e a tarefa de registro de votos.
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.
Com a atualização para o Django 1.11.28, o celery foi atualizado para a versão 4.2.1, 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. 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 há exemplo de configuração dele pra rodar supervisionado pelo supervisor, assim como no Dockerfile há indicação do pacote necessário (redis-server).
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:
celery -A helios worker -l info --concurrency=5
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.
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
No arquivo settings.py , colocou-se 60 dias como o prazo para apagar essas tarefas:
CELERY_RESULT_EXPIRES = 5184000 # 60 days
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. Você encontra exemplos de uso em docker/supervisor
settings.py, configurar ALLOWED_HOSTS para o seu domínio. Exemplo:
# set a value for production environment, alongside with debug set to false
ALLOWED_HOSTS = get_from_env('ALLOWED_HOSTS', 'endereco-do-seu-servidor-helios').split(",")
settings.py e deixe como False a opção HELIOS_ADMIN_ONLYAlém do que já foi relatado na seção Personalizações feitas no Helios, detalhamos aqui algumas das personalizações realizadas.
O projeto original do Helios não vem com essa aplicação habilitada. A interface de administração automática 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.
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:
Helios e clique em Elections.Content type
Image
Digest
Size
262.1 MB
Last updated
almost 6 years ago
docker pull douglasanpa/helios-server