Saudações.

Esse tutorial é um guia rápido de instalação do N8N versão 2 modo fila com taskrunners.

Arquivos do guia:

• https://github.com/patrickbrandao/n8n-builder/
• https://github.com/patrickbrandao/n8n-builder/tree/main/n8n-deploy

Pré-requisitos (constam em outros artigos aqui do blog):

• Instalação do Linux (Debian);
• Internet no servidor (sua VPS ou host);
• Docker CE instalado;
• Traefik como proxy reverso;

1 – Sobre N8N versão 2

O N8N (eni eiti eni) é um sistema de construção de automações no-code e low-code usando fluxos visuais, ligando visualmente componentes uns aos outros para criar programas.

A versão 2 implementou algumas mudanças, entre elas, a mais drástica foi a separação da execução de códigos Python e Javascript em containers separados de sandbox que ele nomeou como taskrunners.

Diagrama de relação entre serviços (containers) na versão 2:

Com isso a estrutura de containers ficou assim:

• editor (main): Roda o núcleo do N8N, gestão completa e disparo de eventos (triggers);
• webhook: Roda o servidor web (HTTP) para disparo de eventos baseados na chamada de URLs e Webhooks (webhook trigger, form trigger);
• worker: Detecta o disparo de eventos e inicia a execução do workflow node a node, é o serviço que faz o trabalho pesado, todos os nodes do tipo code de Javascript e Python são enviados para execução no taskrunner;
• taskrunner: Se conecta ao worker para receber trabalhos de execução de códigos Javascript e Python, retorna os dados gerados e informações da execução;
• redis: Provê o canal de comunicação pub-sub entre todos os serviços acima e serve de cache de dados;
• postgresql: Provê o banco de dados persistente para cadastro de tudo (logins, credenciais, workflows, logs de execução, etc).

O serviço de webhook é opcional mas altamente recomendado para separar a carga de entrada das webhooks do editor, assim o editor fica com recursos reservados à administração do N8N enquanto que o webhook pode escalar por meio de réplicas.

Os containers dos 6 serviços tem diferentes naturezas de escalonamento:

• editor (main): Por padrão não escala, não replicável, pode escalar por meio de licença especial que permite o ambiente multi-main que balanceia a carga HTTP das ações administrativas. Devido ao fato do main rodar o núcleo duro do N8N que dispara quase todos os tipos de triggers das automações, ao rodar várias instâncias do editor uma delas será eleita a principal (master) para assumir a tarefa de disparo de triggers enquanto as demais atual apenas como balanceamento de carga das chamadas ao backend vindas do frontend;
• webhook: Replicável, o balanceamento de conexões de entrada é feito pelo Swarm e em casos mais avançados por cluster de proxy reverso;
• worker: Replicável, o balanceamento da carga é feita internamente entre os workers que disputam serviços na mensageria do redis;
• taskrunner: Replicável, o taskrunner requer o endereço do worker a qual ele se conectará e portanto o balanceamento é feito pelo Swarm;
• redis: Não replicável, todos os containers do N8N precisam se comunicar por ele, para escalar o redis é necessário montar um cluster redis;
• postgres: Não replicável, semelhante ao redis, requer cluster postgres separado;

2 – Preparativos

Nesse capítulo vou executar o N8N parte por parte para ambiente de estudos das partes isoladamente.

2.1 – Configurações

Personalize a variável EMAIL para que o LetsEncrypt funcione corretamente. Vou salvar o email de contato no arquivo /etc/email do host:

# Email de registro no letsencrypt
EMAIL="voce@seudominio.com.br";

# Gravar no arquivo para consulta
echo "$EMAIL" > /etc/email;

# Email de registro no letsencrypt
EMAIL="voce@seudominio.com.br";

# Gravar no arquivo para consulta
echo "$EMAIL" > /etc/email;

2.2 – Rede Docker

Rede Docker para containers do N8N.
Arquivo: /root/n8n-deploy/run-01-network-public.sh

# Rede Docker (bridge local)
docker network create \
    -d bridge \
    \
    -o "com.docker.network.bridge.name"="br-net-public" \
    -o "com.docker.network.bridge.enable_icc"="true" \
    -o "com.docker.network.driver.mtu"="1500" \
    \
    --subnet 10.249.0.0/16 --gateway 10.249.255.254 \
    \
    network_public;

