From dcece8435caac5685c735b5f5923ac722a17511b Mon Sep 17 00:00:00 2001 From: Guilherme Donato Date: Tue, 21 Mar 2017 01:06:33 -0300 Subject: [PATCH] created troubleshooting doc #15 --- doc/troubleshooting.md | 123 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 doc/troubleshooting.md diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md new file mode 100644 index 000000000..a42d05f12 --- /dev/null +++ b/doc/troubleshooting.md @@ -0,0 +1,123 @@ +Problemas Comuns +================ + +Nesse capítulo abordaremos alguns problemas frequentes que são encontrados por +pessoas que instalam o Login Cidadão e como solucioná-los. + +Alterei as configurações e nada mudou +------------------------------------- + +Isso acontece, principalmente quando acessamos no modo Produção, pois o Symfony +faz um cache das configurações. Sempre que você alterar suas configurações, seja +em `parameters.yml`, `config.yml` ou outros arquivos de configuração é imperativo +que o cache seja limpo. + +Para limpar o cache é recomendado usar o próprio comando do Symfony, entretanto, +em alguns casos, algumas alterações podem impedir seu correto funcionamento e +será necessário apagar, manualmente, as pastas de cache. + +O comando do Symfony, recomendado, é: + + ./app/console cache:clear -e prod + +Caso o comando não funcione corretamente você pode utilizar o comando a seguir +para limpar o cache do modo de produção e o do modo de desenvolvimento: + + rm -rf app/cache/{dev,prod} + +Alterei um arquivo e nada mudou +------------------------------- + +Assim como no problema anterior, isso ocorre com maior frequência quando é feito +acesso em modo de Produção. Quando um *asset* (CSS, JS, imagens...) é alterado, +é importante que sejam compilados novamente os *assets* através dos comandos do +Symfony, além de ser feita a limpeza do cache. + +Para gerar os *assets*, você pode utilizar os comandos `assets:install` e +`assetic:dump`, entretanto recomendamos que você utilize o `lc:deploy` que +cuidará de outros aspectos da instalação: + + ./app/console lc:deploy + +### Mas e em desenvolvimento? + +Certamente é muitíssimo inconveniente ficar executando comandos a cada alteração, +pois mesmo que esses comandos sejam automáticos a cada vez que o arquivo é salvo +eles demoram alguns segundos para concluir o processamento e isso não lhe trará +uma boa experiência como desenvolvedor. + +Desse modo, assumindo que você esteja desenvolvendo em ambiente *Linux*, é +recomendado que você instale os assets através de *symlinks* e que acesse o modo +de Desenvolvimento para que os *assets* compilados pelo componente *assetic* +sejam gerados em tempo de execução. + +Para instalar os *assets* usando *symlinks* basta utilizar o comando apropriado: + + ./app/console assets:install --symlink + +Para acessar o modo de Desenvolvimento basta utilizar `/app_dev.php` na frente +de suas URIs. Por exemplo: `https://seu.dominio/app_dev.php` ou +`https://seu.dominio/app_dev.php/login`. Entretanto para ter acesso seu IP/rede +deve estar listado no parâmetro `dev_allowed` do `parameters.yml`. + +Os emails não estão sendo enviados +---------------------------------- + +Esse é um dos problemas mais frequentes quando uma nova instalação está sendo +configurada e, em 99.9% dos casos, o problema está na configuração do arquivo +`parameters.yml` ou do servidor de envio de emails em si. Algumas dicas que +podemos dar são: + +### Configurações do `parameters.yml` + +Verifique se informou o endereço correto de seu servidor SMTP no parâmetro +`mailer_host` bem como as credenciais em `mailer_user` e `mailer_password`. +Certifique-se, também, de limpar o cache do Symfony após essas alterações. + +### Configurações do SMTP + +Certifique-se de que o servidor está aceitando as conexões do Login Cidadão e +que está configurado corretamente para enviar emails. Caso esteja enviando para +servidores utilizando IPv6 você deve ter um PTR configurado corretamente ou as +suas mensagens serão recusadas. Esse problema é bastante frequente quando são +enviados emails a servidores do Google e há, inclusive, +[documentação sobre isso](https://support.google.com/mail/answer/81126?p=IPv6AuthError&visit_id=1-636253930059328048-1270189812&rd=1#authentication). + +Caso tenha optado por enviar emails utilizando o *Gmail*, verifique se todos os +passos da [documentação do Symfony](http://symfony.com/doc/2.8/email/gmail.html) +foram seguidos, em especial a configuração de envio por "apps menos seguros", +conforme citado no fim do documento. + +Alterações em entidades não funcionam +------------------------------------- + +Para otimizar o processamento envolvendo bancos de dados, o *Doctrine* salva, +no *memcached*, um cache dos metadados gerados. Caso tenham sido feitas mudanças +em entidades do *Doctrine* ou quaisquer outras alterações no banco de dados e +isso esteja gerando erros, é possível que o cache do *Doctrine* no *memcached* +não esteja sendo limpo corretamente. + +Normalmente esse cache é limpo quando executamos o comando `lc:deploy`, mas é +possível que, por motivos que desconhecemos, essa limpeza de cache não seja +eficaz, o que resulta em erros onde o *Doctrine* espera que o banco de dados +esteja de uma forma diferente da que ele se encontra. + +Para sanar o problema você pode limpar o cache de metadados através do Symfony +utilizando o seguinte comando: + + ./app/console doctrine:cache:clear-metadata -e prod + +Caso o problema persista, será necessário apagar todo o cache, o que fará com +que todas as sessões sejam perdidas, infelizmente. Isso pode ser feito +reiniciando o serviço `memcached` ou conectando-se a ele via `telnet` e +executando o comando `flush_all` (linhas começando com `>` representam os +comandos que você deverá digitar): + + > telnet + Trying [ip do memcached]... + Connected to [ip do memcached]. + Escape character is '^]'. + > flush_all + OK + > quit + Connection closed by foreign host.