# n8n

n8n en modo cola sobre Docker, con workers, task runners, PostgreSQL y Redis propios, HTTPS y actualizaciones con respaldo.

Fuente: https://ardumaker.com/docs/n8n/

- Categoría: Servidores e infraestructura
- Estado: Disponible
- Requisitos: Un VPS activo con al menos 4 GB de RAM libre real (no la nominal del plan); Docker posible en el VPS (los VPS nuevos ya traen los permisos); Ningún n8n instalado por npm en ese VPS
- Herramientas MCP (Solo leen): `ver_preflight_app`, `ver_app`, `ver_operacion_app`
- Herramientas MCP (Escriben o modifican): `instalar_app`, `controlar_app`, `reintentar_operacion_app`
- Herramientas MCP (Destructivas): `desinstalar_app`

## ¿Qué permite hacer?

ArduMaker instala n8n como un stack de Docker listo para producción: un proceso principal, workers en modo cola, un task runner por proceso, su propio PostgreSQL y su propio Redis. Es una instalación por VPS.

- Instalar sin preguntas: las credenciales internas se generan solas.
- Publicar el editor con HTTPS; la URL de webhooks y del editor se configura sola.
- Reiniciar, actualizar de versión (con copia de la base antes) y escalar workers.
- Editar variables de entorno desde el panel, con las críticas protegidas.
- Desinstalar conservando los datos, o borrándolos con confirmación.

## ¿Cuándo conviene usarlo?

- Automatizaciones y webhooks propios, sin límites de ejecuciones de un servicio alojado.
- Flujos con nodos Code que necesitan aislamiento real (task runners externos).
- Mucho volumen de ejecuciones que conviene repartir entre workers.

## ¿Cómo funciona en ArduMaker?

1. Validar: VPS activo, función `n8n` del sistema, Docker posible y RAM libre real (`MemAvailable`) de al menos 4 GB. Si ya hay un n8n (Docker o npm), se adopta tal cual, sin reinstalar ni migrar.
2. Preparar credenciales (o reutilizar las del `.env` de un intento anterior: un PostgreSQL ya inicializado no acepta otra contraseña).
3. Generar el Compose desde código según la RAM libre, bajar las imágenes como paso largo y levantar el stack.
4. Publicar el editor (puerto 5678) con HTTPS y escribir en el `.env` `WEBHOOK_URL` y `N8N_EDITOR_BASE_URL` con la dirección publicada, y `N8N_PROXY_HOPS=1`.
5. Verificar: `running` solo con el proceso principal activo, `/healthz` y `/healthz/readiness` en 200 y todos los workers activos.

Si un worker se cae a mitad, quien retoma la operación espera la misma instalación: nunca lanza un segundo stack.

## ¿Qué cambia realmente?

| Archivo o recurso | Contenido |
| --- | --- |
| `/opt/n8n/docker-compose.yml` | Compose generado por la plataforma (644 root) |
| `/opt/n8n/.env` | Variables de todos los contenedores (600 root) |
| `/opt/n8n/stack.json` | Versión, topología, límites y volúmenes (600 root) |
| `/opt/n8n/backups/` | Volcados diarios de la base con 7 días de retención (timer `n8n-db-backup`) |
| `n8n-stack.service` | Unidad que controla el stack con `docker compose` |
| Volúmenes | `n8n_data`, `n8n_pg_data`, `n8n_redis_data` |

## RAM, workers y topología

La cantidad de workers sale de la RAM libre real, no del plan. Además se reservan 896 MB fijos para PostgreSQL y Redis y 512 MB de holgura antes de conceder workers extra; el máximo es 8.

| RAM libre | Workers | Runner del principal |
| --- | --- | --- |
| Menos de 4 GB | Se rechaza | — |
| 4 – 5,9 GB | 2 | No |
| 6 – 7,9 GB | 3 | No |
| 8 GB o más | 4 o más (hasta 8) | Sí |

Cada contenedor lleva su límite de memoria y n8n recibe `--max-old-space-size` en torno al 75 % de ese límite, para que el recolector trabaje antes de que el sistema mate el proceso. Los logs rotan (10 MB, 3 archivos) y el historial de ejecuciones se poda a los 14 días.

## Variables de entorno

