# Decision: Capa de gestion de incidentes y comunicacion (punto 5)

## Contexto

El equipo gestiona incidencias via Zammad (ticketing) y comunicacion directa (telefono, email). Las alertas de infraestructura se envian a Telegram. No hay herramienta de comunicacion interna del equipo ni gestion formal de guardias. La documentacion operativa esta dispersa en ficheros, cabezas, y CLAUDE.md por servidor.

2 subcapas:
- 5.1 Ticketing, alertas y comunicacion
- 5.2 Documentacion operativa

---

## 5.1 Ticketing, alertas y comunicacion

### Lo que ya existe

| Herramienta | Estado | Funcion |
|-------------|--------|---------|
| **Zammad** | En produccion | Ticketing de soporte, gestion de incidencias de clientes |
| **Telegram** | En uso | Canal de alertas criticas (personal) |
| **Email** | En uso | Alertas informativas, comunicacion con clientes |
| **Telefono** | En uso | Escalado urgente ("atiende este ticket") |

### Opciones evaluadas (futuro)

| Herramienta | Que hace | Recursos | Estado |
|-------------|----------|----------|--------|
| **Mattermost** | Chat de equipo con canales tematicos + webhooks | 512 MB RAM | **Futuro** (mes 3+) |
| **Grafana OnCall** | Gestion de ciclo de vida de alertas (asignar, resolver, escalar, guardias) | Integrado en Grafana | **Futuro** (mes 3+) |
| **PagerDuty/Opsgenie** | Escalado alertas SaaS | SaaS | Descartado (coste, dependencia) |

### DECISION 5.1 (confirmada)

#### Dia 1: Zammad + Telegram (lo que ya funciona)

- **Zammad** sigue como centro de ticketing
- **Telegram** sigue como canal de alertas criticas
- **Email** para alertas informativas

Integraciones nuevas con el stack:

| Integracion | Que aporta | Prioridad |
|-------------|-----------|-----------|
| **Zammad SSO Authentik** | Misma cuenta para todo (SAML/OIDC nativo) | Semana 1 |
| **Alertmanager → Telegram** | Alertas de infraestructura al movil | Semana 1 |
| **Wazuh → Telegram** | Alertas de seguridad al movil | Semana 1 |
| **Alertmanager → Zammad** | Alerta critica no atendida en 15min → crea ticket automaticamente | Mes 2 |
| **Wazuh → Zammad** | Incidente seguridad → ticket prioridad critica | Mes 2 |
| **Panel diagnostico → Zammad** | Cliente adjunta informe al abrir ticket | Mes 3+ |
| **Netbox → Zammad** | Tecnico ve contexto del cliente en el ticket | Mes 3+ |

#### Futuro (mes 3-6): Mattermost

Chat interno del equipo como **panel de notificaciones centralizado**:

| Canal | Que recibe |
|-------|-----------|
| #alertas-criticas | Alertmanager → webhook (solo critical/warning) |
| #seguridad | Wazuh → webhook (FIM, rootkits, anomalias) |
| #backups | Semaphore → webhook (GC/verify fallidos) |
| #infra-general | Deploys, mantenimientos, cambios |
| #tickets | Zammad → webhook (tickets nuevos/escalados) |

Valor: historial buscable, contexto compartido, incorporacion de tecnicos nuevos.

No es para chatear entre el equipo (para eso ya hay canales). Es donde el stack vuelca sus eventos y el equipo tiene visibilidad compartida.

SSO con Authentik (OIDC nativo). Contenedor Docker, 512 MB RAM.

**Cuando desplegar**: cuando el stack base este rodando y el equipo tenga soltura. No antes del mes 3.

#### Futuro (mes 6+): Grafana OnCall

Gestion de ciclo de vida de alertas con rotacion de guardias:

- Alertas activas visibles, resueltas desaparecen
- Asignacion: "yo la miro"
- Escalado automatico: si nadie responde en X min → siguiente tecnico
- Rotacion de guardias (on-call schedule)
- Integrado en Grafana (mismo panel)
- Notifica por Telegram/Mattermost/SMS/llamada

**Cuando desplegar**: cuando el equipo crezca y haya guardias formales. No antes del mes 6.

```
Flujo futuro completo:
Alertmanager detecta problema
    │
    ├──► Grafana OnCall (gestionar: asignar, resolver, escalar)
    ├──► Mattermost #alertas (ver: contexto compartido)
    └──► Telegram (backup: al movil del que esta de guardia)
```

---

## 5.2 Documentacion operativa

### El problema

- Documentacion dispersa: CLAUDE.md por servidor, ficheros sueltos, conocimiento en cabezas
- Si un tecnico se va, se va su conocimiento
- Si llega un tecnico nuevo, no tiene donde aprender
- Los runbooks (que hacer cuando X pasa) no existen formalmente
- A 100+ servidores, "preguntale a David" no escala

### Opciones evaluadas

| Herramienta | Tipo | Editor | SSO | Recursos | Estado |
|-------------|------|--------|-----|----------|--------|
| **Outline** | Wiki moderna (tipo Notion) | Markdown visual, tiempo real | OIDC nativo | ~1 GB RAM | **ELEGIDA** |
| **Bookstack** | Wiki clasica | WYSIWYG + markdown | OIDC/SAML | 512 MB | Descartada (menos moderna) |
| **MkDocs + Git** | Docs como codigo | Ficheros .md en Forgejo | No aplica | 0 | Complementario (docs tecnicas con codigo) |
| **Confluence** | Wiki empresarial | WYSIWYG | SAML | SaaS/pesado | Descartada (SaaS/coste) |

### DECISION 5.2 (confirmada)

#### Outline para conocimiento operativo

Wiki moderna self-hosted. Interfaz tipo Notion, edicion colaborativa en tiempo real, busqueda full-text, permisos por coleccion.

Estructura propuesta:

```
📁 Runbooks
  ├── Servidor nuevo: checklist completo
  ├── Cliente nuevo PBS: paso a paso
  ├── Incidente de seguridad: protocolo
  ├── Disco lleno: procedimiento
  ├── Restore de backup: guia
  ├── Failover WG Hub: pasos
  └── Rotar credenciales: procedimiento

📁 Arquitectura
  ├── Stack completo (diagramas)
  ├── Redes WG (topologia IPv6)
  ├── DNS (esquema PowerDNS + Technitium)
  ├── Decisiones tecnicas (resumen de estos documentos)
  └── Mapa de servicios y VMs

📁 Onboarding
  ├── Primer dia del tecnico
  ├── Accesos (SSH bastion, WG, paneles)
  ├── Herramientas del stack
  ├── Como usar Semaphore
  └── Contactos y escalado

📁 Clientes (acceso restringido)
  ├── ACME: infra, contactos, particularidades
  ├── BETA: infra, contactos
  └── Plantilla cliente nuevo
```

Permisos:
- Tecnicos: leen y editan todo
- Comerciales: solo ven Clientes + Onboarding
- Clientes: no acceden (su info esta en Zammad + panel diagnostico)

SSO con Authentik desde el dia 1.

#### Forgejo para documentacion tecnica con codigo

Los docs que van pegados al codigo siguen en Forgejo (README.md, comentarios en playbooks, configs documentadas). No duplicar en Outline.

| Tipo de documentacion | Donde |
|-----------------------|-------|
| Runbooks, procedimientos, onboarding | **Outline** |
| Playbooks Ansible, configs, scripts | **Forgejo** (en el repo) |
| Diagramas de arquitectura | **Outline** |
| Decisiones tecnicas (estos documentos) | **Outline** (migrar cuando este listo) |
| API docs, integraciones | **Forgejo** (con el codigo) |

#### Recursos

| Componente | RAM |
|-----------|-----|
| Outline app | ~512 MB |
| PostgreSQL (puede compartir con otros) | ~256 MB |
| Redis (puede compartir con otros) | ~64 MB |
| **Total** | ~800 MB - 1 GB |

Contenedor Docker en VM Servicios.

#### Prioridades despliegue documentacion

| Prioridad | Que | Esfuerzo |
|-----------|-----|----------|
| **Semana 2** | Desplegar Outline con SSO Authentik | 2h |
| **Semana 2** | Crear estructura de colecciones (vacia) | 1h |
| **Mes 1** | Escribir runbooks criticos (servidor nuevo, incidente seguridad, restore) | 1 dia |
| **Mes 1** | Migrar decisiones tecnicas (estos docs) a Outline | 2h |
| **Mes 2** | Documentar onboarding de tecnicos | 4h |
| **Mes 2** | Documentar particularidades por cliente | Progresivo |

---

## Resumen Capa 5 completa (DECISIONES FINALES)

```
┌─────────────────────────────────────────────────────┐
│        CAPA 5: GESTION DE INCIDENTES                 │
├─────────────────────────────────────────────────────┤
│                                                      │
│  5.1 TICKETING Y ALERTAS (confirmada)                │
│  ┌───────────────────────────────────┐               │
│  │  Zammad (ya en produccion)        │               │
│  │  - Ticketing soporte              │               │
│  │  - SSO Authentik                  │               │
│  │  - Integracion Alertmanager/Wazuh │               │
│  │                                    │               │
│  │  Telegram (alertas criticas)      │               │
│  │  - Alertmanager → bot             │               │
│  │  - Wazuh → bot                    │               │
│  │                                    │               │
│  │  Futuro (mes 3+):                 │               │
│  │  - Mattermost (notificaciones     │               │
│  │    centralizadas del equipo)      │               │
│  │  Futuro (mes 6+):                 │               │
│  │  - Grafana OnCall (guardias,      │               │
│  │    escalado, ciclo de vida)       │               │
│  └───────────────────────────────────┘               │
│                                                      │
│  5.2 DOCUMENTACION (confirmada)                      │
│  ┌───────────────────────────────────┐               │
│  │  Outline (wiki tipo Notion)       │               │
│  │  - Runbooks, arquitectura,        │               │
│  │    onboarding, clientes           │               │
│  │  - Edicion colaborativa real-time │               │
│  │  - SSO Authentik                  │               │
│  │  - Permisos por coleccion        │               │
│  │                                    │               │
│  │  Forgejo (docs con codigo)        │               │
│  │  - README, configs, playbooks     │               │
│  │  - Versionado con git             │               │
│  └───────────────────────────────────┘               │
│                                                      │
└─────────────────────────────────────────────────────┘

Recursos Capa 5:
- Zammad: ya existente
- Outline: ~1 GB RAM (contenedor Docker en VM Servicios)
- Mattermost (futuro): 512 MB RAM
- Grafana OnCall (futuro): integrado en Grafana, 0 extra
```