Como configurar o n8n em queue mode no Docker: passo a passo atualizado

Aprenda o passo a passo mais atualizado para configurar o n8n em queue mode no Docker, garantindo escalabilidade, alta performance e paralelismo para projetos profissionais. Veja dicas de arquitetura, preparação do ambiente e manutenção de workers em containers.

A automação de tarefas e fluxos utilizando o n8n está cada vez mais sofisticada, especialmente com a possibilidade de executar workflows em paralelo com o queue mode. Para aqueles que buscam criar projetos escaláveis, robustos e com performance elevada, aprender a configurar o “n8n queue mode docker” é essencial. Neste guia, abordaremos de forma didática e prática todos os passos necessários para entender, preparar e executar o n8n em queue mode usando Docker Compose, além de dicas valiosas sobre escalabilidade e gestão de workers.

Se você está começando e quer dar seus primeiros passos na automação profissional com n8n, este artigo vai te orientar desde os conceitos básicos até a montagem de uma arquitetura pronta para crescer junto com as necessidades do seu negócio ou empresa.

Entendendo o queue mode do n8n e suas vantagens

O queue mode do n8n é um recurso avançado que permite escalonar a execução dos seus workflows, processando múltiplas tarefas ao mesmo tempo, de maneira controlada e organizada. Em vez de executar tudo em um só processo, o n8n divide os trabalhos em filas (queues), podendo alocar diferentes workers (trabalhadores) para processar essas tarefas em paralelo.

As principais vantagens desse modo são:

• Paralelismo real: workflows são processados simultaneamente por múltiplos workers, acelerando fluxos de alto volume.
• Resiliência: falhas em um fluxo não afetam outros, já que estão isolados em processos distintos.
• Escalabilidade: é possível aumentar (ou diminuir) o número de workers conforme a demanda, otimizando uso de recursos.
• Performance e controle: usando filas, você ajusta prioridades e pode limitar o número de workflows rodando ao mesmo tempo, melhorando o gerenciamento.

O queue mode é ideal para quem precisa processar muitos dados ou responder a eventos de alta frequência sem engasgos. Por isso, é tão utilizado em soluções profissionais e projetos que exigem alta disponibilidade.

Dica para aprender mais: Formação Agentes de IA (n8n + automações sem código)

Se você está gostando de mergulhar no mundo do n8n, automações e agentes inteligentes, uma dica valiosa é conhecer a Formação Agentes de IA da Hora de Codar. Esse treinamento é ideal para quem quer dominar desde o básico do n8n até a construção de fluxos avançados e agentes de IA prontos para o mercado.

O que achei mais interessante é que ele foi desenhado para quem está começando: não exige experiência prévia em programação e ensina do zero como instalar, configurar e criar automações realmente inteligentes. São mais de 20 horas de conteúdo, diversos projetos práticos e uma comunidade super ativa para tirar dúvidas e trocar experiências.

O acesso é vitalício e os materiais são sempre atualizados. Tem até módulos focados em automações profissionais, integração com APIs, bancos de dados vetoriais e muito mais. Se quer acelerar seu aprendizado e construir aplicações reais com n8n e IA, recomendo conhecer: Confira a Formação Agentes de IA aqui.

Formação Recomendada

Formação Agentes de IA

Domine a criação de Agentes de IA e Venda para Empresas

• 402 aulas
• 32 projetos
• 38h 19min

Conhecer formação

Arquitetura: como o n8n funciona em queue mode no Docker

Para aproveitar todo o potencial do queue mode, o n8n se apoia em uma arquitetura distribuída. No Docker, essa arquitetura é fácil de montar e escalar.

Veja como os componentes principais interagem:

1. Instância Principal (Main): responsável pela orquestração geral dos fluxos e gerenciamento das filas. Não executa workflows, apenas distribui tarefas para os workers.
2. Workers: são os containers que realmente processam as tarefas dos workflows. Você pode subir vários containers workers, aumentando a capacidade de processamento.
3. Banco de Dados (ex: PostgreSQL): armazena dados dos fluxos, execuções e configurações do n8n.
4. Redis: atua como sistema de gerenciamento das filas, garantindo que as tarefas sejam distribuídas de forma confiável e ordenada aos workers.

No Docker Compose, cada um desses elementos fica em um container separado. Isso garante flexibilidade para atualizar, reiniciar ou escalar cada componente individualmente.

Por exemplo, se seu sistema começar a processar mais workflows simultâneos, basta aumentar o número de containers worker especificados no Compose. Essa arquitetura modular também facilita a manutenção e futuras otimizações do ambiente.