# Rede Docker (bridge local)
docker network create \
    -d bridge \
    \
    -o "com.docker.network.bridge.name"="br-net-public" \
    -o "com.docker.network.bridge.enable_icc"="true" \
    -o "com.docker.network.driver.mtu"="1500" \
    \
    --subnet 10.249.0.0/16 --gateway 10.249.255.254 \
    \
    network_public;

2.3 – Proxy Reverso – Traefik

Container do Traefik para proxy reverso com HTTPs automático.
Arquivo: /root/n8n-deploy/run-02-traefic-app.sh

# Email de contato para o certificado LetsEncrypt:
    EMAIL="voce@seudominio.com.br";
    [ -f /etc/email ] && EMAIL=$(head -1 /etc/email);

# Imagem do traefik, baixar atualizada:
    docker pull traefik:latest;

# Diretorio de dados persistentes:
    mkdir -p /storage/traefik-app/letsencrypt;
    mkdir -p /storage/traefik-app/logs;
    mkdir -p /storage/traefik-app/config;

# Renovar/rodar:
  docker rm -f traefik-app 2>/dev/null;
  docker run \
    -d --restart=always \
    --name traefik-app -h traefik-app.intranet.br \
    --tmpfs /run:rw,noexec,nosuid,size=8m \
    --tmpfs /tmp:rw,noexec,nosuid,size=8m \
    --read-only \
    --cpus="8.0" --memory=4g --memory-swap=4g \
    \
    --network network_public \
    \
    -p 80:80 \
    -p 443:443 \
    \
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
    -v /storage/traefik-app/letsencrypt:/etc/letsencrypt \
    -v /storage/traefik-app/config:/etc/traefik \
    -v /storage/traefik-app/logs:/logs \
    \
    traefik:latest \
      \
      --global.checkNewVersion=false \
      --global.sendAnonymousUsage=false \
      \
      --api.insecure=true \
      \
      --log.level=INFO \
      --log.filePath=/logs/error.log \
      \
      --accessLog.filePath=/logs/access.log \
      \
      --entrypoints.web.address=:80 \
      --entrypoints.web.http.redirections.entryPoint.to=websecure \
      --entrypoints.web.http.redirections.entryPoint.scheme=https \
      --entrypoints.web.http.redirections.entryPoint.permanent=true \
      --entrypoints.websecure.address=:443 \
      \
      --providers.docker=true \
      --providers.file.directory=/etc/traefik \
      \
      --certificatesresolvers.letsencrypt.acme.email=$EMAIL \
      --certificatesresolvers.letsencrypt.acme.storage=/etc/letsencrypt/acme.json \
      --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web;

# Email de contato para o certificado LetsEncrypt:
    EMAIL="voce@seudominio.com.br";
    [ -f /etc/email ] && EMAIL=$(head -1 /etc/email);

# Imagem do traefik, baixar atualizada:
    docker pull traefik:latest;

# Diretorio de dados persistentes:
    mkdir -p /storage/traefik-app/letsencrypt;
    mkdir -p /storage/traefik-app/logs;
    mkdir -p /storage/traefik-app/config;

# Renovar/rodar:
  docker rm -f traefik-app 2>/dev/null;
  docker run \
    -d --restart=always \
    --name traefik-app -h traefik-app.intranet.br \
    --tmpfs /run:rw,noexec,nosuid,size=8m \
    --tmpfs /tmp:rw,noexec,nosuid,size=8m \
    --read-only \
    --cpus="8.0" --memory=4g --memory-swap=4g \
    \
    --network network_public \
    \
    -p 80:80 \
    -p 443:443 \
    \
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
    -v /storage/traefik-app/letsencrypt:/etc/letsencrypt \
    -v /storage/traefik-app/config:/etc/traefik \
    -v /storage/traefik-app/logs:/logs \
    \
    traefik:latest \
      \
      --global.checkNewVersion=false \
      --global.sendAnonymousUsage=false \
      \
      --api.insecure=true \
      \
      --log.level=INFO \
      --log.filePath=/logs/error.log \
      \
      --accessLog.filePath=/logs/access.log \
      \
      --entrypoints.web.address=:80 \
      --entrypoints.web.http.redirections.entryPoint.to=websecure \
      --entrypoints.web.http.redirections.entryPoint.scheme=https \
      --entrypoints.web.http.redirections.entryPoint.permanent=true \
      --entrypoints.websecure.address=:443 \
      \
      --providers.docker=true \
      --providers.file.directory=/etc/traefik \
      \
      --certificatesresolvers.letsencrypt.acme.email=$EMAIL \
      --certificatesresolvers.letsencrypt.acme.storage=/etc/letsencrypt/acme.json \
      --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web;

