From b64cb8e1335d94fbed6e9c6930ab975335f1504c Mon Sep 17 00:00:00 2001 From: bigtux Date: Thu, 5 Feb 2026 22:12:58 -0300 Subject: [PATCH] docs: Add installation and configuration manual --- docs/INSTALL.md | 436 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 436 insertions(+) create mode 100644 docs/INSTALL.md diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..e1e0aee --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,436 @@ +# 🐍 OPHION - Manual de Instalação e Configuração + +## Índice +1. [Instalação do Servidor](#instalação-do-servidor) +2. [Instalação do Agent](#instalação-do-agent) +3. [Monitoramento de Docker](#monitoramento-de-docker) +4. [Monitoramento de Aplicações](#monitoramento-de-aplicações) +5. [Configuração de Alertas](#configuração-de-alertas) + +--- + +## 1. Instalação do Servidor + +### Requisitos Mínimos +- CPU: 2 cores +- RAM: 4GB (8GB recomendado) +- Disco: 50GB SSD +- OS: Ubuntu 22.04+ / Debian 12+ +- Docker 24+ + +### Instalação Rápida (1 comando) + +```bash +curl -fsSL https://ophion.com.br/install.sh | bash +``` + +### Instalação Manual + +```bash +# Clonar repositório +git clone https://github.com/bigtux/ophion.git +cd ophion/deploy/docker + +# Configurar variáveis de ambiente +cp .env.example .env +nano .env # Editar conforme necessário + +# Iniciar serviços +docker compose up -d + +# Verificar status +docker compose ps +``` + +### Variáveis de Ambiente (.env) + +```env +# Segurança (OBRIGATÓRIO - gere valores únicos!) +JWT_SECRET=sua-chave-secreta-aqui-min-32-chars + +# Banco de Dados +POSTGRES_USER=ophion +POSTGRES_PASSWORD=senha-forte-aqui +POSTGRES_DB=ophion + +# ClickHouse (métricas/logs) +CLICKHOUSE_USER=default +CLICKHOUSE_PASSWORD=senha-clickhouse + +# Redis +REDIS_PASSWORD=senha-redis + +# Configurações do Servidor +OPHION_PORT=8080 +OPHION_HOST=0.0.0.0 + +# Retenção de dados (dias) +METRICS_RETENTION_DAYS=30 +LOGS_RETENTION_DAYS=14 +``` + +### Verificar Instalação + +```bash +# Health check +curl http://localhost:8080/health + +# Resposta esperada: +# {"status":"healthy","service":"ophion","version":"0.1.0"} +``` + +### Acessar Dashboard + +Abra no navegador: `http://seu-servidor:3000` + +1. Crie sua conta de administrador +2. Configure sua organização +3. Gere API Keys para os agents + +--- + +## 2. Instalação do Agent + +O Agent coleta métricas do servidor e envia para o OPHION. + +### Instalação Rápida + +```bash +# Substitua YOUR_API_KEY pela chave gerada no dashboard +curl -fsSL https://ophion.com.br/agent.sh | OPHION_API_KEY=YOUR_API_KEY bash +``` + +### Instalação Manual + +```bash +# Baixar binário +wget https://github.com/bigtux/ophion/releases/latest/download/ophion-agent-linux-amd64 +chmod +x ophion-agent-linux-amd64 +sudo mv ophion-agent-linux-amd64 /usr/local/bin/ophion-agent + +# Criar arquivo de configuração +sudo mkdir -p /etc/ophion +sudo tee /etc/ophion/agent.yaml << EOF +server: https://api.ophion.com.br +api_key: YOUR_API_KEY +hostname: $(hostname) +interval: 30s + +collectors: + cpu: true + memory: true + disk: true + network: true + processes: true +EOF + +# Criar serviço systemd +sudo tee /etc/systemd/system/ophion-agent.service << EOF +[Unit] +Description=OPHION Monitoring Agent +After=network.target + +[Service] +Type=simple +ExecStart=/usr/local/bin/ophion-agent --config /etc/ophion/agent.yaml +Restart=always +RestartSec=10 + +[Install] +WantedBy=multi-user.target +EOF + +# Iniciar serviço +sudo systemctl daemon-reload +sudo systemctl enable ophion-agent +sudo systemctl start ophion-agent + +# Verificar status +sudo systemctl status ophion-agent +``` + +### Variáveis de Ambiente do Agent + +```bash +export OPHION_SERVER="https://api.ophion.com.br" +export OPHION_API_KEY="ophion_xxxxxxxxxxxxxxxx" +export OPHION_HOSTNAME="meu-servidor" +export OPHION_INTERVAL="30s" +``` + +--- + +## 3. Monitoramento de Docker + +### Opção A: Agent com Acesso ao Docker Socket + +```bash +# Adicionar ao agent.yaml +collectors: + docker: + enabled: true + socket: /var/run/docker.sock + collect_container_stats: true + collect_container_logs: true +``` + +### Opção B: Container Dedicado + +```yaml +# docker-compose.yml do seu projeto +services: + ophion-agent: + image: ophion/agent:latest + container_name: ophion-agent + restart: unless-stopped + environment: + - OPHION_SERVER=https://api.ophion.com.br + - OPHION_API_KEY=YOUR_API_KEY + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + - /proc:/host/proc:ro + - /sys:/host/sys:ro + network_mode: host + pid: host +``` + +### Métricas Coletadas do Docker + +| Métrica | Descrição | +|---------|-----------| +| `container.cpu.usage` | Uso de CPU por container | +| `container.memory.usage` | Uso de memória | +| `container.memory.limit` | Limite de memória | +| `container.network.rx_bytes` | Bytes recebidos | +| `container.network.tx_bytes` | Bytes enviados | +| `container.disk.read_bytes` | Leitura de disco | +| `container.disk.write_bytes` | Escrita de disco | +| `container.status` | Status (running/stopped) | +| `container.restarts` | Contagem de restarts | + +### Labels para Identificação + +Adicione labels aos seus containers para melhor organização: + +```yaml +services: + minha-app: + labels: + ophion.monitor: "true" + ophion.service: "api" + ophion.environment: "production" + ophion.team: "backend" +``` + +--- + +## 4. Monitoramento de Aplicações (APM) + +### Node.js + +```bash +npm install @ophion/apm +``` + +```javascript +// No início do seu app (antes de outros imports) +const ophion = require('@ophion/apm'); + +ophion.init({ + serverUrl: 'https://api.ophion.com.br', + apiKey: 'YOUR_API_KEY', + serviceName: 'minha-api', + environment: 'production' +}); + +// Seu código normal... +const express = require('express'); +const app = express(); +``` + +### Python + +```bash +pip install ophion-apm +``` + +```python +# No início do seu app +import ophion_apm + +ophion_apm.init( + server_url='https://api.ophion.com.br', + api_key='YOUR_API_KEY', + service_name='minha-api', + environment='production' +) + +# Seu código normal... +from flask import Flask +app = Flask(__name__) +``` + +### Go + +```go +import "github.com/bigtux/ophion/sdk/go/apm" + +func main() { + // Inicializar APM + apm.Init(apm.Config{ + ServerURL: "https://api.ophion.com.br", + APIKey: "YOUR_API_KEY", + ServiceName: "minha-api", + Environment: "production", + }) + defer apm.Close() + + // Seu código normal... +} +``` + +### Java (Spring Boot) + +```xml + + + com.ophion + ophion-apm + 1.0.0 + +``` + +```yaml +# application.yml +ophion: + apm: + server-url: https://api.ophion.com.br + api-key: YOUR_API_KEY + service-name: minha-api + environment: production +``` + +### OpenTelemetry (Universal) + +OPHION é compatível com OpenTelemetry. Use qualquer SDK OTel: + +```bash +# Variáveis de ambiente +export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.ophion.com.br/v1/traces" +export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_API_KEY" +export OTEL_SERVICE_NAME="minha-api" +``` + +--- + +## 5. Configuração de Alertas + +### Via Dashboard + +1. Acesse **Alertas** → **Novo Alerta** +2. Defina a condição: + - Métrica: `cpu.usage` + - Operador: `>` + - Valor: `80` + - Duração: `5 minutos` +3. Configure notificações: + - Telegram + - Slack + - Email + - Webhook + +### Via API + +```bash +curl -X POST "https://api.ophion.com.br/api/v1/alerts" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "CPU Alta", + "description": "Alerta quando CPU > 80%", + "condition": { + "metric": "cpu.usage", + "operator": ">", + "threshold": 80, + "duration": "5m" + }, + "notifications": [ + { + "type": "telegram", + "chat_id": "123456789" + }, + { + "type": "email", + "to": "admin@empresa.com" + } + ], + "severity": "warning" + }' +``` + +### Integrações Disponíveis + +| Canal | Configuração | +|-------|-------------| +| **Telegram** | Bot token + Chat ID | +| **Slack** | Webhook URL | +| **Discord** | Webhook URL | +| **Email** | SMTP ou API (SendGrid, Resend) | +| **PagerDuty** | Integration Key | +| **Webhook** | URL customizada | + +### Configurar Telegram + +1. Crie um bot com [@BotFather](https://t.me/BotFather) +2. Obtenha o token do bot +3. Inicie conversa com o bot +4. No dashboard OPHION: **Configurações** → **Integrações** → **Telegram** +5. Cole o token e configure + +--- + +## Troubleshooting + +### Agent não conecta + +```bash +# Verificar conectividade +curl -v https://api.ophion.com.br/health + +# Verificar logs do agent +journalctl -u ophion-agent -f + +# Testar API key +curl -H "Authorization: Bearer YOUR_API_KEY" \ + https://api.ophion.com.br/api/v1/status +``` + +### Métricas não aparecem + +1. Verifique se o agent está rodando: `systemctl status ophion-agent` +2. Verifique a API key no dashboard +3. Confira o hostname no dashboard +4. Aguarde até 60 segundos para primeira coleta + +### Docker metrics não coletam + +```bash +# Verificar permissões do socket +ls -la /var/run/docker.sock + +# Agent precisa estar no grupo docker +sudo usermod -aG docker ophion-agent +``` + +--- + +## Suporte + +- 📧 Email: suporte@ophion.com.br +- 💬 Telegram: [@ophion_suporte](https://t.me/ophion_suporte) +- 📖 Docs: https://docs.ophion.com.br +- 🐙 GitHub: https://github.com/bigtux/ophion + +--- + +*Made with 🖤 in Brazil*