Vídeo em destaque: Como instalar o n8n localmente – Instale o n8n com o npm no seu computador

Se você está começando no universo do n8n ou quer visualizar passo a passo a instalação e configuração, recomendo este vídeo completo do Hora de Codar: Como instalar o n8n localmente – Instale o n8n com o npm no seu computador. O conteúdo explica detalhes básicos do funcionamento do n8n e serve como apoio para quem deseja entender melhor a ferramenta antes de partir para configurações mais avançadas, como o queue mode.

Aproveite para assistir e tirar suas dúvidas de iniciante!

Link do vídeo: https://www.youtube.com/embed/4ZksrjJuARo?si=4TVDkaLV68dUt032

Pré-requisitos e preparação do ambiente com Docker Compose

Antes de colocar o n8n em queue mode para rodar via Docker Compose, alguns pré-requisitos são essenciais para garantir o bom funcionamento e segurança do seu ambiente:

• Docker e Docker Compose instalados: Se ainda não tem, instale-os no seu sistema operacional usando comandos oficiais conforme seu sistema.
• Banco de dados PostgreSQL: Recomendado para uso profissional e performance. Você pode criar um serviço no docker-compose.yaml para isso.
• Redis: Fundamental para o modo fila, será responsável pela orquestração das filas.
• Configuração das variáveis de ambiente: Algumas variáveis são obrigatórias para queue mode (como N8NEXECUTIONSPROCESS e QUEUEBULLREDIS). Mapeie senha e usuário do PostgreSQL, e as configurações do Redis corretamente.
• Volumes persistentes: Garanta que dados do n8n e banco fiquem salvos mesmo que containers sejam reiniciados.
• Rede isolada: Configure o Docker Compose para usar uma rede dedicada, evitando conflitos e aumentando a segurança.

Com esses itens prontos, você cria um ambiente escalável, seguro e pronto para rodar o n8n com filas de processamentos. Se for seu primeiro contato, comece montando um docker-compose.yaml básico e ajuste conforme ganhar mais confiança e experiência.

Passo a passo: configuração do n8n queue mode com Docker Compose

Agora vamos à parte prática! Siga estas etapas para configurar o n8n em queue mode usando Docker Compose:

1. Crie um arquivo docker-compose.yaml: Nele, defina os serviços principais: n8n main, n8n worker, PostgreSQL e Redis.
2. Configuração do serviço Main:

• Defina as variáveis que indicam o modo fila/executions-process.
• Exemplo principais: N8NEXECUTIONSPROCESS=queue, DB_TYPE=postgresdb, etc.
• Mapear as portas de acesso.

1. Configuração dos Workers:

• Utilize a mesma imagem do n8n, mudando a configuração para QUEUE_MODE=worker.
• Pode definir quantos containers quiser (proporcional à necessidade de paralelismo).

1. Configuração do PostgreSQL e Redis:

• Use as imagens oficiais.
• Assegure volumes para persistência dos dados e variáveis de conexão corretas.

1. Suba o ambiente:

• Rode docker-compose up -d e acompanhe os logs para garantir que todos os serviços iniciaram corretamente.

1. Acesse o n8n:

• Normalmente pelo navegador em http://localhost:5678 ou ajustando para a porta definida.

Exemplo básico do conteúdo do arquivo docker-compose.yaml:

version: ‘3.8’
services:
n8n-main:
image: n8nio/n8n:latest
environment:
– N8NEXECUTIONSPROCESS=queue
– DBTYPE=postgresdb
– DBPOSTGRESDBHOST=postgres
– DBPOSTGRESDBPORT=5432
– DBPOSTGRESDBDATABASE=n8n
– DBPOSTGRESDBUSER=n8n
– DBPOSTGRESDBPASSWORD=senhadificil
– QUEUEBULLREDISHOST=redis
ports:
– “5678:5678”
dependson:
– postgres
– redis
networks:
– n8n-network
volumes:
– ./n8n-data:/home/node/.n8n
n8n-worker:
image: n8nio/n8n:latest
environment:
– N8NEXECUTIONSPROCESS=queue
– QUEUEMODE=worker
– DBTYPE=postgresdb
– DBPOSTGRESDBHOST=postgres
– DBPOSTGRESDBPORT=5432
– DBPOSTGRESDBDATABASE=n8n
– DBPOSTGRESDBUSER=n8n
– DBPOSTGRESDBPASSWORD=senhadificil
– QUEUEBULLREDISHOST=redis
dependson:
– postgres
– redis
networks:
– n8n-network
postgres:
image: postgres:13
environment:
POSTGRESUSER: n8n
POSTGRESPASSWORD: senhadificil
POSTGRESDB: n8n
volumes:
– ./postgres-data:/var/lib/postgresql/data
networks:
– n8n-network
redis:
image: redis:6
networks:
– n8n-network
networks:
n8n-network:
driver: bridge

