Una instancia de n8n auto-alojada es un editor de flujo de trabajo en el puerto 5678, un volumen para su base de datos y un inicio de sesión que creas al abrir por primera vez. Este laboratorio inicia ese contenedor, construye Webhook a HTTP Request a If a Slack o correo electrónico, lo prueba con curl, lo publica, luego cuelga un IA Agente y una herramienta del mismo editor.
Ejecuta n8n con Docker
La página de instalación de Docker de n8n aún imprime un docker run, y también dice que esa página está desactualizada a favor de Docker Compose. El comando a continuación es el que esa página aún documenta. A partir de octubre de 2026, esa página enumeraba comportamiento de imagen estable en 2.44.7 y beta en 2.45.4, y dijo que un nuevo minor se envía la mayoría de semanas. Fija una etiqueta de los lanzamientos de n8n cuando te importe qué compilación obtienes. n8nio/n8n sin etiqueta sigue estable.
Crea el volumen primero. Sin él, un nuevo contenedor tiene una base de datos vacía y una nueva clave de cifrado.
docker volume create n8n_data
Genera una clave y pásala en el primer inicio. n8n escribe una clave aleatoria en ~/.n8n si lo omites. Solo obtienes la oportunidad de elegir la clave antes de que ese archivo exista.
openssl rand -hex 32
docker run -it --rm \
--name n8n \
-p 5678:5678 \
-e GENERIC_TIMEZONE="America/New_York" \
-e TZ="America/New_York" \
-e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
-e N8N_ENCRYPTION_KEY="paste-the-hex-here" \
-v n8n_data:/home/node/.n8n \
n8nio/n8n
TZ es el reloj del contenedor. GENERIC_TIMEZONE es lo que usan los nodos de estilo horario. N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true es la configuración que la página de instalación establece para que el archivo de configuración no se quede legible por el mundo. --rm elimina el contenedor cuando se cierra. El volumen con nombre permanece. Abre http://localhost:5678.
Para un proceso que debería sobrevivir a la terminal, suelta --rm e -it, y agrega -d, que es cómo los mismos docs reinician un contenedor después de una extracción de imagen. Los comandos cotidianos docker run, docker ps y volumen están en la chuleta de CLI de Docker.
El almacenamiento predeterminado es SQLite dentro de ese volumen. Postgres es opcional: establece DB_TYPE=postgresdb más las variables DB_POSTGRESDB_* de la página de instalación. Mantén el volumen de todos modos. Con Postgres, la carpeta aún contiene la clave de cifrado, los logs y los activos de control de código fuente.
Actualiza con un pull, luego recrea el contenedor contra el mismo volumen:
docker pull n8nio/n8n
docker stop n8n
docker rm n8n
Comienza de nuevo con el mismo -v, la misma N8N_ENCRYPTION_KEY y -d.
compose.yaml
Este archivo usa la misma imagen, puerto, ruta de volumen y variables de entorno que la instalación de Docker. No es la pila de sandbox de la guía completa de Compose de n8n. La forma del archivo Compose y docker compose up están en la chuleta de Docker Compose.
Coloca la clave en un archivo .env junto al archivo compose, y no commits ese archivo.
services:
n8n:
image: n8nio/n8n
restart: always
ports:
- "127.0.0.1:5678:5678"
environment:
GENERIC_TIMEZONE: America/New_York
TZ: America/New_York
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
volumes:
- n8n_data:/home/node/.n8n
volumes:
n8n_data:
docker compose up -d
docker compose ps
Vinculación 127.0.0.1 coincide con el ejemplo de Compose en la nube: el editor es local hasta que un proxy lo publica. Actualiza una instalación de Compose con docker compose pull, docker compose down, luego docker compose up -d. down no elimina un volumen con nombre a menos que pases una bandera que elimine volúmenes. No pases esa bandera.
Cuenta de propietario, no autenticación básica
n8n 1.0 eliminó la autenticación básica y JWT externo. No hay un interruptor compatible que oculte la pantalla de inicio de sesión. Al abrir por primera vez, el formulario de registro crea el propietario. La contraseña debe tener al menos ocho caracteres e incluir un número y una letra mayúscula.
A partir de n8n 2.17.0, puedes aprovisionar previamente ese propietario con variables de entorno. El interruptor es N8N_INSTANCE_OWNER_MANAGED_BY_ENV=true. Los otros campos de propietario viven en la página de entorno de administración de usuarios. Establécelos antes de depender de la interfaz de usuario de registro.
N8N_ENCRYPTION_KEY cifra credenciales antes de que lleguen a la base de datos. En modo de cola, cada trabajador necesita la misma variable. Si cambias la clave después de que existan credenciales, esas filas fueron cifradas con la clave anterior. Mantén una copia de la clave fuera del volumen. Una copia de seguridad de flujos de trabajo sin esta clave no puede descifrar credenciales. Los comandos de copia de seguridad de CLI también omiten la clave. Copia el volumen, o mantén la variable env, así como n8n export:workflow.
Proxy inverso
n8n construye URLs de webhook a partir de N8N_PROTOCOL, N8N_HOST y N8N_PORT. Detrás de un proxy, el proceso aún escucha en 5678, mientras que los navegadores usan 443. Establece el origen público tú mismo.
N8N_WEBHOOK_URL reemplaza WEBHOOK_URL. El nombre anterior está deprecado a partir de n8n 2.35.0 y registra una advertencia. Establece N8N_PROXY_HOPS=1 cuando hay un proxy. El último proxy en la ruta debe enviar X-Forwarded-For, X-Forwarded-Host y X-Forwarded-Proto.
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
Los docs también dicen que combinar N8N_PATH con un proxy inverso rompe la navegación de carpetas. Prefiere un subdominio como n8n.example.com.
Construye el primer flujo de trabajo
flowchart LR
W[Webhook] --> H[HTTP Request]
H --> I[If]
I -->|true| S[Slack]
I -->|false| E[Send Email]
Crea un flujo de trabajo. Agrega un nodo Webhook. Establece HTTP Method en POST. Establece Respond to When Last Node Finishes para que curl imprima la salida del último nodo en lugar del cuerpo genérico «workflow got started». Los otros modos de respuesta son Immediately, Using ‘Respond to Webhook’ Node y Streaming response.
El nodo muestra dos URLs. Test es para el editor. Production se registra cuando publicas. Los prefijos de ruta predeterminados son webhook-test y webhook. Puedes cambiar esos con N8N_ENDPOINT_WEBHOOK_TEST y N8N_ENDPOINT_WEBHOOK. Los docs de Webhook limitan el cuerpo a 16 MB. En tu propio servidor, N8N_PAYLOAD_SIZE_MAX aumenta ese límite.
Agrega un nodo HTTP Request. Llama a cualquier API REST, y los docs del nodo también dicen que puedes pegar un comando curl para rellenar los parámetros. Apúntalo a una URL de salud que controlas que devuelve JSON con un campo status. El método GET es suficiente para la primera prueba.
Agrega un nodo If. Los docs deletrean el nodo If. Elige String, la comparación es equal to, y compara el status del JSON de salud con ok. Las condiciones adicionales se combinan con AND u OR. Más de dos salidas significa un nodo Switch, no una pila de nodos If. Las comparaciones de String incluyen contains, starts with y matches regex. La salida false es la rama que usas cuando la verificación falla.
En la salida true, agrega un nodo Slack. Resource Message, operación Send. Esa operación llama a chat.postMessage de Slack. Necesitas una credencial de Slack. La página del nodo de Slack lista el método por operación e indica que tomes scopes de la página de credenciales de Slack. No adivines cadenas de scope.
En la salida false, agrega un nodo Send Email. Envía a través de SMTP. Operación Send. Rellena From Email, To Email, Subject y Email Format: Text, HTML o Both. El mismo nodo puede ser una herramienta de IA después. No puede establecer In-Reply-To o References. Las respuestas encadenadas necesitan la operación reply del nodo de Gmail, que la página de Send Email nombra como la solución alternativa.
Guarda el flujo de trabajo.
Prueba con curl, luego publica
Haz clic en Listen for test event en el nodo Webhook. La página de problemas comunes dice que la URL de prueba escucha durante 120 segundos y muestra la carga en el editor. Copia la URL de prueba desde el nodo. Se parece a esto, con tu ruta:
curl -X POST http://localhost:5678/webhook-test/health-check \
-H "Content-Type: application/json" \
-d "{\"service\":\"checkout\"}"
Si nada llega, esperaste demasiado tiempo o el flujo de trabajo no estaba escuchando. Haz clic en Listen for test event de nuevo. Una URL de producción devuelve nada útil hasta que publiques. Publicar es el control actual. Escritos más antiguos dicen «activar». Los docs de ejecuciones dicen que publiques una versión, y despublicas para detener el tráfico de producción.
Después de Publish, llama a la URL de producción. El editor no muestra esa ejecución en vivo. Abre la pestaña Executions. Las ejecuciones manuales desde el editor no cuentan hacia la cuota de ejecución de un plan pagado. Un webhook publicado sí: una ejecución por solicitud que realmente inicia el flujo de trabajo, incluyendo un cuerpo de {}. Las solicitudes mal formadas que fallan antes de que el flujo de trabajo comience no cuentan. Cómo se compara esa cuota con créditos de Make y tareas de Zapier está en n8n vs Make vs Zapier.
Agrega un IA Agente, un modelo de chat y una herramienta
El nodo IA Agente es un nodo raíz. Conectas un modelo de chat y al menos una herramienta. El agente decide qué herramienta llamar. Los docs requieren una herramienta. Un modelo solo no es una configuración válida.
A partir de n8n 1.82.0, el menú desplegable de tipo de agente anterior está deprecado. Cada nodo IA Agente se comporta como un Tools Agent. El nodo v1 que aún muestra el menú desplegable está programado para desaparecer en n8n 3.0. Actualiza el nodo en lugar de elegir un tipo heredado. Para un agente de estilo de base de datos, la página de IA Agente dice que uses una herramienta Postgres o MySQL en un nodo Agent actual.
La página de Tools Agent lista estos modelos de chat:
- OpenAI Chat Model
- Groq Chat Model
- Mistral Cloud Chat Model
- Anthropic Chat Model
- Microsoft Foundry Chat Model
Conecta uno de esos a la entrada del modelo y crea la credencial de ese proveedor. En la entrada de herramienta, Calculator es suficiente para probar el bucle, porque no necesita una cuenta. HTTP Request y Slack también son herramientas en esa lista, así que la misma cuenta de Slack puede ser una herramienta en lugar de una rama fija.
Establece la fuente de prompt en Define below y escribe el mensaje del usuario, u elige Take from previous node automatically, que espera un campo de entrada llamado chatInput. Las opciones que vale la pena conocer: System Message y Max Iterations, que predetermina a 10. Enable Streaming está activado de forma predeterminada y solo transmite cuando el modo de respuesta del desencadenante es Streaming, por ejemplo un Webhook o el Chat Trigger.
Un Chat Trigger más un sub-nodo de memoria puede mantener una conversación entre turnos. La página de Tools Agent dice que la memoria no persiste entre sesiones.
Lo que «tool calling» significa fuera de n8n se cubre en qué es IA agentiva. Los docs de IA Agente de n8n también apuntan a conectar un servidor MCP como herramienta. Cómo se forman esos servidores está en servidores MCP explicados.
Exporta e importa
Los flujos de trabajo son JSON. En el editor, abre el menú Workflow en el encabezado del lienzo:
- Download guarda el flujo de trabajo actual.
- Import from File lee un archivo JSON desde tu computadora.
- Import from URL lee JSON desde una dirección a la que puedes llegar.
Copy and paste también funciona: selecciona nodos, Ctrl + c, Ctrl + v.
El archivo contiene nombres de credenciales e IDs. Los IDs no son el secreto. Los nombres aún pueden ser sensibles si nombras una credencial según un cliente. Los nodos HTTP Request completados desde curl aún pueden almacenar encabezados de Autorización en el JSON del nodo. Elimina esos antes de enviar el archivo a otra persona.
En el servidor, los comandos de copia de seguridad escriben un archivo por flujo de trabajo:
n8n export:workflow --backup --output=backups/workflows/
n8n export:credentials --backup --output=backups/credentials/
Dentro de Docker, esa ruta backups/ no es el volumen. Monta un directorio de host o copia los archivos. Usa un directorio diferente para credenciales. La página de copia de seguridad dice que import:credentials --separate falla si los archivos de flujo de trabajo se encuentran en la misma carpeta. --decrypted escribe secretos de credenciales en texto plano para que puedas moverlos a una instancia con una clave de cifrado diferente. Trata esos archivos como secretos.
--published exporta la versión publicada en lugar del borrador. --version exporta una versión histórica por su id de versión. No puedes combinar --version con --all.
n8n también tiene paquetes (.n8np) vía n8n-cli package. Están marcados Preview. Un paquete lleva id de credencial, nombre y tipo, nunca el secreto. La importación coincide con una credencial que ya tienes o crea un marcador de posición vacío.
Importar un flujo de trabajo JSON no importa la contraseña SMTP ni el token de Slack. Crea esas credenciales de nuevo, luego reselecciónalas en los nodos.
Fallas que realmente golpearás
404 en el webhook. Llamaste a la ruta de producción antes de Publish, o el escucha de prueba ya había agotado a los 120 segundos.
La URL en el nodo es localhost:5678 en un sitio público. Establece N8N_WEBHOOK_URL y N8N_PROXY_HOPS. Si una lista blanca de IP en el nodo Webhook rechaza clientes que deberían pasar, la página de problemas comunes indica que establezca N8N_PROXY_HOPS al número de proxies.
Las credenciales no se abrirán después de una recreación. El nuevo contenedor no tiene la clave anterior. Restaura el volumen o establece la misma N8N_ENCRYPTION_KEY que usaste en el primer lanzamiento.
Las variables de entorno de autenticación básica no hacen nada. Se eliminaron en 1.0. Usa la cuenta de propietario.
El nodo IA Agente no se ejecutará. Conecta una herramienta. La pista en la página de IA Agente es explícita.
Slack envía en el editor y nunca en producción, o al revés. Esa limitación se documenta para el Slack Trigger, que solo puede registrar una URL de webhook por aplicación de Slack. Un nodo de acción de Slack que publica un mensaje no tiene esa restricción. El caso de desencadenante se corrige despublicando, apuntando Slack a la URL de prueba, luego publicando de nuevo con la URL de producción.
Preguntas frecuentes
¿Cómo ejecuto n8n en Docker para que los datos sobrevivan a un reinicio?
Crea un volumen con nombre y móntalo en /home/node/.n8n. Ese directorio contiene la base de datos SQLite y la clave de cifrado de credenciales. Establece N8N_ENCRYPTION_KEY antes del primer inicio si quieres una clave que controles, y mantén el volumen cuando reemplaces el contenedor.
¿Por qué mi webhook de n8n devuelve 404?
La URL de prueba solo escucha durante aproximadamente 120 segundos después de que hagas clic en Listen for test event. La URL de producción se registra cuando publicas el flujo de trabajo. Detrás de un proxy inverso, establece N8N_WEBHOOK_URL en el origen https público y N8N_PROXY_HOPS en 1, o el editor muestra una URL interna.
¿Sigue N8N_BASIC_AUTH protegiendo un n8n auto-alojado?
No. La autenticación básica y el login JWT externo se eliminaron en n8n 1.0. Las versiones actuales siempre muestran una pantalla de inicio de sesión. La primera cuenta que creas es el propietario. La contraseña necesita al menos ocho caracteres, un número y una letra mayúscula.
¿Los archivos JSON de flujo de trabajo n8n exportados incluyen claves API?
Incluyen nombres de credenciales e IDs, no los valores secretos. Recreas credenciales en la instancia de destino. Un nodo HTTP Request importado desde un comando curl aún puede contener un encabezado de Autorización en el JSON del nodo, así que lee el archivo antes de compartirlo.
Cómo se verificó esta guía
Escrita a mano a partir de la documentación oficial, con cada comando comprobado de nuevo y una segunda revisión antes de publicar. Última revisión: .
Fuentes oficiales consultadas para este artículo
- docs.n8n.io/deploy/host-n8n/install-options/install-with-docker
- docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/configuration-examples/set-a-custom-encryption-key
- docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/configuration-examples/configure-webhook-urls-with-reverse-proxy
- docs.n8n.io/deploy/host-n8n/configure-n8n/user-management
- docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/use-environment-variables/user-management-and-2fa
- docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/use-environment-variables/endpoints
- docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook
- docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/common-issues
- docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest
- docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.if
- docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.slack
- docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.sendemail
- docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent
- docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/tools-agent
- docs.n8n.io/build/manage-workflows/export-and-import
- docs.n8n.io/deploy/host-n8n/configure-n8n/use-the-command-line
- docs.n8n.io/deploy/host-n8n/keep-n8n-running/backup-and-restore
- docs.n8n.io/changelog/v10-migration-guide

