n8n com Docker: instalar e hospedar por conta própria gratuitamente

#Por que instalar o n8n com Docker em vez de npm

O n8n é uma aplicação Node.js. É possível iniciá-lo com npm ou npx, e a documentação sugere essa opção para um teste rápido. Para uma instância em execução contínua, a imagem Docker oficial é o caminho recomendado pelo projeto: ela inclui a versão correta do Node.js, isola o n8n do restante da máquina e torna a atualização tão simples quanto trocar a imagem. Esse também é o formato usado pela documentação de hospedagem do n8n para descrever todos os exemplos de servidor.

A segunda vantagem é a reprodutibilidade. Um arquivo docker-compose.yml descreve toda a configuração: imagem, porta, variáveis de ambiente e volume de dados. Você pode versioná-lo, copiá-lo para outra máquina ou relê-lo daqui a seis meses para saber exatamente o que está em execução. Em uma instalação npm, essas informações ficam dispersas entre o sistema, o perfil do usuário e o gerenciador de serviços.

O que este guia abrange

Instalação local ou em um servidor pequeno, persistência dos dados, chave de criptografia, backup, atualização, acesso HTTPS.

O que ele não aborda

Os nodes de IA do n8n, a conexão com Ollama, o servidor MCP e a escalabilidade no modo de fila. Os dois primeiros pontos têm seu próprio guia, indicado no final do artigo.

O que não afirmamos

Nenhuma duração de instalação, nenhum consumo medido, nenhum número de versão fixado. Esses valores mudam de uma release para outra e devem ser consultados nas fontes oficiais no momento da instalação.

#Licença e limitações da edição comunitária

O n8n não está sob uma licença open source no sentido da OSI. O código é publicado sob a Sustainable Use License, um modelo que o editor chama de « fair-code ». Em linhas gerais, você pode usar, modificar e hospedar o n8n livremente para suas necessidades internas, pessoais ou da sua empresa. O que é restrito é a revenda: oferecer o n8n como serviço hospedado a terceiros ou integrá-lo a um produto comercial exige um acordo com o editor. O texto completo e sua FAQ estão em docs.n8n.io/sustainable-use-license/; leia-os se seu uso ultrapassar a automação interna.

A versão que você instala com Docker é a edição comunitária. Ela inclui o editor completo, centenas de nodes de integração, webhooks, gatilhos programados, nodes de IA e gerenciamento de usuários. Alguns recursos são reservados aos planos pagos auto-hospedados: autenticação única (SSO), ambientes com sincronização Git, segredos externos, envio de logs para uma ferramenta externa e parte dos recursos de colaboração. O editor também oferece uma chave gratuita chamada « comunidade registrada », obtida ao informar um endereço de e-mail nas configurações, que desbloqueia alguns recursos adicionais. A lista exata evolui: a página docs.n8n.io/hosting/community-edition-features/ é a referência oficial.

#Pré-requisitos

Docker e Docker Compose

Docker Engine com o plugin Compose no Linux ou Docker Desktop no Windows e no macOS. Verifique com docker compose version: o comando deve responder com um número de versão, em duas palavras (docker compose), e não com o hífen da ferramenta antiga.

Uma máquina que permaneça ligada

O n8n executa seus workflows no horário programado ou ao receber um webhook. Um PC que é desligado à noite não verá as execuções programadas para a madrugada. Um mini-PC, um NAS compatível com Docker ou uma pequena VPS são suficientes; as necessidades de memória continuam modestas para alguns workflows simples.

Uma porta livre

O n8n escuta na porta 5678 dentro do contêiner. Nós a publicamos com o mesmo número no host; altere-o se outro serviço já a estiver usando.

Somente para a etapa de HTTPS

Um nome de domínio apontando para a máquina e as portas 80 e 443 acessíveis pela Internet. Sem isso, permaneça no acesso local ou use uma VPN: a seção HTTPS detalha as duas opções.

docker --version
docker compose version

#Instalar o n8n com Docker Compose passo a passo

A documentação do n8n apresenta primeiro um comando docker run em uma linha, útil para um teste. Nós passamos diretamente ao Compose: o arquivo é apenas um pouco mais longo e se torna a referência da sua instalação. Todos os valores abaixo são os documentados pelo n8n; somente os valores de fuso horário e de porta são escolhas deste guia.

1. 01
   Criar a pasta do projeto

   Uma pasta dedicada contém o arquivo Compose, o arquivo .env e, mais tarde, seus backups. Os próprios dados do n8n ficarão em um volume Docker nomeado, não nessa pasta.
2. 02
   Gerar a chave de criptografia

   Antes da primeira inicialização, gere uma chave aleatória e coloque-a no arquivo .env. A seção seguinte explica por que essa ordem é importante.
