Acesso à Documentação (Docusaurus)

A documentação técnica da BITIO é hospedada em Docusaurus e está acessível apenas via VPN para manter a segurança dos conteúdos internos.

🔗 Informações de Acesso

Atributo	Valor
URL	`https://engenharia-docs.bitio.com.br`
Acesso	Apenas via VPN
Engine	Docusaurus (React)
Hospedagem	Container no Servidor Pritunl

📋 Pré-requisitos

✅ VPN configurada e conectada
✅ Arquivo /etc/hosts configurado
✅ Navegador web moderno

⚙️ Configuração Inicial

1. Configurar /etc/hosts (Obrigatório)

Linux/Ubuntu/macOS:

echo "172.31.11.156 engenharia-docs.bitio.com.br" | sudo tee -a /etc/hosts

Windows (como Administrador):

echo 172.31.11.156 engenharia-docs.bitio.com.br >> C:\Windows\System32\drivers\etc\hosts

2. Verificar Configuração

# Testar resolução DNS
nslookup engenharia-docs.bitio.com.br
# Deve retornar: 172.31.11.156

# Sem VPN (deve falhar)
curl -I https://engenharia-docs.bitio.com.br/
# Erro: Connection refused ✅

# Com VPN (deve funcionar)
curl -I https://engenharia-docs.bitio.com.br/
# HTTP/2 200 ✅

🔐 HTTPS e SSL

Status Atual

Componente	SSL Status	Certificado
VPN Admin	✅ Let's Encrypt	Válido até 2026-10-01
Git Forgejo	✅ Let's Encrypt	Válido até 2026-10-01
Documentação	✅ Auto-assinado temporário	Substituir por Let's Encrypt

Configurar Certificado Let's Encrypt

Quando o DNS estiver propagado (pode demorar até 24h):

# Verificar propagação DNS
nslookup engenharia-docs.bitio.com.br 8.8.8.8

# Configurar certificado válido
./scripts/setup-docs-ssl.sh

Acesso Atual

Com certificado auto-assinado: Navegador mostra aviso de segurança (normal)
Aceitar certificado e prosseguir - funciona perfeitamente
Após Let's Encrypt: Certificado será totalmente válido

🌐 Acesso via Navegador

Conectar VPN
Acessar: https://engenharia-docs.bitio.com.br
Aceitar certificado (se auto-assinado temporário)
Navegar pela documentação completa da infraestrutura

Interface da Documentação

A documentação inclui:

✅ Visão Geral - Arquitetura completa
✅ Configuração VPN - Setup Pritunl + OpenVPN
✅ Acesso Git - Forgejo via VPN
✅ PostgreSQL - Conexão ao banco
✅ Backup e Monitoramento - Estratégias de backup
✅ Guias de Desenvolvimento - Workflows e boas práticas

🔧 Arquitetura da Documentação

Hospedagem

graph TB
    Internet[🌐 Internet] --> VPN[🔐 VPN<br/>50.19.198.178]
    VPN --> Nginx[📡 Nginx Proxy<br/>172.31.11.156:443]
    Nginx --> Docker[🐳 Container Docusaurus<br/>localhost:3001]
    Docker --> Files[📚 Build Docusaurus<br/>/opt/bitio/docs]

    Dev[👨‍💻 Desenvolvedor] --> VPNC[VPN Conectada<br/>10.250.0.x]
    VPNC --> Nginx

    classDef private fill:#ffcccc
    classDef public fill:#ccffcc
    classDef vpn fill:#ccccff

    class Nginx,Docker,Files private
    class VPN public
    class VPNC vpn

Stack Tecnológico

Componente	Tecnologia	Função
Frontend	Docusaurus + React	Interface da documentação
Web Server	Nginx Alpine	Servir arquivos estáticos
Proxy	Nginx (host)	SSL termination + proxy reverso
Container	Docker	Isolamento da aplicação
SSL	Let's Encrypt	Certificados SSL/TLS

📝 Processo de Atualização da Documentação

Deploy Automático

# 1. Fazer alterações nos arquivos .md
cd /home/two-biz/projeto/BITIO/apps/docs

# 2. Executar build local
npm run build

# 3. Deploy para servidor
./scripts/deploy-docs.sh

# 4. Verificar no navegador
# https://engenharia-docs.bitio.com.br

Build Manual

# Build local do Docusaurus
cd apps/docs
npm install  # primeira vez apenas
npm run build

# Verificar build
ls -la build/

Deploy Manual

# Upload manual dos arquivos
rsync -avz --delete \
  apps/docs/build/ \
  ubuntu@50.19.198.178:/opt/bitio/docs/

# Restart do container (se necessário)
ssh ubuntu@50.19.198.178 "docker restart bitio-docusaurus"

