Skip to content

instrucoes-nginx.md

Latest commit

 

History

History
512 lines (368 loc) · 12.9 KB

instrucoes-nginx.md

File metadata and controls

512 lines (368 loc) · 12.9 KB
Raw

GovBR Gateway - Guia de Instalação com Nginx

Sistema de redirecionamento para integração entre clientes da Betha Sistemas e o Login Único do GovBR usando Nginx.

📋 Requisitos para Prefeituras

Antes de instalar, certifique-se que:

✅ Domínio .gov.br configurado - O gateway deve estar em um domínio oficial da prefeitura ✅ Servidor Nginx disponível - Nginx configurado e funcionando ✅ Acesso de administrador - Para configurar o servidor ✅ Certificado SSL ativo - HTTPS é obrigatório para integração com GovBR

Escolha seu método de instalação:

🐳 Instalação com Docker:

  • ✅ Isolado em container
  • ✅ Não afeta outras aplicações do servidor
  • ✅ Fácil de remover e atualizar
  • ⚠️ Requer Docker instalado no servidor
  • ⏱️ 5 minutos

🖥️ Instalação Tradicional:

  • ✅ Controle total sobre configuração
  • ✅ Integração com servidor web existente
  • ✅ Melhor performance
  • ✅ Ideal para servidores governamentais
  • ⚠️ Requer conhecimento básico de Nginx
  • ⏱️ 15-30 minutos

Arquivos do Sistema

O gateway usa quatro pontos de entrada frontend:

  • login.html
  • beth.html
  • suite.html
  • logout.html

Cada página carrega o app.js hospedado pela Betha. O JavaScript identifica a rota visível no navegador, preserva a query string e realiza o redirecionamento.

Arquivos auxiliares (só para quem usa Docker):

  • docker-compose.yml - Configuração do Docker
  • Dockerfile - Receita para criar o container

🚀 INSTALAÇÃO COM DOCKER

Esta opção isola o sistema em um container. Ideal se você já usa Docker.

Passo 1: Baixe os arquivos

Baixe todos os arquivos deste projeto para uma pasta no seu computador.

Passo 2: Abra o terminal

  • Windows: Clique com botão direito na pasta → "Abrir no Terminal" ou "Git Bash Here"
  • Linux/Mac: Abra o terminal e navegue até a pasta com cd caminho/da/pasta

Passo 3: Inicie o sistema

Digite este comando e pressione Enter:

docker-compose up -d

O que vai acontecer: O Docker vai baixar tudo que precisa e iniciar o sistema. Isso pode demorar uns 2-3 minutos na primeira vez.

Passo 4: Teste se funcionou

Abra seu navegador e acesse:

http://localhost:8085/login

Se o navegador for redirecionado para o Login Betha/GovBR, funcionou! 🎉

Passo 5: Para parar o sistema

Quando quiser parar, digite:

docker-compose down

🔧 INSTALAÇÃO TRADICIONAL (Sem Docker)

Use esta opção se preferir instalar diretamente no servidor. Mais controle sobre a configuração.

Opção A: Linux (Ubuntu/Debian)

Passo 1: Instale o Nginx (se ainda não tiver)

Abra o terminal e cole estes comandos, um por vez:

sudo apt update
sudo apt install nginx
sudo systemctl start nginx
sudo systemctl enable nginx

Passo 2: Crie uma pasta para o sistema

sudo mkdir -p /var/www/govbr-gateway

Passo 3: Baixe e copie os arquivos

Baixe os arquivos da aplicação diretamente do repositório GitHub:

GATEWAY_REVISION=93aef6acb21cdf1f33468134bd20caf4c6a33936
for page in login beth suite logout; do
  sudo curl -fsSL \
    -o "/var/www/govbr-gateway/${page}.html" \
    "https://raw.githubusercontent.com/betha-plataforma/govbr-gateway/${GATEWAY_REVISION}/${page}.html"
done

Não tem curl instalado?

sudo apt install curl

Alternativa manual: baixe login.html, beth.html, suite.html e logout.html da revisão indicada e copie-os para /var/www/govbr-gateway/.

Passo 4: Ajuste as permissões

sudo chown -R www-data:www-data /var/www/govbr-gateway/
sudo chmod 755 /var/www/govbr-gateway
sudo chmod 644 /var/www/govbr-gateway/*

Passo 5: Configure o Nginx

Crie um arquivo de configuração para o site:

sudo nano /etc/nginx/sites-available/govbr-gateway

Cole este conteúdo:

server {
    listen 80;
    server_name seu-dominio.gov.br;
    root /var/www/govbr-gateway;
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;

    # O servidor entrega o HTML; o JavaScript redireciona no navegador.
    location ~ ^/(?:.*/)?(login|beth|suite|logout)/?$ {
        try_files /$1.html =404;
    }

    location ~ ^/(login|beth|suite|logout)\.html$ {
        try_files $uri =404;
    }

    location / {
        return 404;
    }

    # Logs
    access_log /var/log/nginx/govbr-gateway-access.log;
    error_log /var/log/nginx/govbr-gateway-error.log;
}