2.4 – Banco de dados PostgreSQL

Vamos criar um banco de dados PostgreSQL chamado “n8n-pgsql“.
Arquivo: /root/n8n-deploy/run-03-n8n-postgresql.sh

# Credenciais de acesso ao PG
    POSTGRES_USER="postgres";
    POSTGRES_PASSWORD="tulipasql";
    POSTGRES_DB="n8n";

# Pasta para o volume
    mkdir -p /storage/n8n-pgsql;
    chown -R 999:999 /storage/n8n-pgsql;

# Rodar:
    docker pull pgvector/pgvector:pg18-trixie;
    docker run \
        -d --restart=always \
        --name n8n-pgsql -h n8n-pgsql.intranet.br \
        --read-only --cpus="2.0" --memory=2g --memory-swap=2g --shm-size=1g \
        \
        --network network_public \
        \
        --tmpfs /run:rw,noexec,nosuid,size=128m \
        --tmpfs /tmp:rw,noexec,nosuid,size=128m \
        \
        -v /storage/n8n-pgsql:/var/lib/postgresql/data \
        \
        -e POSTGRES_USER=$POSTGRES_USER \
        -e POSTGRES_PASSWORD=$POSTGRES_PASSWORD \
        -e POSTGRES_DB=$POSTGRES_DB \
        -e PGDATA=/var/lib/postgresql/data/pgdata \
        \
        --health-cmd="pg_isready -U postgres" \
        --health-interval=5s \
        --health-timeout=5s \
        --health-retries=10 \
        \
        --entrypoint "docker-entrypoint.sh" \
        \
        pgvector/pgvector:pg18-trixie \
            postgres \
                --max_connections=8192 \
                --wal_level=minimal \
                --max_wal_senders=0 \
                --port=5432;

# Credenciais de acesso ao PG
    POSTGRES_USER="postgres";
    POSTGRES_PASSWORD="tulipasql";
    POSTGRES_DB="n8n";

# Pasta para o volume
    mkdir -p /storage/n8n-pgsql;
    chown -R 999:999 /storage/n8n-pgsql;

# Rodar:
    docker pull pgvector/pgvector:pg18-trixie;
    docker run \
        -d --restart=always \
        --name n8n-pgsql -h n8n-pgsql.intranet.br \
        --read-only --cpus="2.0" --memory=2g --memory-swap=2g --shm-size=1g \
        \
        --network network_public \
        \
        --tmpfs /run:rw,noexec,nosuid,size=128m \
        --tmpfs /tmp:rw,noexec,nosuid,size=128m \
        \
        -v /storage/n8n-pgsql:/var/lib/postgresql/data \
        \
        -e POSTGRES_USER=$POSTGRES_USER \
        -e POSTGRES_PASSWORD=$POSTGRES_PASSWORD \
        -e POSTGRES_DB=$POSTGRES_DB \
        -e PGDATA=/var/lib/postgresql/data/pgdata \
        \
        --health-cmd="pg_isready -U postgres" \
        --health-interval=5s \
        --health-timeout=5s \
        --health-retries=10 \
        \
        --entrypoint "docker-entrypoint.sh" \
        \
        pgvector/pgvector:pg18-trixie \
            postgres \
                --max_connections=8192 \
                --wal_level=minimal \
                --max_wal_senders=0 \
                --port=5432;

2.5 – Redis

O Redis é vital para o N8N, vamos criar o container chamado “n8n-redis“.
Arquivo: /root/n8n-deploy/run-04-n8n-redis.sh

# Pasta de persistencia RDB e AOF:
    mkdir -p /storage/n8n-redis;
    chown -R 999:999 /storage/n8n-redis;

# Baixar imagem atualizada do Redis (https://hub.docker.com/_/redis):
    docker pull redis:latest;

# Remover container atual:
    docker rm -f n8n-redis 2>/dev/null;
    