🔍 Solução de Problemas

Documentação não carrega

# Verificar VPN
ip addr show tun0

# Verificar hosts
grep "engenharia-docs" /etc/hosts

# Testar conectividade
curl -I https://engenharia-docs.bitio.com.br/

Erro 403 Forbidden

# Verificar container
ssh ubuntu@50.19.198.178 "docker ps -f name=bitio-docusaurus"

# Verificar logs
ssh ubuntu@50.19.198.178 "docker logs bitio-docusaurus --tail 20"

# Reiniciar container se necessário
ssh ubuntu@50.19.198.178 "docker restart bitio-docusaurus"

Conteúdo desatualizado

# Verificar última atualização
ssh ubuntu@50.19.198.178 "ls -la /opt/bitio/docs/"

# Re-deploy forçado
./scripts/deploy-docs.sh

SSL Certificate Error

# Verificar certificado
ssh ubuntu@50.19.198.178 "sudo certbot certificates"

# Renovar se necessário
ssh ubuntu@50.19.198.178 "sudo certbot renew"

🛠️ Administração

Status dos Serviços

# Container Docusaurus
ssh ubuntu@50.19.198.178 "docker ps -f name=bitio-docusaurus"

# Nginx proxy
ssh ubuntu@50.19.198.178 "sudo systemctl status nginx"

# Uso de espaço
ssh ubuntu@50.19.198.178 "du -sh /opt/bitio/docs"

Logs e Monitoramento

# Logs do container
ssh ubuntu@50.19.198.178 "docker logs bitio-docusaurus"

# Logs do Nginx (acesso)
ssh ubuntu@50.19.198.178 "sudo tail -f /var/log/nginx/access.log | grep docs"

# Logs do Nginx (erro)
ssh ubuntu@50.19.198.178 "sudo tail -f /var/log/nginx/error.log"

Backup da Documentação

# Backup dos arquivos fonte (já versionados no Git)
git add apps/docs/
git commit -m "docs: atualizar documentação"
git push

# Backup do build (opcional)
rsync -avz ubuntu@50.19.198.178:/opt/bitio/docs/ ./backup-docs-$(date +%Y%m%d)/

🚀 Recursos Disponíveis

Funcionalidades

✅ Busca - Pesquisa full-text na documentação
✅ Navegação - Sidebar hierárquica e breadcrumbs
✅ Mobile - Interface responsiva
✅ Dark Mode - Tema claro/escuro
✅ Links - Cross-references entre guias
✅ Syntax Highlighting - Código com destaque
✅ Mermaid - Diagramas de arquitetura

Performance

✅ Cache - Assets com cache de 1 ano
✅ Compression - Gzip habilitado
✅ CDN-like - Arquivos estáticos otimizados
✅ SPA - Single Page Application (navegação rápida)

📊 Configuração Técnica

Container Configuration

# /opt/bitio/docker-compose.docs.yml
version: "3.8"
services:
  docusaurus:
    image: nginx:alpine
    container_name: bitio-docusaurus
    restart: unless-stopped
    volumes:
      - /opt/bitio/docs:/usr/share/nginx/html:ro
      - /opt/bitio/configs/nginx-docs.conf:/etc/nginx/conf.d/default.conf:ro
    ports:
      - "3001:80"

Nginx Configuration

# /etc/nginx/sites-available/bitio (fragmento)
server {
    listen 443 ssl http2;
    server_name engenharia-docs.bitio.com.br;

    # Proxy para Docusaurus
    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Produtividade

Mantenha a documentação sempre atualizada. Use o script deploy-docs.sh para deployments rápidos após alterações.

Segurança

A documentação contém informações internas sensíveis. Nunca desabilite a restrição de VPN ou torne-a pública na internet.

🔗 Informações de Acesso​

📋 Pré-requisitos​

⚙️ Configuração Inicial​

1. Configurar /etc/hosts (Obrigatório)​

2. Verificar Configuração​

🔐 HTTPS e SSL​

Status Atual​

Configurar Certificado Let's Encrypt​

Acesso Atual​

🌐 Acesso via Navegador​

Interface da Documentação​

🔧 Arquitetura da Documentação​

Hospedagem​

Stack Tecnológico​

📝 Processo de Atualização da Documentação​

Deploy Automático​

Build Manual​

Deploy Manual​

🔍 Solução de Problemas​

Documentação não carrega​

Erro 403 Forbidden​

Conteúdo desatualizado​

SSL Certificate Error​

🛠️ Administração​

Status dos Serviços​

Logs e Monitoramento​

Backup da Documentação​

🚀 Recursos Disponíveis​

Funcionalidades​

Performance​

📊 Configuração Técnica​

Container Configuration​

Nginx Configuration​