Instalación de n8n con Docker: Guía Completa

En esta guía explicaremos cómo instalar n8n utilizando Docker, la forma recomendada para la mayoría de casos de uso. Docker proporciona un entorno aislado y limpio, evita incompatibilidades entre sistemas operativos y herramientas, y facilita la gestión de bases de datos y variables de entorno.

¿Qué es n8n?

n8n es una herramienta de automatización de flujos de trabajo que te permite conectar diferentes servicios y aplicaciones sin necesidad de escribir código. Es similar a Zapier o Make (anteriormente Integromat), pero con la ventaja de que puedes auto-hospedarlo y tener control total sobre tus datos y flujos.

Requisitos Previos

Antes de comenzar, necesitas tener instalado Docker en tu sistema:

Instalación de Docker

Docker Desktop está disponible para Mac, Windows y Linux. Docker Desktop incluye el motor Docker y Docker Compose.

Para Linux, también puedes instalar Docker Engine y Docker Compose por separado si prefieres no usar Docker Desktop.

# Verificar instalación de Docker
docker --version
docker compose version

⚠️ Nota de Seguridad: Auto-hospedar n8n requiere conocimientos técnicos, incluyendo configuración de servidores y contenedores, gestión de recursos, seguridad de aplicaciones y configuración de n8n. n8n recomienda auto-hospedar solo para usuarios expertos. Los errores pueden llevar a pérdida de datos, problemas de seguridad y tiempo de inactividad.

Instalación Básica de n8n con Docker

Para iniciar n8n con Docker, ejecuta los siguientes comandos desde tu terminal, reemplazando <YOUR_TIMEZONE> con tu zona horaria (por ejemplo: America/Lima, America/Mexico_City, Europe/Madrid):

# Crear un volumen para almacenar datos persistentes
docker volume create n8n_data

# Iniciar n8n con Docker
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="<YOUR_TIMEZONE>" \
  -e TZ="<YOUR_TIMEZONE>" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Este comando realiza lo siguiente:

Crea un volumen para almacenar datos persistentes
Descarga la imagen de n8n si no está disponible
Inicia el contenedor con las siguientes configuraciones:
- Mapea y expone el puerto 5678 en el host
- Configura la zona horaria del contenedor:
  - TZ establece la zona horaria del sistema para controlar lo que scripts y comandos como date retornan
  - GENERIC_TIMEZONE establece la zona horaria correcta para nodos orientados a horarios como el Schedule Trigger
- Habilita permisos seguros de archivos para el archivo de configuración de n8n
- Habilita task runners, la forma recomendada de ejecutar tareas en n8n
- Monta el volumen n8n_data al directorio /home/node/.n8n para persistir tus datos entre reinicios del contenedor

Una vez que esté en ejecución, puedes acceder a n8n abriendo: http://localhost:5678

💡 Versiones disponibles: n8n lanza una nueva versión menor casi todas las semanas. La versión stable es para producción. La versión beta es la más reciente pero puede ser inestable.

Configuración con PostgreSQL

Por defecto, n8n usa SQLite para guardar credenciales, ejecuciones pasadas y flujos de trabajo. n8n también soporta PostgreSQL, configurable usando variables de entorno.

⚠️ Importante: Aunque estés usando PostgreSQL, todavía se recomienda mapear un volumen persistente para el directorio .n8n, ya que contiene otros datos importantes como claves de cifrado, logs de la instancia y assets de la función de control de versiones.

Para usar n8n con PostgreSQL, ejecuta los siguientes comandos, reemplazando los placeholders (por ejemplo, <POSTGRES_USER>) con tus valores reales:

docker volume create n8n_data

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="<YOUR_TIMEZONE>" \
  -e TZ="<YOUR_TIMEZONE>" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -e DB_TYPE=postgresdb \
  -e DB_POSTGRESDB_DATABASE=<POSTGRES_DATABASE> \
  -e DB_POSTGRESDB_HOST=<POSTGRES_HOST> \
  -e DB_POSTGRESDB_PORT=<POSTGRES_PORT> \
  -e DB_POSTGRESDB_USER=<POSTGRES_USER> \
  -e DB_POSTGRESDB_SCHEMA=<POSTGRES_SCHEMA> \
  -e DB_POSTGRESDB_PASSWORD=<POSTGRES_PASSWORD> \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Ejemplo de docker-compose con PostgreSQL

Puedes encontrar un archivo docker-compose.yml completo con PostgreSQL en el repositorio de hosting de n8n.

Variables de Entorno Importantes

Para una configuración en producción, hay varias variables de entorno que debes considerar configurar:

Configuración de Dominio y Subdominio

# El dominio de nivel superior desde donde se servirá n8n
DOMAIN_NAME=tu-dominio.com

# El subdominio desde donde se servirá n8n
SUBDOMAIN=n8n

# Esto servirá n8n en: https://n8n.tu-dominio.com

Las variables DOMAIN_NAME y SUBDOMAIN juntas determinan desde dónde será accesible n8n.

Configuración de Zona Horaria

# Zona horaria usada por Cron y nodos de programación
GENERIC_TIMEZONE=America/Lima

