09 ago. 2026 3 min read News

Dominando n8n en Docker: Configuración mediante Variables de Entorno

1. Qué es n8n y cómo funciona

n8n es una plataforma de automatización de flujos de trabajo (workflow automation) de código abierto (fair-code) y basada en nodos. A diferencia de soluciones comerciales y cerradas, n8n te permite alojar el motor de ejecución en tu propia infraestructura, garantizando la soberanía de los datos y eliminando los costos escalonados por ejecución.

Su arquitectura funciona mediante un sistema de "Triggers" (disparadores) y "Actions" (acciones). Un flujo puede iniciar por un evento externo, como un Webhook entrante desde un sistema de monitoreo o una petición de un panel de control, y ejecutar secuencias lógicas de transformación de datos, interactuando nativamente con cientos de APIs de terceros.

2. Enlaces Oficiales y Recursos

Para auditar la seguridad y mantener la infraestructura operativa, utiliza siempre las fuentes oficiales del proyecto:

Sitio Principal: n8n.io
Documentación Técnica: docs.n8n.io
Repositorio GitHub: github.com/n8n-io/n8n
Docker Hub: docker.n8n.io/n8nio/n8n

3. Requisitos Previos

Para garantizar un entorno estable y escalable, las instalaciones directas tipo bare-metal deben evitarse. Se requiere:

Un servidor Linux (Kubuntu, Ubuntu, Debian o un contenedor LXC).
Docker Engine y Docker Compose instalados y actualizados.
Mínimo 1 GB de RAM (se recomiendan 2 GB para flujos con alta carga de datos).
Un proxy inverso para la gestión de certificados SSL/HTTPS.

4. El Motor de n8n: Variables de Entorno

Configurar n8n a través de variables de entorno es obligatorio para mantener la inmutabilidad de la infraestructura y aislar la configuración del código. Omitirlas provocará fallos de enrutamiento y corrupción de datos a largo plazo:

GENERIC_TIMEZONE: Define la zona horaria del motor. Es crítico para que los nodos de tipo Cron se ejecuten en la hora local correcta y no en UTC.
WEBHOOK_URL: Esencial cuando el servicio opera detrás de un proxy inverso. Define la URL pública exacta. Si se omite, el sistema generará webhooks apuntando a redes internas.
N8N_ENCRYPTION_KEY: n8n encripta las credenciales (API keys, contraseñas) en la base de datos. Si no defines una clave estática y el contenedor se recrea, perderás permanentemente el acceso a esas credenciales.
DB_TYPE y variables de base de datos: Desactivan SQLite y obligan a n8n a utilizar PostgreSQL, evitando bloqueos de escritura en operaciones concurrentes.

5. Paso a Paso para el Despliegue

El siguiente procedimiento respeta el orden estricto de directorios, permisos y orquestación para evitar el clásico error EACCES: permission denied originado por los bind mounts de Docker en Linux.

5.1 Preparación del Entorno

Primero, crea la estructura de directorios y ajusta los permisos. El contenedor de n8n ejecuta sus procesos internos bajo el usuario node (UID 1000). Si la carpeta local no le pertenece, el despliegue fallará instantáneamente.

# Crear directorio principal del proyecto
mkdir -p ~/n8n-server
cd ~/n8n-server

# Crear carpeta para datos persistentes y asignar permisos al UID 1000
mkdir n8n_data
sudo chown -R 1000:1000 n8n_data

5.2 Archivos de Configuración

Dentro del directorio ~/n8n-server, crea un archivo Dockerfile. Esto permite inyectar paquetes adicionales a la imagen oficial a nivel de sistema operativo, útiles para diagnóstico de red dentro de los flujos.

# Archivo: Dockerfile
FROM docker.n8n.io/n8nio/n8n:latest

USER root
RUN apk add --no-cache iputils curl python3
USER node

A continuación, crea el archivo docker-compose.yml. Este bloque despliega simultáneamente n8n y una instancia de PostgreSQL, vinculándolos de forma segura.

# Archivo: docker-compose.yml
version: "3.8"

services:
  postgres:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_USER=n8n_user
      - POSTGRES_PASSWORD=tu_password_fuerte
      - POSTGRES_DB=n8n
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -h localhost -U n8n_user -d n8n']
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n_user
      - DB_POSTGRESDB_PASSWORD=tu_password_fuerte
      - N8N_ENCRYPTION_KEY=reemplaza_con_una_cadena_larga_y_segura
      - N8N_HOST=0.0.0.0
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - NODE_ENV=production
      - WEBHOOK_URL=https://n8n.tudominio.com/
      - GENERIC_TIMEZONE=America/La_Paz
      - EXECUTIONS_DATA_SAVE_ON_ERROR=all
      - EXECUTIONS_DATA_SAVE_ON_SUCCESS=none
    volumes:
      - ./n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  db_data:

5.3 Ejecución y Verificación

Con los directorios y archivos listos, compila la imagen y levanta los servicios en segundo plano.

docker compose up --build -d

Revisa los logs para confirmar que el sistema conectó con la base de datos y generó las claves iniciales de forma exitosa:

docker compose logs -f n8n

6. Mantenimiento y Comandos Útiles

La administración del ciclo de vida de los contenedores se debe ejecutar siempre desde el directorio base ~/n8n-server.

Actualización del entorno:

docker compose pull
docker compose build --no-cache
docker compose up -d

Exportación manual de flujos (Backup JSON):

docker compose exec n8n n8n export:workflow --all --output=/home/node/.n8n/backup_flujos.json

Limpieza profunda de recursos no utilizados:

docker system prune -a --volumes -f