# Criar container do redis:
    docker run \
        -d --restart=always \
        --name n8n-redis -h n8n-redis.intranet.br \
        --read-only --cpus="1.0" --memory=1g --memory-swap=1g \
        \
        --network network_public \
        \
        -v /storage/n8n-redis:/data \
        -w /data \
        \
        --health-cmd="redis-cli ping" \
        --health-interval=1s \
        --health-timeout=3s \
        \
        redis:latest \
            redis-server \
                --tcp-backlog 8192 --tcp-keepalive 30 --timeout 0 \
                --dir /data --save 16 1 --save 12 10 --save  6 100 \
                --rdbcompression no --appendonly yes --appendfsync everysec;

# Pasta de persistencia RDB e AOF:
    mkdir -p /storage/n8n-redis;
    chown -R 999:999 /storage/n8n-redis;

# Baixar imagem atualizada do Redis (https://hub.docker.com/_/redis):
    docker pull redis:latest;

# Remover container atual:
    docker rm -f n8n-redis 2>/dev/null;
    
# Criar container do redis:
    docker run \
        -d --restart=always \
        --name n8n-redis -h n8n-redis.intranet.br \
        --read-only --cpus="1.0" --memory=1g --memory-swap=1g \
        \
        --network network_public \
        \
        -v /storage/n8n-redis:/data \
        -w /data \
        \
        --health-cmd="redis-cli ping" \
        --health-interval=1s \
        --health-timeout=3s \
        \
        redis:latest \
            redis-server \
                --tcp-backlog 8192 --tcp-keepalive 30 --timeout 0 \
                --dir /data --save 16 1 --save 12 10 --save  6 100 \
                --rdbcompression no --appendonly yes --appendfsync everysec;

3 – Variáveis de ambiente

O N8N possui uma vastidão de variáveis de ambientes mas elas podem ser divididas de acordo com suas finalidades e quais serviços precisam delas.

Variáveis com valor semelhante ao valor padrão estarão em AZUL e os valores alterados e personalizados de VERMELHO.

Você pode omitir todas as variáveis em AZUL sem problemas, isso economiza espaço na configuração.

3.1 – Modo fila (1 variável)

O antigo modo simples baseado no sqlite foi substituído pelo modo fila que faz uso do Redis e PostgreSQL por meio da técnica Claim Check Pattern (sinais em tempo real no Redis pub/sub e dados de transações no SQL).

Dados para acesso ao Redis e PG do modelo fila foram definidos na criação dos containers no capítulo 2.

Usadas pelo editor, webhook e worker, não são usadas pelo task-runner.

3.2 – Acesso a Redis (1 variável)

Usados pelo editor, webhook e worker, não é usado pelo task-runner.

Variáveis do Redis:

3.3 – Acesso a Postgres (3 variáveis)

Usados pelo editor, webhook e worker, não é usado pelo task-runner.

O N8N não envia operações de vaccum para o postgres, lembre de fazer essa rotina mensalmente.

3.4 – Opções globais (2 variáveis)

Variáveis de uso global e necessárias para todos os serviços: editor, webhook, worker, e task-runner.

3.5 – Opções gerais (5 variáveis)

Variáveis usadas pelo editor, webhook e worker, não são usadas no task-runner.

3.6 – Opções de servidor http (4 variáveis)

Variáveis usadas apenas pelos serviços que abrem a porta HTTP para webhooks.

Usados pelo editor e webhook, não é usado pelo worker e task-runner.

3.6 – Opções exclusivas do editor (7 variáveis)

Usados somente pelo editor (frontend e backend).

3.7 – Opções do editor e worker (3 variáveis)

Usados pelo editor e worker, não é usado pelo webhook e task-runner.

3.8 – Opções exclusivas do worker (2 variáveis)

Variáveis usadas somente pelo worker.

3.9 – Opções exclusivas do task-runner (2 variáveis)

Variáveis usadas pelo task-runner.

3.9 – Opções do worker e task-runner (2 variáveis)

Usados pelo worker e task-runner.

3.10 – Opções de gerenciamento de usuários e SMTP (4 variáveis)

Usados pelo editor para envio de emails (notificações, convites, recuperação de senha).

3.11 – Opções da licença enterprise (4 variáveis)

Quando a licença enterprise é ativada você pode usar novos recursos localmente.
Use esse link para adquirir a licença: https://n8n.io/enterprise/

As variáveis para instalar a licença devem ser informadas em todos os serviços do n8n ( editor, worker e webhook, menos o task-runner:

As variáveis de controle de recursos enterprise são: