Como hospedar o n8n (automação com IA)

O n8n é uma ferramenta de automação: você liga serviços (e-mail, planilhas, APIs, modelos de IA) em workflows visuais. Na nuvem oficial do n8n, você só usa a ferramenta. Em self-hosting, você roda o servidor e passa a cuidar de disponibilidade, URL, banco e atualizações.

Um workflow que começa por um webhook ou por um agendamento só dispara se o servidor estiver ligado o tempo todo. Por isso rodar o n8n no seu notebook serve para testar, mas não para produção. Confira na documentação oficial as versões suportadas e os nomes das variáveis antes de instalar, porque eles mudam entre versões do n8n.

O que preciso para hospedar o n8n?#

Quatro coisas:

• Um processo sempre ligado, para que webhooks e agendamentos disparem.
• Uma URL pública com HTTPS, porque serviços externos precisam alcançar os webhooks.
• Dados persistentes: a pasta .n8n guarda a chave de criptografia e, por padrão, o banco SQLite.
• Uma chave de criptografia fixa (N8N_ENCRYPTION_KEY) que você controla.

Docker ou npm?#

A documentação do n8n traz as duas formas. O Docker usa a imagem n8nio/n8n, a porta 5678 e um volume montado em /home/node/.n8n:

docker volume create n8n_data

docker run -d --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="America/Sao_Paulo" \
  -e TZ="America/Sao_Paulo" \
  -e N8N_ENCRYPTION_KEY="troque-por-uma-chave-longa-e-aleatoria" \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

A própria página de Docker aponta o Docker Compose como a forma de instalação recomendada, e a instalação por npm aparece como descontinuada. Se o seu servidor não roda Docker, o npm ainda funciona e exige uma versão do Node.js dentro da faixa que a documentação indica:

npm install n8n -g
n8n start

Nos dois casos, abra http://localhost:5678 para criar a conta de dono na primeira execução.

Como configurar a URL pública?#

Atrás de um proxy reverso, o n8n escuta na porta 5678 por dentro, mas o público acessa pela 443. Sem configuração, ele monta URLs de webhook erradas. Segundo a documentação, defina:

N8N_HOST=n8n.seudominio.com
N8N_PROTOCOL=https
N8N_WEBHOOK_URL=https://n8n.seudominio.com/
N8N_PROXY_HOPS=1

N8N_WEBHOOK_URL substitui a antiga WEBHOOK_URL, descontinuada desde o n8n 2.35.0. O último proxy do caminho precisa repassar os cabeçalhos X-Forwarded-For, X-Forwarded-Host e X-Forwarded-Proto. Todas essas opções são variáveis de ambiente: mantenha-as fora do código.

Qual banco de dados usar?#

O padrão é o SQLite, num arquivo database.sqlite dentro de ~/.n8n. Ele serve para começar, mas credenciais, execuções e workflows ficam num arquivo só, preso ao disco do servidor.

Para produção, use PostgreSQL:

DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=seu-host
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=seu-usuario
DB_POSTGRESDB_PASSWORD=sua-senha

Se o servidor do banco exige TLS com certificado de cliente, ative o SSL e aponte os arquivos do certificado. Cada variável aceita o sufixo _FILE, que lê o valor de um arquivo:

DB_POSTGRESDB_SSL_ENABLED=true
DB_POSTGRESDB_SSL_CA_FILE=/caminho/ca.crt
DB_POSTGRESDB_SSL_CERT_FILE=/caminho/certificado.pem
DB_POSTGRESDB_SSL_KEY_FILE=/caminho/chave.key

A documentação do n8n lista as versões de PostgreSQL suportadas: confira se a do seu banco está nela. Mesmo com PostgreSQL, a pasta .n8n continua guardando a chave de criptografia e os logs, então ela também precisa ser persistente. Veja como hospedar um banco de dados e como hospedar um app Node.js.

Por que fixar a N8N_ENCRYPTION_KEY?#

O n8n criptografa as credenciais dos seus workflows (chaves de API, senhas) com uma chave. Se você não definir uma, ele gera uma aleatória na primeira execução e a salva em ~/.n8n. Se esse disco for recriado, a chave some e as credenciais gravadas no banco ficam ilegíveis. Defina N8N_ENCRYPTION_KEY você mesmo e guarde uma cópia num cofre de senhas. Nunca coloque a chave no repositório.

Como verificar que deu certo?#

1. Abra a URL pública: a tela de criação de conta (ou de login) deve carregar por HTTPS.
2. Crie um workflow com o nó Webhook, ative-o e confira se a URL mostrada no editor usa o seu domínio, não localhost.
3. Chame essa URL com curl e veja a execução aparecer na lista de execuções.
4. Reinicie o servidor e confirme que workflows e credenciais continuam lá. Se sumirem, a pasta .n8n não está persistente.

Quais erros são comuns?#

• Webhook com URL localhost no editor: faltou N8N_WEBHOOK_URL (ou N8N_HOST e N8N_PROTOCOL).
• Credenciais inválidas após reinício: a chave de criptografia mudou. Restaure a original em N8N_ENCRYPTION_KEY.
• Workflows agendados com horário errado: defina GENERIC_TIMEZONE e TZ.
• Perda de dados ao recriar o contêiner: o volume de /home/node/.n8n não foi montado.
• Uso comercial sem ler a licença: o n8n self-hosted usa a licença de uso sustentável, que tem limites. Confira em LICENSE.md antes de revender ou embutir em um produto.

Como fazer isso na Square Cloud#

O n8n é um aplicativo Node.js, e na Square Cloud ele roda como qualquer API ou serviço HTTP: num container sempre ligado, sem modo de suspensão, então webhooks e agendamentos disparam a qualquer hora.

1. Adicione n8n como dependência no package.json. Não há etapa de build: no start, a plataforma roda npm install quando não existe node_modules.
2. Use N8N_PORT=$PORT npx n8n start como comando de início (START) e defina N8N_LISTEN_ADDRESS=0.0.0.0, porque a aplicação web precisa escutar em 0.0.0.0, na porta da variável PORT.
3. Nas variáveis de ambiente, coloque N8N_ENCRYPTION_KEY, as variáveis de banco, N8N_HOST com o subdomínio HTTPS *.squareweb.app da aplicação, N8N_PROTOCOL=https e N8N_WEBHOOK_URL.
4. Faça o deploy por ZIP, CLI ou GitHub.

A RAM do plano é um pool compartilhado, com mínimo de 512 MB por aplicação web. Acompanhe o n8n nas métricas: se ele estourar a memória, a aplicação para até você aumentar a RAM e iniciá-la de novo.

O disco da aplicação persiste entre restarts e deploys: aponte N8N_USER_FOLDER para uma pasta do projeto e deixe a pasta .n8n fora do ZIP, porque um commit sobrescreve os arquivos que estão nele. Para produção, a hospedagem de PostgreSQL começa no Standard (a partir de R$ 44,99 por mês), com snapshot automático diário do banco. A conexão exige TLS: envie com o projeto o certificado baixado no painel e aponte para ele as variáveis DB_POSTGRESDB_SSL_*_FILE.

O Standard também dá acesso ao AI Gateway, uma API compatível com a OpenAI para o modelo cubic, em beta e sem custo extra durante o beta. No n8n, use o nó HTTP Request com POST https://api.squarecloud.app/v2/ai/chat/completions, a chave de API da conta (escopo ai:chat) no cabeçalho Authorization e "model": "cubic" no corpo. Nesse plano, são até 2,5M tokens e até 1.000 requisições por dia, uma de cada vez; os limites podem mudar quando o beta acabar.