Guia Completo: Instalar n8n Self-Hosted com Docker e PostgreSQL

n8n é uma ferramenta de automação de workflows baseada em nó, amplamente reconhecida por sua flexibilidade e capacidade de self-hosting. Diferente de plataformas SaaS fechadas, a versão self-hosted permite total controle sobre os dados, a infraestrutura subjacente e a lógica de execução das integrações. Para ambientes corporativos que exigem alta disponibilidade, escalabilidade e conformidade com políticas de segurança rigorosas, a configuração padrão (que utiliza SQLite) não é suficiente.

Neste tutorial técnico, detalhamos o processo de implantação do n8n self-hosted utilizando Docker Compose, com foco em uma arquitetura robusta que separa os componentes críticos. Utilizaremos um banco de dados PostgreSQL externo para persistência de dados e um servidor Redis como fila de execução (queue) para garantir que workflows longos ou complexos não bloqueiem a interface web do usuário.

Pré-requisitos e Arquitetura da Solução

Antes de iniciar a instalação, é fundamental entender os componentes que compõem esta stack. A decisão de separar o banco de dados e a fila do container principal do n8n traz benefícios significativos em termos de performance e durabilidade dos dados.

Docker & Docker Compose: Ferramentas essenciais para orquestração de containers.
PostgreSQL: Banco de dados relacional robusto. A versão community do n8n suporta nativamente o PostgreSQL, oferecendo melhor concorrência e gerenciamento de transações comparado ao SQLite.
Redis: Estrutura de dados em memória usada como broker de mensagens. Ao configurar o NODE_FUNCTION_ALLOW_EXTERNAL e a fila Redis, o n8n libera o thread principal para atender requisições HTTP, enquanto as execuções pesadas dos workflows são processadas assincronamente.
Nginx (Opcional mas recomendado): Para gerenciar certificados SSL/TLS e roteamento de tráfego, embora possamos focar inicialmente na configuração interna do n8n.

Certifique-se de que seu servidor Linux (Ubuntu, Debian ou CentOS) tenha as últimas atualizações instaladas e que o Docker Engine esteja em execução com permissões adequadas para o usuário atual.

Passo 1: Preparação do Ambiente Docker

A primeira etapa consiste em criar uma estrutura de diretórios organizada. Isso facilita a manutenção, o versionamento das configurações e o backup futuro. Vamos criar um diretório dedicado para a aplicação n8n.

mkdir -p ~/n8n-docker/n8n-data
mkdir -p ~/n8n-docker/postgres-data
mkdir -p ~/n8n-docker/redis-data

A estrutura acima define três volumes persistentes:

n8n-data: Armazena credenciais de nós, configurações do usuário e dados locais se não estiverem no banco externo.
postgres-data: Persiste o banco de dados PostgreSQL.
redis-data: Mantém a cache do Redis (útil para alta performance, embora o Redis possa ser configurado como stateless em alguns cenários).

Passo 2: Configuração do Docker Compose

Crie um arquivo chamado docker-compose.yml dentro do diretório ~/n8n-docker. Este arquivo definirá os serviços, redes e variáveis de ambiente necessárias para a integração avançada.

version: '3.8'

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=seu-dominio.com ou IP_SERVIDOR
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - NODE_ENV=production
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_USER=n8n_user
      - DB_POSTGRESDB_PASSWORD=senha_forte_aqui
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
      - GENERIC_TIMEZONE=America/Sao_Paulo
    volumes:
      - ./n8n-data:/home/node/.n8n
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:15-alpine
    restart: always
    environment:
      - POSTGRES_DB=n8n
      - POSTGRES_USER=n8n_user
      - POSTGRES_PASSWORD=senha_forte_aqui
    volumes:
      - ./postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    restart: always
    command: redis-server --appendonly yes
    volumes:
      - ./redis-data:/data

Análise técnica da configuração:

Note a variável DB_TYPE=postgresdb. Ela instrui o n8n a utilizar o driver PostgreSQL. As credenciais são passadas via variáveis de ambiente, conectando-se ao serviço postgres definido no mesmo Docker network. Da mesma forma, as variáveis QUEUE_BULL_REDIS_HOST e QUEUE_BULL_REDIS_PORT ativam o sistema de filas BullMQ baseado em Redis.

A opção command: redis-server --appendonly yes no serviço Redis garante a persistência dos dados da fila através do mecanismo AOF (Append Only File), evitando perda de jobs em caso de reinicialização inesperada do container.

Passo 3: Inicialização e Verificação dos Serviços

Com o arquivo docker-compose.yml salvo, inicie os contêineres em segundo plano:

cd ~/n8n-docker
docker compose up -d

Aguarde alguns segundos para que as imagens sejam baixadas e os containers inicializados. Para verificar se todos os serviços estão rodando corretamente, execute:

docker compose ps

O retorno deve indicar status "Up" para todos os três serviços: n8n, postgres e redis. Se algum serviço estiver em estado "Restarting", verifique os logs com docker compose logs -f n8n para identificar erros de conexão ou permissão.

Passo 4: Configuração Inicial do n8n e Integração com CRM