3. 03
   Escrever o docker-compose.yml

   Copie o arquivo abaixo. Ele publica o n8n na porta 5678 da máquina, limitado ao endereço local 127.0.0.1, e monta o volume n8n_data na pasta /home/node/.n8n do contêiner, que é o local onde o n8n armazena seu banco SQLite, sua configuração e seus arquivos.
4. 04
   Começar

   docker compose up -d télécharge l'image et lance le conteneur en arrière-plan. La première exécution prend le temps du téléchargement de l'image; les suivantes sont immédiates.
5. 05
   Criar a conta proprietária

   Abra http://localhost:5678 em um navegador. O n8n solicita a criação da primeira conta, que se torna a proprietária da instância. Desde a versão 1.0, é essa conta que protege o acesso; a antiga autenticação básica por variáveis de ambiente não existe mais.

mkdir -p ~/n8n && cd ~/n8n

# Clé de chiffrement : 64 caractères hexadécimaux
echo "N8N_ENCRYPTION_KEY=$(openssl rand -hex 32)" > .env
chmod 600 .env
cat .env

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - GENERIC_TIMEZONE=Europe/Paris
      - TZ=Europe/Paris
      - N8N_RUNNERS_ENABLED=true
      - N8N_DIAGNOSTICS_ENABLED=false
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=336
    volumes:
      - n8n_data:/home/node/.n8n
      - ./local-files:/files

volumes:
  n8n_data:

docker compose up -d
docker compose logs -f n8n   # Ctrl+C pour quitter les journaux

Algumas explicações sobre as variáveis. GENERIC_TIMEZONE define o fuso horário usado pelo node Schedule Trigger e pelas expressões de data; TZ alinha o relógio do sistema dentro do contêiner. N8N_RUNNERS_ENABLED ativa os task runners, o mecanismo que executa o código dos nodes Code em um processo separado; a documentação recomenda seu uso, e as versões recentes exibem um aviso quando ele está ausente. N8N_DIAGNOSTICS_ENABLED=false interrompe o envio de dados de telemetria ao editor. As duas variáveis EXECUTIONS_DATA_* pedem ao n8n que limpe o histórico de execuções com mais de 336 horas, ou seja, quatorze dias, para evitar que o banco de dados cresça indefinidamente.

A montagem ./local-files:/files é opcional. Ela fornece ao n8n uma pasta compartilhada com a máquina host, útil para os nodes que leem ou gravam arquivos. Remova a linha se não precisar dela.

#A chave de criptografia: a variável que você não pode perder

O n8n criptografa todas as credenciais que você salva na interface, ou seja, tokens de API, senhas e chaves OAuth das suas integrações. A chave de criptografia usada é N8N_ENCRYPTION_KEY. Se você não a definir, o n8n gerará uma na primeira inicialização e a gravará no arquivo config da pasta /home/node/.n8n, portanto dentro do volume. Isso funciona, mas a chave ficará apenas nesse volume: se você o perder ou recriar a instância sem ele, cada credencial se tornará ilegível e precisará ser inserida novamente.

É por isso que este guia define a chave no arquivo .env antes do primeiro lançamento. Ela permanece sob seu controle, é armazenada com o arquivo Compose e permite restaurar o banco de dados em outra máquina sem perder as credenciais. Disso resultam duas regras.

Nunca altere a chave depois

Uma chave diferente daquela usada para criptografar torna todos os identificadores existentes inutilizáveis. Se precisar substituí-la, primeiro exporte seus identificadores descriptografados com o comando export:credentials e depois importe-os novamente após a alteração.

Faça um backup separado do arquivo .env

Guarde uma cópia da chave no seu gerenciador de senhas. Um backup do volume sem a chave não serve para as credenciais, mesmo que os workflows continuem legíveis.

#Persistência e backup dos dados

Tudo o que o n8n precisa preservar fica em /home/node/.n8n: o banco SQLite que contém workflows, credenciais criptografadas e histórico das execuções, o arquivo config, os nodes comunitários instalados e os arquivos binários no modo de armazenamento em disco. O volume nomeado n8n_data sobrevive ao docker compose down e à remoção do contêiner. Ele não sobrevive ao docker compose down -v nem a docker volume rm: esses dois comandos apagam os dados.

Para um backup, duas abordagens se complementam. A primeira arquiva o volume inteiro: paramos o n8n durante a cópia dos arquivos para evitar capturar um banco SQLite em processo de gravação. A segunda usa a ferramenta de linha de comando do n8n para exportar os workflows e as credenciais em JSON, legíveis e reimportáveis individualmente.

