Ajustes documentacao

doc/ATUALIZACAO.md

@@ -0,0 +1,84 @@
+# Procedimento de Atualização
+
+Este documento descreve os passos necessários para atualizar a aplicação DNSBlock para a nova versão, incluindo a aplicação de migrações no banco de dados.
+
+## 1. Backup do Banco de Dados (Recomendado)
+
+Antes de qualquer atualização, é altamente recomendável fazer um backup do banco de dados atual para evitar perda de dados em caso de falhas.
+
+```bash
+make backup
+# O backup será salvo na pasta backups/
+```
+
+## 2. Atualização do Código-Fonte
+
+Baixe as atualizações mais recentes do repositório (se estiver usando git) ou substitua os arquivos da aplicação pela nova versão.
+
+```bash
+git pull origin main
+```
+
+## 3. Reconstrução e Reinício dos Containers
+
+Após atualizar o código, é fundamental reconstruir a imagem Docker da aplicação e reiniciar os containers. Isso garante que as novas configurações de ambiente (como aumento do limite de upload do PHP) sejam aplicadas corretamente.
+
+```bash
+docker compose up -d --build
+```
+
+*(Nota: O comando `make restart` do Makefile apenas reinicia os containers, mas não força a reconstrução da imagem. Portanto, para atualizações de versão, utilize o comando acima).*
+
+## 4. Aplicação das Migrações de Banco de Dados (SQL)
+
+As atualizações que alteram a estrutura do banco de dados incluem arquivos `.sql` na pasta `database/migrations/`. Para aplicá-los, utilize o comando `docker exec` direcionando o arquivo para o container do MySQL.
+
+Para aplicar a migração mais recente referente ao suporte a anexos nas ordens judiciais, execute na raiz do projeto:
+
+```bash
+docker exec -i dnsblock-db mysql -u root -p"$(grep DB_ROOT_PASSWORD .env | cut -d '=' -f2 | tr -d '\r')" dnsblock < database/migrations/2026_03_12_create_order_attachments.sql
+```
+
+**Regra Geral para Migrações:**
+Caso existam múltiplas migrações que ainda não foram aplicadas em seu ambiente de produção, aplique-as uma a uma, respeitando a ordem cronológica dos prefixos dos arquivos (ex: `2025_...`, `2026_...`). Exemplo genérico:
+```bash
+docker exec -i dnsblock-db mysql -u root -p"$(grep DB_ROOT_PASSWORD .env | cut -d '=' -f2 | tr -d '\r')" dnsblock < database/migrations/ARQUIVO_DE_MIGRACAO.sql
+```
+
+## 5. Permissões de Diretório (Armazenamento Persistente)
+
+Para garantir que a aplicação consiga salvar arquivos enviados (como os PDFs de anexos) no diretório mapeado para o hospedeiro, é obrigatório ajustar as permissões do diretório `storage`.
+
+Após os containers estarem em execução, rode o seguinte comando na raiz do projeto para conceder a posse e permissão correta ao usuário do container web (`www-data`):
+
+```bash
+docker exec dnsblock-app chown -R www-data:www-data /var/www/html/storage
+docker exec dnsblock-app chmod -R 775 /var/www/html/storage
+```
+
+## 6. Validação da Atualização
+
+1. Acesse o sistema pelo navegador.
+2. Limpe o cache do navegador (CTRL + F5) para garantir o carregamento de novos scripts, se houver.
+3. Valide o funcionamento das novas entregas (ex: anexe um arquivo grande na página de Ordens Judiciais).
+4. Verifique os logs se encontrar algum problema de comunicação:
+   ```bash
+   make logs
+   ```
+
+## 7. Limpeza e Otimização (Opcional)
+
+Após a atualização bem-sucedida, é recomendado realizar uma limpeza no ambiente Docker para remover compilações antigas (imagens) e dados que não são mais utilizados, liberando espaço em disco no servidor.
+
+**Atenção:** Os comandos abaixo não afetarão conteinêres em execução nem os volumes que estão associados a eles (seus dados estarão seguros).
+
+Para remover **imagens antigas**, containers parados e redes não utilizadas:
+```bash
+docker system prune -f
+```
+
+Se você mudou volumes recentemente (como na migração do banco de dados) e tem certeza de que os **volumes antigos não são mais necessários**:
+```bash
+docker volume prune -f
+```
+*(Nota: O comando de volumes remove TODOS os volumes Docker na máquina que não estejam atrelados a um container ativo. Use com cautela se houver outras aplicações no mesmo servidor).*