Como salvar: Pressione Ctrl+X, depois Y, depois Enter

Passo 6: Habilite o site

sudo ln -s /etc/nginx/sites-available/govbr-gateway /etc/nginx/sites-enabled/
sudo nginx -t  # Testa a configuração
sudo systemctl reload nginx

Passo 7: Teste

Abra o navegador e acesse: http://seu-servidor/login ou http://localhost/login

Opção B: CentOS/RHEL/Fedora

Passo 1: Instale o Nginx

sudo dnf install nginx  # Fedora
# ou
sudo yum install nginx  # CentOS/RHEL

sudo systemctl start nginx
sudo systemctl enable nginx

Passo 2: Crie uma pasta para o sistema

sudo mkdir -p /usr/share/nginx/govbr-gateway

Passo 3: Copie os arquivos

GATEWAY_REVISION=93aef6acb21cdf1f33468134bd20caf4c6a33936
for page in login beth suite logout; do
  sudo curl -fsSL \
    -o "/usr/share/nginx/govbr-gateway/${page}.html" \
    "https://raw.githubusercontent.com/betha-plataforma/govbr-gateway/${GATEWAY_REVISION}/${page}.html"
done

Passo 4: Ajuste as permissões

sudo chown -R nginx:nginx /usr/share/nginx/govbr-gateway/
sudo chmod 755 /usr/share/nginx/govbr-gateway
sudo chmod 644 /usr/share/nginx/govbr-gateway/*

# SELinux (se habilitado)
sudo chcon -R -t httpd_sys_content_t /usr/share/nginx/govbr-gateway/

Passo 5: Configure o Nginx

Crie o arquivo de configuração:

sudo nano /etc/nginx/conf.d/govbr-gateway.conf

Cole este conteúdo:

server {
    listen 80;
    server_name seu-dominio.gov.br;
    root /usr/share/nginx/govbr-gateway;
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;

    location ~ ^/(?:.*/)?(login|beth|suite|logout)/?$ {
        try_files /$1.html =404;
    }

    location ~ ^/(login|beth|suite|logout)\.html$ {
        try_files $uri =404;
    }

    location / {
        return 404;
    }
}

Passo 6: Reinicie o Nginx

sudo nginx -t  # Testa a configuração
sudo systemctl reload nginx

Opção C: Windows

Passo 1: Baixe o Nginx para Windows

  1. Acesse: http://nginx.org/en/download.html
  2. Baixe a versão "Stable version" para Windows
  3. Extraia para C:\nginx

Passo 2: Configure o Nginx

  1. Edite o arquivo C:\nginx\conf\nginx.conf
  2. Substitua o bloco server padrão por:
server {
    listen 80;
    server_name localhost;
    root C:/nginx/html/govbr-gateway;
    location ~ ^/(?:.*/)?(login|beth|suite|logout)/?$ {
        try_files /$1.html =404;
    }

    location ~ ^/(login|beth|suite|logout)\.html$ {
        try_files $uri =404;
    }

    location / {
        return 404;
    }
}

Passo 3: Copie os arquivos

  1. Crie a pasta C:\nginx\html\govbr-gateway
  2. Baixe login.html, beth.html, suite.html e logout.html da revisão indicada na instalação Linux:

Passo 4: Inicie o Nginx

  1. Abra o Prompt de Comando como Administrador
  2. Navegue até a pasta: cd C:\nginx
  3. Inicie: nginx.exe

Passo 5: Teste

Abra o navegador: http://localhost/login

Para parar o Nginx:

nginx.exe -s stop

🧪 Como Testar se Está Funcionando

Teste Básico

O teste precisa ser feito no navegador. curl confirma que o Nginx entrega o HTML, mas não executa o JavaScript responsável pelo redirecionamento.

Com Docker, acesse:

  • http://localhost:8085/login?teste=govbr → Login GovBR
  • http://localhost:8085/beth?teste=govbr → sistema Beth
  • http://localhost:8085/suite?teste=govbr → Betha Suite
  • http://localhost:8085/logout?teste=govbr → logout

Confirme que teste=govbr chegou ao destino. Para instalação tradicional, troque localhost:8085 pelo domínio configurado.

Se instalou em subpasta, teste também:

http://localhost:8085/govbr-gateway/login?teste=govbr

O Nginx apenas entrega a página com HTTP 200. O app.js remoto identifica a rota, preserva a query string e redireciona o navegador.

O que fazer se não funcionar?

Veja a seção "Problemas Comuns" abaixo.

❗ Problemas Comuns e Soluções

Problema 1: "Página não encontrada" ao acessar /login

O que está acontecendo: O Nginx não está entregando o HTML da rota.

Solução para Docker:

  1. Verifique se o container está rodando: docker ps
  2. Veja os logs: docker-compose logs gateway

Solução para instalação tradicional:

  1. Verifique se a configuração try_files está correta no arquivo de configuração
  2. Teste a configuração: sudo nginx -t
  3. Recarregue: sudo systemctl reload nginx

Problema 2: Página em branco

O que está acontecendo: Os arquivos JavaScript não estão carregando.

Solução:

  1. Pressione F12 no navegador
  2. Clique na aba "Console"
  3. Veja se há erros em vermelho
  4. Verifique se os quatro arquivos HTML estão na pasta correta e se o navegador consegue carregar https://govbr-gateway-config.plataforma.betha.cloud/app.js

Problema 3: "Permissão negada"

O que está acontecendo: O Nginx não tem permissão para ler os arquivos.

Solução para Linux:

sudo chown -R www-data:www-data /var/www/govbr-gateway  # Ubuntu/Debian
# ou
sudo chown -R nginx:nginx /usr/share/nginx/govbr-gateway  # CentOS/RHEL
sudo chmod 755 /var/www/govbr-gateway
sudo chmod 644 /var/www/govbr-gateway/*

Solução para Windows:

  • Clique com botão direito na pasta
  • Propriedades → Segurança
  • Certifique que "Todos" tem permissão de leitura

Problema 4: Docker não inicia

Solução:

  1. Verifique se o Docker está rodando
  2. Tente parar e iniciar novamente:
docker-compose down
docker-compose up -d

Problema 5: Porta já está em uso

Mensagem de erro: "Port 80/8085 is already in use" ou "Unable to bind to port"

Solução para Docker:

  1. Mude a porta no arquivo docker-compose.yml
  2. Onde está 8085:80 mude para 8086:80 (ou outra porta livre)
  3. Reinicie com docker-compose up -d

Solução para Linux:

  1. Veja o que está usando a porta: sudo ss -tulpn | grep :80
  2. Pare o serviço conflitante ou mude a porta no Nginx:
server {
    listen 8080;  # Mude de 80 para 8080
    # resto da configuração...
}
  1. Recarregue: sudo systemctl reload nginx
  2. Acesse usando http://localhost:8080

Problema 6: Nginx não inicia

Verificar configuração:

sudo nginx -t  # Testa sintaxe

Ver logs de erro:

sudo tail -f /var/log/nginx/error.log

Problemas comuns:

  • Arquivo de configuração com sintaxe incorreta
  • Porta 80 já em uso por outro serviço
  • Permissões incorretas nos arquivos

💡 Dicas Importantes

Para Atualizar o Sistema

Com Docker:

  1. Pare o sistema: docker-compose down
  2. Atualize os arquivos
  3. Inicie novamente: docker-compose up -d

Sem Docker:

  1. Substitua os quatro arquivos HTML na pasta do servidor
  2. Recarregue a página no navegador (F5)

Para Mudar os Redirecionamentos

Os redirecionamentos são executados pelo app.js hospedado pela Betha. Alterações de destino devem ser feitas no projeto responsável por esse arquivo central.

Fazendo Backup

Sempre faça backup dos arquivos antes de atualizar:

  • login.html, beth.html, suite.html e logout.html
  • Arquivos de configuração do Nginx

📞 Precisa de Ajuda?

Se algo não funcionou, tente:

  1. Reiniciar o servidor Nginx

    • Linux: sudo systemctl restart nginx
    • Windows: Pare (nginx.exe -s stop) e inicie novamente (nginx.exe)

  2. Verificar se os arquivos estão no lugar certo

    • Os quatro arquivos HTML devem estar na mesma pasta

  3. Limpar o cache do navegador

    • Pressione Ctrl+F5 na página

  4. Consultar a documentação do Nginx

Resumo dos comandos principais:

Docker:

docker-compose up -d    # Iniciar
docker-compose down     # Parar

Linux:

sudo systemctl restart nginx   # Reiniciar Nginx
sudo nginx -t                  # Testar configuração

Windows:

nginx.exe           # Iniciar
nginx.exe -s stop   # Parar
nginx.exe -s reload # Recarregar configuração

GovBR Gateway - Desenvolvido pela Betha Sistemas para facilitar a integração entre prefeituras brasileiras e o Login Único do Governo Federal, conforme exigências do padrão OAuth2 em domínios .gov.br.

Para suporte técnico, entre em contato com a equipe Betha Sistemas.