Acesse a interface web do n8n através de http://IP_SERVIDOR:5678. Na primeira execução, o sistema solicitará a criação de um usuário administrador. Preencha os dados solicitados.

Após o login, você estará no editor de workflows. Para integrar com seu CRM (seja Salesforce, HubSpot, Pipedrive ou outro), siga estes passos:

Navegue até a aba Credentials (Credenciais) no menu lateral.
Clique em + Add Credential.
Selecione o tipo de serviço do seu CRM. A maioria dos CRMs modernos utiliza OAuth2 ou API Keys.
Preencha os dados fornecidos pelo provedor do CRM (Client ID, Client Secret, Tokens de Acesso).

Dica de Pro: Ao utilizar o Redis como fila, workflows que exigem chamadas HTTP lentas ou processamento de grandes volumes de dados não travarão a interface. Isso é crucial para integrações com CRMs que possuem limites de taxa (rate limits) rigorosos. Certifique-se de configurar nós de "Wait" ou "Split In Batches" dentro do seu workflow para respeitar esses limites.

Passo 5: Backup e Recuperação de Dados

A manutenção de um ambiente self-hosted exige uma estratégia clara de backup. Como estamos utilizando volumes Docker mapeados para o host, o backup é direto, mas requer atenção à consistência dos dados.

Backup do Banco de Dados PostgreSQL

O método mais seguro é utilizar a ferramenta pg_dump. Execute o seguinte comando para criar um dump completo do banco:

docker exec n8n-docker-postgres-1 pg_dump -U n8n_user n8n > backup_n8n_$(date +%F).sql

Este comando gera um arquivo SQL que pode ser armazenado em outro local seguro. Para restaurar, utilize o psql:

docker exec -i n8n-docker-postgres-1 psql -U n8n_user n8n < backup_n8n_2023-10-27.sql

Backup dos Arquivos Locais e Redis

Para backups completos que incluam credenciais salvas localmente (se houver) e estado do Redis, utilize o tar ou rsync:

tar -czvf n8n-full-backup_$(date +%F).tar.gz ./n8n-data ./postgres-data ./redis-data

Mantenha uma rotina automatizada, preferencialmente via cron jobs no host, para enviar esses backups para um objeto storage S3 ou serviço similar.

Passo 6: Troubleshooting Comum em Ambientes Produção

Ainda que a configuração seja robusta, problemas podem ocorrer. Abaixo, listamos os cenários mais frequentes e suas resoluções.

Problema: Workflow não executa ou fica "Running" indefinidamente

Se um workflow inicia mas nunca termina, pode ser um erro de lógica no nó ou um timeout de conexão externa. No entanto, se o Redis está configurado corretamente, o n8n deve processar a fila em background.

Verifique os logs do container Redis: docker compose logs -f redis.
Confirme que as variáveis de ambiente QUEUE_BULL_REDIS_HOST estão corretas. Um erro comum é usar localhost em vez do nome do serviço Docker (neste caso, redis).

Problema: Erro de Conexão com PostgreSQL

Mensagens como "FATAL: password authentication failed" indicam que as variáveis de ambiente no serviço n8n não correspondem às definidas no serviço postgres.

Verifique o arquivo docker-compose.yml.
Garanta que o usuário e senha estejam idênticos em ambos os blocos de serviço.
Reinicie os serviços com docker compose down && docker compose up -d para garantir que as variáveis sejam recarregadas corretamente na inicialização.

Problema: Interface Web Lenta ou Não Carrega

Isto pode indicar falta de recursos de memória RAM ou CPU. O n8n, especialmente com muitos workflows ativos e o Redis em uso, consome recursos significativos durante a execução.

Monitore o uso de recursos com docker stats.
Ajuste as variáveis de ambiente do Node.js se necessário, aumentando o limite de memória heap:

- NODE_OPTIONS=--max_old_space_size=4096

Considerações Finais sobre Segurança e Escala

A instalação básica expõe a porta 5678 diretamente. Em produção, **nunca** deixe essa porta acessível publicamente sem proteção. Utilize um reverse proxy como Nginx ou Traefik na frente do n8n para gerenciar certificados SSL e autenticação adicional.

Além disso, para ambientes de alta demanda, considere a implementação de múltiplas instâncias do container n8n atrás de um balanceador de carga. O Redis e o PostgreSQL suportam naturalmente essa escalabilidade horizontal, desde que as variáveis de ambiente N8N_HOST reflitam o endereço do balanceador.

A automação via n8n self-hosted, quando configurada com PostgreSQL externo e Redis Queue, oferece uma plataforma estável, segura e escalável para integrar seus CRMs e sistemas internos. A capacidade de controlar a infraestrutura permite que equipes de DevOps e SREs apliquem suas melhores práticas de monitoramento, backup e recuperação de desastres diretamente aos fluxos de trabalho da empresa.

Com esta base estabelecida, você está preparado para criar workflows complexos, garantir a integridade dos dados transacionais e manter a operação contínua da sua automação corporativa.

Tags: #n8n self-hosted #instalação docker #redis queue #postgresql externo #automação workflows #backup n8n #troubleshooting n8n #integrações crm