cd ~/n8n
mkdir -p backups
docker compose stop n8n
docker run --rm \
  -v n8n_data:/data:ro \
  -v "$PWD/backups":/backup \
  alpine tar czf "/backup/n8n_data-$(date +%F).tgz" -C /data .
docker compose start n8n
ls -lh backups/

# Un fichier par workflow, puis un par identifiant, dans le volume
docker exec n8n n8n export:workflow --backup --output=/home/node/.n8n/exports/workflows/
docker exec n8n n8n export:credentials --backup --output=/home/node/.n8n/exports/credentials/

# Récupérer les exports sur la machine hôte
docker cp n8n:/home/node/.n8n/exports ./backups/exports-$(date +%F)

A opção --backup dos comandos de exportação reúne as opções que produzem um arquivo por item, em formato legível. Os identificadores exportados continuam criptografados com sua chave, a menos que você adicione --decrypted; nesse caso, trate o arquivo como um segredo. Para restaurar, os comandos import:workflow e import:credentials aceitam a mesma pasta com a opção --separate. A referência completa da CLI está em docs.n8n.io/hosting/cli-commands/.

Para uma restauração completa em outra máquina: recrie a pasta com o mesmo docker-compose.yml e o mesmo .env, crie o volume vazio com docker compose up -d e depois docker compose stop, descompacte o arquivo no volume usando o comando inverso ao do backup e reinicie. A mesma chave de criptografia é necessária para recuperar as credenciais.

#Atualizar o n8n sem quebrar a instância

O n8n publica versões frequentes. A tag latest da imagem aponta para a versão estável mais recente, a tag next para a versão de teste; as tags numeradas permitem fixar uma versão específica. Com o Compose, a atualização requer três comandos: obter a nova imagem, parar o contêiner antigo e recriar um com a mesma configuração. Os dados permanecem no volume e não são tocados. As migrações do esquema do banco de dados, quando existem, são feitas automaticamente na inicialização.

cd ~/n8n

# 1. Sauvegarde avant toute mise à jour (voir section précédente)

# 2. Mise à jour
docker compose pull
docker compose down
docker compose up -d

# 3. Contrôle
docker compose logs --tail=50 n8n
docker exec n8n n8n --version

Três precauções evitam a maior parte das surpresas desagradáveis. Faça um backup antes: não é possível desfazer uma migração de banco de dados. Leia as notas de versão em github.com/n8n-io/n8n/releases e a página de atualização da documentação, docs.n8n.io/hosting/installation/updating/: as versões principais removem variáveis de ambiente ou alteram comportamentos padrão, e a documentação mantém uma página dedicada às mudanças incompatíveis. Por fim, se a instância for importante para você, prefira uma tag numerada a latest: você escolhe o momento da atualização em vez de sofrer com ela no próximo pull.

services:
  n8n:
    # Remplacez par un numéro lu sur la page des releases
    image: docker.n8n.io/n8nio/n8n:1.XX.Y

#Expor o n8n via HTTPS com cuidado

Enquanto você usar o n8n pela máquina que o hospeda ou pela sua rede local, a instalação anterior é suficiente. A necessidade de exposição surge com os webhooks: um serviço de terceiros que precisa chamar sua instância ou um acesso externo. Existem dois caminhos, e o primeiro costuma ser o mais adequado.

Uma VPN em vez de uma exposição

Tailscale, WireGuard ou a VPN do seu roteador permitem acessar o n8n de qualquer lugar sem abrir uma porta na Internet. Para uso pessoal sem webhook público, é a solução mais segura e simples. A instância continua em HTTP na rede privada, e N8N_SECURE_COOKIE=false se torna necessário se você acessá-la pelo endereço da VPN.

Um proxy reverso com certificado

Para receber webhooks públicos, é preciso ter um nome de domínio, um proxy reverso que encerre o TLS e um certificado. O exemplo oficial do n8n usa o Traefik; nós mostramos o Caddy, cuja configuração cabe em três linhas e que obtém sozinho os certificados do Let's Encrypt.

Na configuração abaixo, o n8n não publica mais nenhuma porta: apenas o Caddy fica acessível, nas portas 80 e 443, e encaminha as solicitações ao contêiner do n8n pela rede interna do Compose. As variáveis N8N_HOST, N8N_PROTOCOL e WEBHOOK_URL informam ao n8n o endereço público pelo qual ele é servido; sem elas, as URLs de webhook exibidas no editor apontariam para localhost e os redirecionamentos OAuth falhariam.

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    environment:
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_HOST=n8n.votre-domaine.fr
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://n8n.votre-domaine.fr/
      - GENERIC_TIMEZONE=Europe/Paris
      - TZ=Europe/Paris
      - N8N_RUNNERS_ENABLED=true
      - N8N_DIAGNOSTICS_ENABLED=false
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=336
    volumes:
      - n8n_data:/home/node/.n8n

  caddy:
    image: caddy:2
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

