AgrSis Docs
Operação

Sistema de Modo de Manutenção

Sistema de Modo de Manutenção

📋 Visão Geral

Sistema profissional de página de manutenção para exibir aos usuários durante deploys e atualizações, eliminando a página "Bad Gateway" padrão do Nginx.

Características

  • ✅ Página HTML bonita e responsiva com loading animado
  • ✅ Auto-reload a cada 10 segundos - usuário não precisa atualizar manualmente
  • ✅ Configuração no Nginx para interceptar erros 502/503
  • ✅ Scripts de controle para ativar/desativar manualmente
  • ✅ Integração com deploy (opcional)

🎨 Página de Manutenção

A página exibe:

  • Logo do AgrSis com animação pulse
  • Título "Sistema em Atualização"
  • Spinner de loading animado
  • Lista do que está acontecendo:
    • ✅ Instalação de novas funcionalidades
    • ✅ Otimização de performance
    • ✅ Atualizações de segurança
  • Barra de progresso animada
  • Tempo estimado: 2-5 minutos
  • Auto-reload a cada 10 segundos

Visual

┌────────────────────────────────────┐
│                                    │
│           🟢 [Logo]                │
│                                    │
│    Sistema em Atualização          │
│                                    │
│  Estamos realizando melhorias...   │
│                                    │
│        [Spinner Animado]           │
│                                    │
│  O que está acontecendo?           │
│  ✅ Instalação de funcionalidades  │
│  ✅ Otimização de performance      │
│  ✅ Atualizações de segurança      │
│                                    │
│  ═══════════ [Progresso]           │
│                                    │
│  ⏱️ Tempo estimado: 2-5 minutos    │
│                                    │
└────────────────────────────────────┘

🚀 Setup Inicial (Uma vez)

1. Enviar arquivos para VPS

bash scripts/maintenance/setup-vps.sh

Isso irá:

  1. Criar diretório /opt/agrsis/maintenance na VPS
  2. Enviar o arquivo index.html
  3. Configurar permissões corretas

2. Configurar Nginx Proxy Manager

Acesse: http://dev.agrsis.com:81

Para cada proxy host (producer.agrsis.com, supplier.agrsis.com, api.agrsis.com):

  1. Clique no host
  2. Vá na aba "Advanced"
  3. Adicione no campo "Custom Nginx Configuration":
# Páginas de erro customizadas
error_page 502 503 504 /maintenance.html;

location = /maintenance.html {
    root /opt/agrsis/maintenance;
    internal;
}
  1. Clique em "Save"

3. Testar

# Ativar modo de manutenção
bash scripts/maintenance/enable.sh

# Acessar o site
open https://producer.agrsis.com

# Você deve ver a página de manutenção!

# Desativar
bash scripts/maintenance/disable.sh

💻 Uso no Dia a Dia

Modo Manual

Ativar Manutenção

cd /opt/agrsis
bash scripts/maintenance/enable.sh

Isso irá:

  • ✅ Parar containers: API, Frontends, Queue, Scheduler
  • ✅ Manter rodando: PostgreSQL e Redis
  • ✅ Criar flag .maintenance
  • ✅ Usuários veem página de manutenção

Desativar Manutenção

cd /opt/agrsis
bash scripts/maintenance/disable.sh

Isso irá:

  • ✅ Iniciar todos os containers novamente
  • ✅ Verificar saúde da API
  • ✅ Remover flag .maintenance
  • ✅ Sistema volta ao normal

Modo Automático (Durante Deploy)

Você pode integrar ao script de deploy adicionando:

# No início do deploy
ssh $VPS_HOST "cd /opt/agrsis && bash scripts/maintenance/enable.sh"

# ... deploy acontece aqui ...

# No final do deploy
ssh $VPS_HOST "cd /opt/agrsis && bash scripts/maintenance/disable.sh"

Exemplo de deploy com manutenção:

#!/bin/bash
# scripts/deploy/deploy-with-maintenance.sh

VPS_HOST="root@dev.agrsis.com"
VPS_PATH="/opt/agrsis"

echo "🔧 Ativando modo de manutenção..."
ssh $VPS_HOST "cd $VPS_PATH && bash scripts/maintenance/enable.sh"

echo "📦 Fazendo deploy..."
# ... seu código de deploy ...

echo "✅ Desativando modo de manutenção..."
ssh $VPS_HOST "cd $VPS_PATH && bash scripts/maintenance/disable.sh"

echo "🎉 Deploy concluído!"

🔍 Verificações

Verificar se página está acessível

# Na VPS
curl http://localhost/maintenance.html

# Ou via ssh
ssh root@dev.agrsis.com "curl -I http://localhost/maintenance.html"

Deve retornar 200 OK.

Verificar configuração do Nginx Proxy Manager

ssh root@dev.agrsis.com "docker exec -it npm cat /etc/nginx/conf.d/default.conf | grep maintenance"

Deve mostrar as linhas de configuração.

Testar erro 502

# Parar API para forçar erro 502
ssh root@dev.agrsis.com "cd /opt/agrsis && docker compose stop api"

# Acessar site - deve mostrar página de manutenção
curl https://producer.agrsis.com

# Religar API
ssh root@dev.agrsis.com "cd /opt/agrsis && docker compose start api"

📁 Estrutura de Arquivos