Com esse setup, você terá um ambiente inicial robusto e pronto para escalar conforme o crescimento da sua automação.

Sugestão para hospedar seu n8n: VPS Hostinger com desconto exclusivo

Pensando em rodar o n8n em produção ou ambientes que exigem alta performance? Uma alternativa que tenho gostado bastante é usar a VPS da Hostinger, que já traz o n8n pré-instalado e pronta para escalar conforme o seu projeto cresce.

A Hostinger oferece diferentes planos de VPS, todos com SSD NVMe, uptime de 99,9% e a possibilidade de aumentar CPU, memória e armazenamento de acordo com a demanda dos seus workflows e workers em queue mode. Outra vantagem é o controle total do ambiente e a liberdade para customizar como quiser, além de facilitar upgrades ou mantenções sem interromper seus fluxos.

Quem acompanha o Hora de Codar ainda conta com cupom de desconto exclusivo HORADECODAR! Para conhecer os planos e garantir sua infraestrutura para o n8n: https://www.hostinger.com.br/horadecodar

Essa estrutura é ideal especialmente para quem pretende escalar o n8n usando Docker e filas, garantindo performance, segurança e suporte especializado.

Escalabilidade e dicas para gerenciar workers do n8n no Docker

Escalar o n8n no queue mode usando Docker é uma das grandes vantagens dessa arquitetura. Aqui vão dicas e boas práticas para manter o sistema eficiente e confiável:

• Adicione mais workers conforme a necessidade: Basta replicar o serviço n8n-worker no seu Docker Compose. Por exemplo: docker-compose up –scale n8n-worker=4 cria quatro workers para processar tarefas simultâneas.
• Acompanhe o uso de CPU/Memória: Monitore os recursos dos containers para evitar sobrecargas. Ajuste a quantidade de workers de acordo com a capacidade do seu servidor.
• Mantenha PostgreSQL e Redis performáticos: Ambos são pontos críticos do sistema. Considere aumentar recursos e monitorar uso. Evite compartilhar o mesmo host com muitos processos pesados.
• Estruture logs e alertas: Configure logging dos containers para identificar travamentos ou gargalos e, se possível, utilize ferramentas de monitoramento como Portainer ou Prometheus.
• Backups frequentes: Tanto dos dados do workflow (PostgreSQL) quanto dos arquivos do sistema (volumes Docker), garantindo segurança em caso de falhas.

Um ponto fundamental: se for rodar o n8n em projetos mais sérios ou de produção, pense em utilizar uma VPS (como a Hostinger) para garantir estabilidade, performance e flexibilidade na escalabilidade. A abordagem modular via Docker facilita upgrades e manutenções sem downtime prolongado.

Conclusão

A configuração do n8n em queue mode usando Docker Compose é uma solução moderna, robusta e escalável para quem precisa automatizar muitos workflows com alta performance e flexibilidade. Ao compreender as vantagens do queue mode, montar a arquitetura distribuída correta e adequar o ambiente aos pré-requisitos, você garante estabilidade e eficiência mesmo em projetos de grande porte.

Para dar seus primeiros passos, aproveite o exemplo de docker-compose para criar e testar o ambiente localmente. E lembre-se: para crescer com segurança e tranquilidade, utilizar uma VPS de qualidade (como a Hostinger) faz toda diferença, além de investir em aprendizado constante com treinamentos como a Formação Agentes de IA. Assim, você terá um setup de n8n queue mode docker pronto para acompanhar as exigências do mercado e explorar ao máximo o potencial dos containers, automações e agentes inteligentes.

Agora é só partir para a prática, escalar seus fluxos e desfrutar das vantagens do queue mode em containers Docker!

Quando o queue mode NÃO vale a pena:

Vou ser honesto contigo antes de você sair subindo container

Queue mode não é upgrade automático, é troca de problema

Você sai de uma instância só, simples de subir e simples de debugar, e passa a cuidar de Redis, banco, main e workers, cada um com seus próprios logs e seus próprios jeitos de quebrar

Se o teu n8n hoje roda poucos fluxos, leves, sem pico e sem fila travada, o queue mode só te dá mais coisa pra monitorar

Faz sentido migrar quando:

• Você já vê execução esperando a anterior terminar
• Tem fluxo pesado (scraping, IA, processamento de arquivo) segurando todo o resto
• Você precisa que uma falha não derrube os outros fluxos
• O ambiente é de produção e não pode ficar de pé só com um processo

