Sistema de Automatización¶
Visión global del subsistema de automatización de 
SmallCountry: los motores, flujos y herramientas que permiten que el sistema reaccione, se repare y evolucione sin intervención humana constante.
Descripción general¶
SmallCountry usa dos orquestadores con filosofías complementarias, más un trío de herramientas de infraestructura como código. Esta decisión está documentada en el ADR-004.
El principio rector es el Principio 9 — Silencio operativo: el sistema no debe molestar a las personas. Debe resolver lo que pueda por sí mismo y solo pedir ayuda cuando sea estrictamente necesario.
Panorama de automatización¶
flowchart LR
subgraph Orquestadores["🎛️ Orquestadores"]
NodeRED["Node-RED<br/>flujos en tiempo real<br/>IoT · sensores ·MQTT"]
n8n["n8n<br/>flujos de negocio<br/>APIs · webhooks · CRON"]
end
subgraph IaC["🏗️ Infraestructura como código"]
Ansible["Ansible<br/>configuración declarativa<br/>roles · playbooks"]
OpenTofu["OpenTofu<br/>provisionamiento<br/>módulos · estado"]
Semaphore["Semaphore<br/>panel de ejecución<br/>auditoría · templates"]
end
subgraph CI_CD["🔄 CI/CD"]
Forgejo["Forgejo Actions<br/>workflows · despliegue<br/>lint · test · deploy"]
end
subgraph Destinos["🎯 Destinos"]
Servicios["Servicios<br/>despliegue · config"]
Sensores["Sensores<br/>actuadores · alarmas"]
Personas["Personas<br/>notificaciones · informes"]
Backups["Backups<br/>PBS · Restic · rsync"]
end
Orquestadores --> Destinos
IaC --> Destinos
CI_CD --> Destinos
NodeRED -->|"MQTT"| Sensores
NodeRED -->|"ntfy · Matrix"| Personas
n8n -->|"webhooks"| Servicios
Ansible -->|"SSH"| Servicios
style Orquestadores fill:#f9a8d4,stroke:#c2185b,color:#000
style IaC fill:#bbdefb,stroke:#1565c0,color:#000
style CI_CD fill:#a5d6a7,stroke:#2e7d32,color:#000
style Destinos fill:#ffe082,stroke:#f57f17,color:#000Node-RED — Automatización en tiempo real¶
Node-RED es el cerebro reactivo de SmallCountry. Escucha el bus MQTT y reacciona en milisegundos a eventos del mundo físico.
Flujos principales¶
| Flujo | Gatillo | Acción |
|---|---|---|
| Alerta de colmena | Báscula ESP32 baja >20% en 24h | Notifica a Melissa por ntfy + registra en farmOS |
| Riego automático | Humedad del suelo <30% + previsión sin lluvia | Activa Shelly de bomba de riego durante 15 min |
| Alerta de gallinero | Temperatura >35°C o <5°C | Notifica a Fauno + activa ventilador o calefactor |
| Modo tormenta | Anemómetro >60 km/h | Desconecta electrovalla, cierra persianas Shelly, avisa a todos |
| Bomba del sótano | Sensor de agua activado | Arranca bomba, notifica a Terminus con prioridad crítica |
| Heartbeat sensores | Silencio de un ESP32 >30 min | Escala: aviso → reenvío → alerta a Argos |
Protocolos¶
- MQTT (Mosquitto): bus principal de sensores y actuadores
- HTTP API: integración con Grafana, ntfy, farmOS
- Modbus TCP: comunicación con Victron Cerbo GX (Geb)
n8n — Automatización de flujos de trabajo¶
n8n es el cerebro administrativo. Orquesta procesos que involucran múltiples servicios, APIs y lógica condicional compleja.
Flujos principales¶
| Flujo | Programación | Acción |
|---|---|---|
| Onboarding de usuario | Webhook (nuevo usuario en Authentik) | Crea cuenta en Nextcloud, Immich, Matrix, Joplin. Asigna cuota. |
| Facturación mensual | Día 1 de cada mes | Genera facturas recurrentes en FacturaScripts, envía por email vía Mautic |
| Informe semanal de finca | Lunes 08:00 | Recopila datos de farmOS + Grafana. Genera PDF. Envía a grupo campo por Matrix. |
| Limpieza de backups | Diario 03:00 | Poda snapshots ZFS antiguos, rota logs, limpia versiones de Immich |
| Verificación de integridad | Semanal domingo 02:00 | Lanza zpool scrub en Ra y Horus, verifica repositorio Restic en Thoth |
| Transcripción clínica | Webhook (nuevo audio en buzón) | Toma audio → Whisper → análisis con Ollama → guarda en Joplin (cifrado E2E) |
| Sincronización Zona Cero | Diario 06:00 | Sincroniza datasets públicos de InvenioRDM hacia el servidor Zona Cero |
Ansible — Configuración declarativa¶
Cada servicio, cada LXC y cada archivo de configuración están definidos como roles de Ansible versionados en Forgejo.
| Componente | Ubicación | Propósito |
|---|---|---|
roles/authentik/ |
infra-core/ansible/roles/ |
Configuración completa de Authentik: providers, grupos, políticas |
roles/caddy/ |
infra-core/ansible/roles/ |
Caddyfile con todos los virtual hosts y forward-auth |
roles/nextcloud/ |
infra-core/ansible/roles/ |
Instalación, OIDC, Redis, cron, maintenance |
roles/common/ |
infra-core/ansible/roles/ |
Base común a todos los LXC: usuario, firewall, fail2ban, Alloy |
playbooks/deploy-all.yml |
infra-core/ansible/ |
Despliegue completo del sistema desde cero |
playbooks/update-all.yml |
infra-core/ansible/ |
Actualización controlada de todos los servicios |
OpenTofu — Infraestructura como código¶
Mientras Ansible configura lo que ya existe, OpenTofu crea la infraestructura desde cero: contenedores LXC, bridges de red, volúmenes ZFS.
| Módulo | Propósito |
|---|---|
modules/proxmox-lxc/ |
Creación de contenedores LXC con recursos asignados |
modules/proxmox-network/ |
Bridges virtuales y asignación de IPs |
modules/zfs-dataset/ |
Creación de datasets con políticas de snapshot |
modules/dns-record/ |
Registros en Pi-hole para el dominio .sc |
Semaphore — Panel de ejecución¶
Semaphore proporciona una interfaz web para ejecutar playbooks de Ansible con:
- Registro de auditoría: quién ejecutó qué playbook, cuándo y con qué resultado
- Templates: playbooks preconfigurados para tareas recurrentes (añadir servicio, rotar secretos)
- Control de acceso: solo el grupo
adminpuede ejecutar playbooks en producción - Notificaciones: cada ejecución notifica resultado por Matrix
Forgejo Actions — CI/CD¶
Cada cambio en el repositorio infra-core dispara un pipeline:
- Lint: validación de sintaxis YAML/JSON, shellcheck en scripts
- Test: ejecución de playbooks en entorno de pruebas (LXC aislado)
- Build: generación de la documentación MkDocs
- Deploy: despliegue automático en producción (solo rama
main, solo con aprobación explícita)
Para el arquitecto
División de responsabilidades Node-RED vs n8n¶
| Criterio | Node-RED | n8n |
|---|---|---|
| Latencia | Milisegundos | Segundos |
| Complejidad de flujo | Baja/Media | Alta |
| Integraciones nativas | MQTT, GPIO, Modbus | REST, GraphQL, OAuth2 |
| Interfaz | Flujo visual cableado | Nodos con formularios |
| Estado | Stateless (eventos) | Stateful (workflows) |
| Ejemplo canónico | Alerta de colmena | Facturación mensual |