# Zona horaria del sistema
TZ=America/Lima

La variable GENERIC_TIMEZONE es especialmente importante para nodos como Schedule Trigger que dependen de la zona horaria correcta para funcionar apropiadamente.

Configuración de SSL/TLS

# Dirección de correo electrónico para certificado TLS/SSL (Let's Encrypt)
SSL_EMAIL=administrador@tu-dominio.com

Esta variable es necesaria si planeas usar Let’s Encrypt para certificados SSL automáticos.

Variables de Seguridad

# Clave de cifrado para datos sensibles (genera una clave aleatoria segura)
N8N_ENCRYPTION_KEY=tu-clave-de-cifrado-muy-larga-y-segura

# Habilitar cookies seguras para HTTPS
N8N_SECURE_COOKIE=true

🔒 Importante: La variable N8N_ENCRYPTION_KEY debe ser una cadena larga y aleatoria. Úsala para cifrar credenciales y datos sensibles. Nunca compartas esta clave ni la expongas en repositorios públicos.

Configuración de Protocolo y URLs Base

# Protocolo usado (http o https)
N8N_PROTOCOL=https

# URL base de la API de Vue
VUE_APP_URL_BASE_API=https://n8n.tu-dominio.com

# URL para webhooks
WEBHOOK_URL=https://n8n.tu-dominio.com

Estas variables aseguran que n8n genere las URLs correctas para webhooks y la interfaz de usuario, especialmente importante cuando estás detrás de un proxy inverso o usando HTTPS.

Ejemplo de Configuración Completa

Aquí tienes un ejemplo de cómo se verían todas las variables juntas en un archivo .env o en tu comando docker run:

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e DOMAIN_NAME=tu-dominio.com \
  -e SUBDOMAIN=n8n \
  -e GENERIC_TIMEZONE=America/Lima \
  -e TZ=America/Lima \
  -e SSL_EMAIL=administrador@tu-dominio.com \
  -e N8N_ENCRYPTION_KEY=tu-clave-segura \
  -e N8N_SECURE_COOKIE=true \
  -e N8N_PROTOCOL=https \
  -e VUE_APP_URL_BASE_API=https://n8n.tu-dominio.com \
  -e WEBHOOK_URL=https://n8n.tu-dominio.com \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Actualización de n8n

Para actualizar n8n, primero necesitas descargar la imagen más reciente:

# Descargar la última versión estable
docker pull docker.n8n.io/n8nio/n8n

# Descargar una versión específica
docker pull docker.n8n.io/n8nio/n8n:1.81.0

# Descargar la versión beta (inestable)
docker pull docker.n8n.io/n8nio/n8n:next

Después de descargar la imagen actualizada, detén tu contenedor de n8n y reinícialo. También puedes usar la línea de comandos:

# Encontrar el ID de tu contenedor
docker ps -a

# Detener el contenedor
docker stop <container_id>

# Eliminar el contenedor
docker rm <container_id>

# Iniciar el contenedor con la nueva imagen
docker run --name=n8n [opciones] -d docker.n8n.io/n8nio/n8n

Actualización con Docker Compose

Si ejecutas n8n usando un archivo Docker Compose, sigue estos pasos:

# Navegar al directorio que contiene tu archivo docker compose
cd /ruta/a/tu/archivo/compose

# Descargar la última versión
docker compose pull

# Detener y eliminar la versión anterior
docker compose down

# Iniciar el contenedor
docker compose up -d

Uso con Tunnel (Desarrollo)

⚠️ Peligro: Usa esto solo para desarrollo y pruebas locales. No es seguro usarlo en producción.

Para usar webhooks con nodos de activación de servicios externos como GitHub, n8n debe ser accesible desde internet. n8n ejecuta un servicio de túnel que puede redirigir solicitudes desde los servidores de n8n a tu instancia local de n8n.

Para iniciar n8n con --tunnel, ejecuta:

docker volume create n8n_data

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="<YOUR_TIMEZONE>" \
  -e TZ="<YOUR_TIMEZONE>" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n \
  start --tunnel

Esto creará una URL temporal a través del túnel de n8n que puedes usar para recibir webhooks durante el desarrollo.

Ejecución en Segundo Plano (Detached)

Para ejecutar n8n en segundo plano y liberar tu terminal, agrega la bandera -d al comando docker run:

docker run -d --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="<YOUR_TIMEZONE>" \
  -e TZ="<YOUR_TIMEZONE>" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Para ver los logs del contenedor:

docker logs n8n

# Seguir los logs en tiempo real
docker logs -f n8n

Próximos Pasos

Una vez que tengas n8n funcionando, aquí hay algunos recursos útiles:

Documentación oficial de n8n: Explora la documentación completa en docs.n8n.io
Configuración y escalado: Aprende más sobre configurar y escalar n8n en producción
Quickstarts: Explora los tutoriales rápidos para comenzar a crear workflows
README del Docker: Encuentra más información sobre la configuración del Docker en el README del repositorio de la imagen Docker
Docker Compose: Revisa configuraciones de Docker Compose para diferentes arquitecturas en el repositorio de hosting de n8n