ophion/docs/INSTALL.md

🐍 OPHION - Manual de Instalação e Configuração

Índice

1. Instalação do Servidor
2. Instalação do Agent
3. Monitoramento de Docker
4. Monitoramento de Aplicações
5. 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)

curl -fsSL https://ophion.com.br/install.sh | bash

Instalação Manual

# 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)

# 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

# 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

# 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

# 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

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

# 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

# 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:

services:
  minha-app:
    labels:
      ophion.monitor: "true"
      ophion.service: "api"
      ophion.environment: "production"
      ophion.team: "backend"

---

4. Monitoramento de Aplicações (APM)

Node.js

npm install @ophion/apm

// 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

pip install ophion-apm

# 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

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)

<!-- pom.xml -->
<dependency>
    <groupId>com.ophion</groupId>
    <artifactId>ophion-apm</artifactId>
    <version>1.0.0</version>
</dependency>

# 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:

# 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

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

# 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

# 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
• 📖 Docs: https://docs.ophion.com.br
• 🐙 GitHub: https://github.com/bigtux/ophion

---

Made with 🖤 in Brazil