volumes:
  n8n_data:
  caddy_data:
  caddy_config:

n8n.votre-domaine.fr {
    reverse_proxy n8n:5678
}

Antes de executar docker compose up -d, o registro DNS de n8n.votre-domaine.fr deve apontar para o endereço público da máquina, e as portas 80 e 443 devem ser redirecionadas para ela. O Caddy então solicita um certificado ao Let's Encrypt e o renova sem intervenção. Os volumes caddy_data e caddy_config preservam os certificados e o estado entre as reinicializações.

#Solução de problemas: os bloqueios mais comuns

Mensagem sobre o cookie seguro na abertura

Você acessa o n8n por HTTP usando um endereço que não é localhost. Ou você passa para HTTPS, ou adiciona N8N_SECURE_COOKIE=false, somente em uma rede privada.

Erro de permissão em /home/node/.n8n

O contêiner é executado com o usuário node, e não como root. Isso acontece quando o volume nomeado é substituído por uma pasta do host cujas permissões não correspondem. Mantenha o volume nomeado ou ajuste o proprietário da pasta para o identificador de usuário 1000, o mesmo do node na imagem.

Os workflows agendados são executados no horário errado

GENERIC_TIMEZONE está ausente ou escrita incorretamente. O valor esperado é um nome de fuso horário IANA, como Europe/Paris. Cada workflow também pode definir seu próprio fuso horário nas configurações.

Os webhooks exibem um endereço localhost

WEBHOOK_URL não está definido ou não corresponde ao endereço pelo qual o serviço de terceiros acessa você. O valor deve terminar com uma barra e incluir o protocolo.

O banco de dados cresce sem parar

A limpeza das execuções está desativada ou demora demais. Verifique EXECUTIONS_DATA_PRUNE e EXECUTIONS_DATA_MAX_AGE e lembre-se também da opção que mantém os dados das execuções bem-sucedidas, que pode ser desativada fluxo a fluxo.

Após uma atualização, o n8n se recusa a iniciar

Leia o log com docker compose logs n8n: a mensagem geralmente indica uma variável removida ou uma migração que falhou. Compare com as notas da versão e restaure o backup, se necessário.

O n8n não consegue ver Ollama na mesma máquina

A partir de um contêiner, localhost designa o próprio contêiner, não o host. O endereço a ser usado depende do sistema e da forma como Ollama é executado; esse é o objetivo do guia sobre n8n e Ollama citado abaixo.

docker compose ps                     # état du conteneur
docker compose logs --tail=100 n8n   # dernières lignes du journal
docker exec n8n n8n --version         # version installée
docker volume inspect n8n_n8n_data    # emplacement réel du volume (préfixe = nom du dossier)
docker compose restart n8n            # redémarrage simple

Para perguntas que não encontram resposta na documentação, o fórum community.n8n.io é ativo e o editor responde nele. Informe a versão exata, o modo de instalação e as linhas do log: essas são as três primeiras coisas solicitadas.

#Para se aprofundar

A instância está instalada, com backup e atualizada. O próximo passo lógico é conectá-la a um modelo local e depois integrá-la a uma stack mais ampla. Fontes oficiais consultadas para este guia: a seção de hospedagem da documentação do n8n (docs.n8n.io/hosting/), a página de instalação do Docker (docs.n8n.io/hosting/installation/docker/), a página sobre atualização, a página sobre a licença e a página sobre os recursos da edição comunitária. Essas páginas evoluem com as versões: em caso de divergência com este guia, elas têm precedência.

n8n + Ollama: automatizar com uma IA 100 % local

O guia que dá continuidade: nodes de IA, conexão com Ollama a partir do contêiner, primeiros workflows de tradução e resumo. https://quelllm.fr/guide/n8n-ollama-automatisation-workflow

Ollama com Docker

Se você também quiser executar Ollama em um contêiner, ao lado do n8n, com acesso à GPU. https://quelllm.fr/guide/ollama-docker-installation-guide

Implantar um LLM em produção com Docker Compose

A stack completa Ollama, Open WebUI, Qdrant, n8n e Traefik em um único arquivo Compose, para ir além da instância isolada. https://quelllm.fr/guide/deployer-llm-docker-compose-production

Proteger seu servidor Ollama

Autenticação, firewall, proxy reverso: as regras de exposição valem para todo serviço hospedado por conta própria, inclusive o n8n. https://quelllm.fr/guide/securiser-serveur-ollama