docs: Add installation and configuration manual
This commit is contained in:
436
docs/INSTALL.md
Normal file
436
docs/INSTALL.md
Normal file
@@ -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
|
||||
<!-- 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*
|
||||
Reference in New Issue
Block a user