NgixProxy_Pathfinder/.gemini/GEMINI.md

NGINX Pathfinder Proxy - Documentação da Estrutura

Visão Geral

Este projeto é um proxy reverso NGINX containerizado com suporte a:

• HTTP/3 (QUIC) - Protocolo moderno para melhor performance
• Brotli - Compressão avançada para menor uso de banda
• High Availability - Restart automático e cache stale
• Validação Automática - Verificação de DNS e SSL no startup

---

Estrutura de Pastas

.
├── conf.d/              # Configurações de sites (carregadas automaticamente)
├── snippets/            # Trechos reutilizáveis de configuração
├── scripts/             # Scripts auxiliares (pre-flight.sh)
├── ssl/                 # Certificados SSL/TLS
├── legacy/              # Arquivos antigos do servidor original
├── .gemini/             # Documentação do projeto
├── Dockerfile           # Build customizado do NGINX
├── docker-compose.yml   # Orquestração do container
├── nginx.conf           # Configuração principal do NGINX
└── deploy.sh            # Script de deploy automatizado

---

Arquivos Principais

Dockerfile

Constrói uma imagem NGINX customizada baseada em Alpine Linux com:

• Módulo Brotli (compressão)
• Módulo headers_more (manipulação de headers)
• Ferramentas de diagnóstico (dig, openssl, curl)

docker-compose.yml

Orquestra o container com:

• Portas: 80 (HTTP), 443 (HTTPS), 443/udp (HTTP/3)
• Volumes: conf.d, ssl, snippets, cache, logs
• Restart: always (alta disponibilidade)
• Variável: HOST_PUBLIC_IP (injetada pelo deploy.sh)

nginx.conf

Configuração principal que:

• Carrega os módulos (Brotli, headers_more)
• Inclui snippets do /etc/nginx/snippets/
• Inclui sites do /etc/nginx/conf.d/

deploy.sh

Script de deploy que:

1. Detecta o IP público do servidor
2. Grava no .env
3. Build da imagem Docker
4. Testa configuração com nginx -t
5. Inicia o container

---

Pasta snippets/

Contém configurações reutilizáveis incluídas no nginx.conf:

Arquivo	Função
rate_limit.conf	Define zonas de rate limiting
security_maps.conf	Maps para detecção de bots e IPs internos
log_formats.conf	Formato JSON detalhado para logs
cache_zones.conf	Define todas as zonas de cache
custom_errors.conf	Páginas de erro customizadas

---

Pasta conf.d/

Contém configurações individuais de cada site/sistema. Cada arquivo .conf representa um virtual host.

Padrão de nomenclatura: dominio.conf (ex: itguys.com.br.conf)

Estrutura típica de um site:

upstream nome_backend {
    server IP:PORTA;
}

server {
    listen 80;
    server_name dominio.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name dominio.com;
    
    ssl_certificate /etc/letsencrypt/live/dominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/dominio.com/privkey.pem;
    
    proxy_cache STATIC;
    proxy_cache_use_stale error timeout;
    
    location / {
        proxy_pass http://nome_backend;
    }
}

---

Pasta scripts/

pre-flight.sh

Script executado ANTES do NGINX iniciar. Valida:

• Se HOST_PUBLIC_IP está definida
• Se os domínios configurados apontam para o IP correto
• Logs de warning se houver inconsistências

---

Pasta legacy/

Contém arquivos do servidor original (synced via proxy-sinc). Não são usados diretamente - servem como referência.

---

Fluxo de Deploy

graph LR
    A[deploy.sh] --> B[Detecta IP]
    B --> C[Gera .env]
    C --> D[Docker Build]
    D --> E[nginx -t]
    E --> F[Docker Up]
    F --> G[pre-flight.sh]
    G --> H[NGINX Start]

---

Variáveis de Ambiente

Variável	Descrição
HOST_PUBLIC_IP	IP público do servidor (detectado automaticamente)

---

Comandos Úteis

# Deploy completo
./deploy.sh

# Rebuild após alterações
docker compose build && docker compose up -d

# Testar configuração
docker compose run --rm nginx-proxy nginx -t

# Ver logs
docker compose logs -f

# Recarregar configuração sem restart
docker compose exec nginx-proxy nginx -s reload

---

Notas Importantes

1. SSL: Os certificados devem estar em /etc/letsencrypt/ no host ou montados via volume
2. ModSecurity: Alguns sites usam WAF que requer módulo adicional (não incluído por padrão)
3. HTTP/2: O formato antigo listen 443 ssl http2 está deprecated, usar http2 on; separado