- Protegidas (no se editan): `N8N_ENCRYPTION_KEY`, `N8N_RUNNERS_AUTH_TOKEN`, `DB_POSTGRESDB_*`, `POSTGRES_*`, `REDIS_PASSWORD`, `QUEUE_BULL_REDIS_*`.
- Gestionadas por la plataforma: `N8N_WORKERS` (escalado), `WEBHOOK_URL` y `N8N_EDITOR_BASE_URL` (dominio), `EXECUTIONS_MODE`, `N8N_RUNNERS_MODE`, `N8N_PORT`.
- Secretas (se muestran enmascaradas): las protegidas y cualquiera que termine en `PASSWORD`, `SECRET`, `TOKEN`, `KEY` o `_PWD`. Revelarlas exige admin y queda registrado.
- Los valores no pueden tener comillas, `#`, `$`, acento grave, barra invertida ni saltos de línea: un valor así no falla, vale otra cosa.

## Actualizar, escalar y respaldar

- Actualizar baja las imágenes de n8n y de los runners (mismo tag), hace un volcado de la base, regenera el Compose y levanta; si la verificación falla, vuelve a la versión anterior.
- Subir workers no corta nada; bajarlos detiene primero los de índice alto con un tiempo de gracia para terminar las ejecuciones en curso.
- La copia semanal del VPS incluye los volúmenes, pero se toma en caliente; el volcado diario de `/opt/n8n/backups/` es la copia consistente de la base.

## Esquema

**Stack de n8n en el VPS**

```text
Internet (HTTPS en la dirección publicada)
  ↓
nginx del VPS (reparte a `127.0.0.1:5678`)
  ↓
`n8n-main` (editor y webhooks; encola ejecuciones)
  ↓
`n8n-redis` (cola de ejecuciones)
  ↓
`n8n-worker-N` (ejecuta, cada uno con su runner)
  ↓
`n8n-postgres` (base de workflows, credenciales y ejecuciones)
```

PostgreSQL y Redis del stack nunca se publican: viven en la red interna del proyecto Compose.

## Resultado esperado

La app n8n figura en Apps como una sola app (sus contenedores son componentes) con la URL HTTPS del editor cuando el enlace está verificado.

```bash
docker compose -p n8n ps
docker logs n8n-main --tail 50
```

## Errores y resolución

| Error o síntoma | Causa y qué hacer |
| --- | --- |
| `recursos_insuficientes` | Menos de 4 GB de RAM libre real. Liberar memoria o subir de plan. |
| `requiere_reinicio_vps` | VPS viejo sin permisos de Docker: hay que reiniciarlo. |
| `n8n_npm_instalado` | Hay un n8n por npm: no se instala Docker encima. |
| `app_ya_existe` / `limite_de_tipo` | Ya hay un n8n en ese VPS (o una instalación en curso). |
| `n8n_instalandose` / `n8n_instalacion_fallida` | Sigue instalándose o terminó con error. Reintentable: relanza con las credenciales del `.env`. |
| `n8n_webhook_no_configurado` | Quedó publicado pero el `.env` no tomó la URL. Reintentable, sin reinstalar. |
| Ejecuciones con nodo Code encoladas para siempre | Un runner no encontró su worker o tiene otra versión de imagen. |
| Se cambió una variable y no pasó nada | `compose restart` no relee el `.env`: hay que reiniciar recreando los contenedores. |

> **PRECAUCION:** Las migraciones de esquema de n8n son irreversibles. Si una actualización falla la verificación, se vuelve a la imagen anterior, pero la base no se revierte: para eso está el volcado previo.

## Relación con MCP

n8n se instala y opera por MCP con las herramientas de Apps ([/mcp/docs](https://ardumaker.com/mcp/docs), [/mcp/servicios](https://ardumaker.com/mcp/servicios)).

- Lectura: `ver_preflight_app` (con `app_type: n8n` dice si entra por RAM y Docker), `ver_app`, `ver_operacion_app`.
- Modifican: `instalar_app` con `app_type: n8n` y `config` opcional `workers` (1–8), `concurrency` (1–50) y `version`; `controlar_app` con `restart` o `update`; `reintentar_operacion_app`.
- Destructiva: `desinstalar_app` (solo admin). Conserva volúmenes salvo `delete_data=true` con `confirm_delete_data=true`, que borra la base de n8n.

Cualquier otro campo en `config` (usuarios, contraseñas) responde `config_invalida`. Las variables de entorno y el escalado se manejan desde el panel; las acciones solo existen para el runtime Docker (un n8n por npm responde `runtime_no_soportado`).

## Funciones relacionadas

- [Docker](https://ardumaker.com/docs/docker/)
- [Servidores VPS](https://ardumaker.com/docs/vps/)
- [PostgreSQL](https://ardumaker.com/docs/postgresql/)
- [Redis](https://ardumaker.com/docs/redis/)
- [Copias de seguridad](https://ardumaker.com/docs/backups/)
- [Certificados SSL](https://ardumaker.com/docs/ssl/)