ophion/docs/INSTALL.md

# 🐍 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
<!-- pom.xml -->
<dependency>
    <groupId>com.ophion</groupId>
    <artifactId>ophion-apm</artifactId>
    <version>1.0.0</version>
</dependency>
```

```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*