Não faz muito sentido quando:

• É ambiente de estudo ou teste local
• São poucos fluxos por dia, rápidos, sem concorrência
• Você ainda não monitora nem a instância única (aí o queue mode só multiplica aquilo que tu não enxerga)

Regra prática: primeiro medir o engasgo, depois escalar

Escalar por achismo é tipo comprar PC da Nasa pra abrir planilha 😅

Queue mode ou só um servidor mais forte?

Pergunta que aparece direto, e a resposta não é a mesma pros dois casos

Subir a máquina (mais CPU, mais memória) resolve quando o gargalo é um fluxo pesado sozinho: ele ganha mais fôlego pra rodar

Queue mode resolve quando o gargalo é volume: muita execução disputando o mesmo processo

Se liga na diferença: máquina mais forte deixa cada tarefa mais confortável, queue mode deixa MAIS tarefas acontecerem ao mesmo tempo

Na prática, quem roda em produção acaba usando os dois: uma máquina que aguenta o tranco e workers pra distribuir a carga

E tem um terceiro caminho que muita gente esquece: arrumar o fluxo

Loop desnecessário, nó rodando item por item quando podia ir em lote, espera parada no meio do caminho… às vezes o problema não é infra, é o workflow mesmo

Como saber se o queue mode subiu de verdade:

Container com status "up" não significa queue mode funcionando, beleza?

Dá pra subir tudo bonitinho e o worker ficar parado a vida inteira sem pegar uma tarefa sequer

Checagem rápida, na unha:

1. Abra a interface e dispare um fluxo que demora um pouquinho
2. Olhe os logs do container do worker: é lá que a execução tem que aparecer, não no main
3. Dispare dois fluxos ao mesmo tempo e veja se eles andam juntos, em vez de um ficar esperando o outro

Se o worker está de braços cruzados, o suspeito número um é sempre o mesmo: main e worker não estão enxergando o MESMO Redis e o MESMO banco

Um errinho de nome de serviço, de rede ou de senha já é suficiente pra isso

Vale conferir também se todos os containers estão na mesma rede do Compose, e se o banco realmente aceitou a conexão (o log do Postgres entrega isso rapidinho)

Tome cuidado com uma pegadinha clássica de tutorial: copiar o YAML, trocar a senha em um serviço e esquecer de trocar no outro

Aí o worker sobe, tenta conectar, apanha calado, e você fica olhando pra tela achando que o queue mode não presta 😄

Quantos workers eu preciso?

Não existe número mágico, e desconfia de quem te der um 😉

O número certo depende de três coisas: o que teus fluxos fazem, quanto a máquina aguenta e quanta fila você tolera

Fluxo que fica só esperando resposta de API segura bem mais paralelismo do que fluxo que mastiga arquivo ou chama modelo de IA

Como chegar no número sem chutar:

• Comece com poucos workers e observe o comportamento
• Acompanhe CPU e memória dos containers enquanto o volume sobe
• Aumente de pouco em pouco, sempre olhando se banco e Redis continuam tranquilos
• Pare de aumentar quando o gargalo mudar de lugar (se a máquina já está no talo, mais worker só piora)

Um detalhe que salva: worker demais no mesmo host começa a brigar por recurso com o próprio Postgres

Aí você acha que escalou e na verdade só empurrou a fila pra outro canto

Antes de copiar qualquer YAML da internet (inclusive o meu):

Esse tipo de conteúdo envelhece, e envelhece rápido

n8n, Docker, Postgres e Redis seguem cada um o seu ritmo de versão, e o que era padrão ontem pode ter mudado de nome, de valor padrão ou de comportamento

Então trate o exemplo daqui como PONTO DE PARTIDA, não como verdade eterna

O que conferir sempre antes de subir:

• Abra a documentação oficial do n8n e confirme como o queue mode é configurado na versão que você vai usar: nome de variável e valor padrão mudam entre versões
• Fixe a versão das imagens em vez de deixar tudo em latest, assim o teu ambiente não muda sozinho de madrugada
• Nunca leve senha de exemplo pra produção, troque tudo antes
• Não publique as portas do banco e do Redis pra fora: eles só precisam conversar dentro da rede do Compose
• Suba primeiro num ambiente de teste, depois leve pro sério
• Guarde o teu docker-compose.yaml no Git: quando algo quebrar depois de uma atualização, você compara e acha a diferença rapidinho

Parece burocracia, mas é isso que separa um n8n que aguenta o ano inteiro de um que cai no primeiro update 🙂