agrsis-v1/
├── maintenance/
│   ├── index.html                    # Página de manutenção HTML
│   ├── nginx-error-pages.conf        # Config para referência
│   └── README.md                     # (opcional)
│
├── scripts/
│   └── maintenance/
│       ├── enable.sh                 # Ativar modo manutenção
│       ├── disable.sh                # Desativar modo manutenção
│       └── setup-vps.sh              # Setup inicial na VPS
│
└── docs/
    └── MAINTENANCE_MODE.md           # Esta documentação

Na VPS (/opt/agrsis/):

/opt/agrsis/
├── maintenance/
│   ├── index.html
│   └── maintenance.html              # Cópia do index.html
├── scripts/
│   └── maintenance/
│       ├── enable.sh
│       └── disable.sh
└── .maintenance                      # Flag (criado quando ativo)

🎨 Customizações

Alterar Mensagem

Edite maintenance/index.html e modifique:

<h1>Sistema em Atualização</h1>
<p class="subtitle">
    Sua mensagem customizada aqui
</p>

Depois:

scp maintenance/index.html root@dev.agrsis.com:/opt/agrsis/maintenance/
ssh root@dev.agrsis.com "cp /opt/agrsis/maintenance/index.html /opt/agrsis/maintenance/maintenance.html"

Alterar Tempo de Auto-Reload

Edite o script no final do index.html:

// De 10 segundos para 5 segundos
setTimeout(() => {
    window.location.reload();
}, 5000);  // Era 10000

Alterar Tempo Estimado

<p class="time">
    ⏱️ Tempo estimado: 5-10 minutos  <!-- Era 2-5 minutos -->
</p>

Adicionar Logo Customizado

Substitua o SVG dentro de .logo-icon por:

<img src="/path/to/logo.png" alt="Logo" style="width: 48px; height: 48px;">

🔧 Troubleshooting

Página de manutenção não aparece

1. Verificar se arquivo existe:

ssh root@dev.agrsis.com "ls -lah /opt/agrsis/maintenance/"

2. Verificar permissões:

ssh root@dev.agrsis.com "chmod 644 /opt/agrsis/maintenance/*.html"

3. Verificar configuração do NPM:

4. Testar diretamente:

curl http://dev.agrsis.com/maintenance.html

Página aparece mesmo com sistema online

Isso significa que os containers não estão respondendo. Verifique:

ssh root@dev.agrsis.com "cd /opt/agrsis && docker compose ps"
ssh root@dev.agrsis.com "cd /opt/agrsis && docker compose logs api"

Auto-reload não funciona

Verifique se JavaScript está habilitado no navegador e se não há bloqueadores de script.

Nginx Proxy Manager não aplica configuração

  1. Salve a configuração
  2. Aguarde alguns segundos
  3. Force reload: docker restart npm (se necessário)

📊 Monitoramento

Ver quantas vezes entrou em manutenção

ssh root@dev.agrsis.com "grep -c 'Ativando modo' /var/log/syslog"

Ver última vez que entrou em manutenção

ssh root@dev.agrsis.com "stat /opt/agrsis/.maintenance"

Verificar se está em manutenção

ssh root@dev.agrsis.com "[ -f /opt/agrsis/.maintenance ] && echo 'SIM' || echo 'NÃO'"

🚨 Casos de Uso

Deploy Normal

# 1. Ativar manutenção
ssh root@dev.agrsis.com "cd /opt/agrsis && bash scripts/maintenance/enable.sh"

# 2. Fazer deploy
bash scripts/deploy/deploy.sh

# 3. Desativar manutenção
ssh root@dev.agrsis.com "cd /opt/agrsis && bash scripts/maintenance/disable.sh"

Manutenção de Banco de Dados

# 1. Ativar manutenção
ssh root@dev.agrsis.com "cd /opt/agrsis && bash scripts/maintenance/enable.sh"

# 2. Fazer backup
ssh root@dev.agrsis.com "cd /opt/agrsis && docker compose exec postgres pg_dump..."

# 3. Executar migrations
ssh root@dev.agrsis.com "cd /opt/agrsis && docker compose exec api php artisan migrate"

# 4. Desativar manutenção
ssh root@dev.agrsis.com "cd /opt/agrsis && bash scripts/maintenance/disable.sh"

Manutenção Programada

# Avisar usuários com antecedência
# Depois, no horário programado:

ssh root@dev.agrsis.com "cd /opt/agrsis && bash scripts/maintenance/enable.sh"

# ... realizar manutenção ...

ssh root@dev.agrsis.com "cd /opt/agrsis && bash scripts/maintenance/disable.sh"

🔐 Segurança

Evitar Acesso Direto ao Arquivo

A diretiva internal; no Nginx garante que o arquivo só é servido em caso de erro, não diretamente:

location = /maintenance.html {
    root /opt/agrsis/maintenance;
    internal;  # ← Importante!
}

Tente acessar diretamente:

curl https://producer.agrsis.com/maintenance.html
# Deve retornar: 404 Not Found

Só deve aparecer quando houver erro 502/503.

📚 Referências

🎉 Benefícios

Antes:

❌ Bad Gateway
❌ Nginx 502 Error
❌ Página genérica e feia
❌ Usuário não sabe o que está acontecendo
❌ Parece que o sistema quebrou

Depois:

✅ Página bonita e profissional
✅ Mensagem clara sobre atualização
✅ Loading animado (sistema está trabalhando)
✅ Auto-reload (volta sozinho)
✅ Tempo estimado informado
✅ Imagem profissional da empresa

Última atualização: 2025-01-13 Versão: 1.0

Guia de Deploy - AgrSis MVP

Sistema de Controle de Versão Automático

Copyright © 2026