O que é o Easy Setup

Em 7 capítulos, do "comprei a VPS" ao "N8N funcionando". Não precisa saber programar. Tudo é menu numerado, copia-e-cola.

O que vamos fazer aqui

O easy-setup.sh é um script que automatiza a instalação de várias ferramentas dentro de uma VPS (um computador alugado na nuvem). Em vez de digitar dezenas de comandos, você só responde a um menu numerado.

No final, você vai ter rodando:

• N8N — automação de tarefas (tipo Zapier, mas seu)
• PostgreSQL + Redis — banco de dados e fila, que o N8N precisa pra funcionar
• Stirling PDF — manipulação de PDFs (juntar, separar, OCR)
• pgAdmin + pgBackWeb — interface e backups do banco
• Portainer — painel pra ver tudo o que está rodando
• Cloudflare Tunnel — domínio bonito (n8n.seusite.com) em vez de IP:porta

Antes de começar

Você só precisa de:

• Um cartão de crédito (pra contratar a VPS — ~R$ 40/mês)
• Um computador com internet
• Cerca de 1h–1h30 livres (pode pausar a qualquer momento)
• Um gerenciador de senhas — recomendamos Bitwarden (grátis)

Linha do tempo

O manual está dividido em 7 etapas. Cada uma tem o seu tempo estimado:

Convenções deste manual

Pra facilitar a leitura, alguns elementos têm sempre o mesmo significado:

Rodando o easy-setup.sh

Dois comandos: um pra baixar, outro pra rodar. Em 30 segundos você vê o menu na tela.

Passo a passo

1. Confirme que você está logado como root

   No prompt do SSH, o final da linha deve mostrar # (cerquilha), e não $ (cifrão). Isso confirma que você é o root — o "dono" do servidor, que pode instalar qualquer coisa.

   root@srv-01:~# _
2. Baixe o script

   Copie o comando abaixo (botão à direita) e cole no terminal. Esse comando puxa o arquivo do GitHub e salva como easy-setup.sh na pasta atual.

   bash · baixar

   Copiar

   $curl -fsSL https://raw.githubusercontent.com/madeinlowcode/easy-setup/main/setup-mlc.sh -o easy-setup.sh

3. Rode o script

   Agora execute. Você vai precisar digitar a senha do root mais uma vez (o sudo pede pra confirmar).

   bash · executar

   Copiar

   $ sudo bash easy-setup.sh

4. Veja o menu aparecer

   Depois de uns 5 segundos, a tela do terminal vai limpar e mostrar algo parecido com isso:

   ══════════════ EASY SETUP · v1.0 ══════════════

   Selecione uma opção e pressione ENTER: A) Preparo completo do servidor (recomendado pra começar) 1) Atualizar sistema 2) Configurar hostname 3) Configurar timezone 4) Instalar Docker 5) Inicializar Docker Swarm 6) Criar rede overlay 7) Instalar Traefik 8) Instalar Cloudflare Tunnel 9) Instalar Portainer 10) Resetar Portainer 11) Instalar stacks → 0) Sair Sua opção: _

Entendendo o menu

Você digita o número da opção e pressiona ENTER. Por exemplo, pra começar do zero, digite A e ENTER — isso roda as opções 1 a 9 em sequência.

Como saber se deu certo

Problemas que podem aparecer

"sudo: command not found"

Seu Ubuntu não tem o sudo instalado (raro, mas acontece em imagens minimalistas). Como você já é root, ignore o sudo:

# bash easy-setup.sh

"Permission denied"

Provavelmente você não está logado como root. Volte ao capítulo 03 e confirme que o prompt termina em #.

"curl: command not found"

Instale o curl e tente de novo:

# apt update && apt install -y curl

PostgreSQL — Banco de dados do N8N

O lugar onde o N8N guarda seus workflows, credenciais e histórico. A primeira stack que você precisa instalar — sem ela, nada do N8N funciona.

O que é

PostgreSQL é um banco de dados — o lugar onde o N8N guarda seus workflows, credenciais e histórico de execuções. Sem ele, o N8N não funciona.

A versão que o script instala já vem com a extensão pgvector, que serve pra busca por similaridade (útil pra projetos de IA / embeddings).

Quando instalar

Primeiro de tudo, antes de qualquer outra coisa relacionada ao N8N.

• Já fez o preparo do servidor? (capítulos 1 a 5 do guia)
• Está no menu principal do script?

Se sim, escolha opção 11 → opção 1.

O que você vai precisar

Passo a passo

1. Abra o menu de stacks
   No menu principal do script, digite 11 e pressione ENTER.
2. Escolha PostgreSQL

   Digite 1 e pressione ENTER. Você vai ver:

   ═══════════════════════════════════════════ STACK: PostgreSQL 16 + pgvector ═══════════════════════════════════════════
3. Defina a senha

   Quando aparecer Senha do PostgreSQL:

   • Pra ter uma senha forte: apenas pressione ENTER (o script gera uma)
   • Pra usar a sua: digite e pressione ENTER

   🔥

   ANOTE essa senha agora

   Você vai precisar dela ao instalar N8N Editor, Workers, Webhooks, MCP e pgBackWeb. Salve em um gerenciador de senhas (Bitwarden, 1Password) ou em um arquivo seguro.
4. Confirme o hostname
   Quando aparecer Hostname do nó manager, geralmente é só ENTER (usa o atual).
5. Aguarde o deploy
   O script vai baixar a imagem e fazer o deploy. Demora ~30 segundos.

Como saber se deu certo

Pra conferir manualmente, rode:

# docker service ls | grep postgres

Você deve ver algo como:

Se aparecer 0/1 em vez de 1/1, espere mais 1 minuto (a imagem ainda está sendo baixada).

Problemas comuns

"0/1" não vira "1/1" nem depois de 5 minutos

Algo deu errado no deploy. Rode:

# docker service ps postgres_postgres --no-trunc

Procure a coluna ERROR. As causas mais comuns:

• Pouco espaço em disco — rode df -h e veja se tem mais de 5 GB livre
• Pouca memória — rode free -m, precisa de pelo menos 1 GB livre

Esqueci a senha do Postgres

Ela está salva no servidor:

# cat /root/dados_vps/postgres/credenciais.txt

Próximo passo

Instale agora o Redis (opção 2 do menu). Sem ele, o N8N também não funciona.

N8N Editor

A interface principal do N8N — onde você desenha os fluxos de automação. Depende do Postgres e do Redis já instalados.

O que é

O N8N Editor é a "tela principal" do N8N — aquela interface visual onde você arrasta nós e conecta para montar automações. É o que você vai abrir no navegador depois.

O que você vai precisar

• Postgres instalado e rodando (1/1)
• Redis instalado e rodando (1/1)
• Senha do Postgres em mãos (do passo anterior)
• Domínio próprio (ex.: n8n.seusite.com) — opcional, pode usar IP

Passo a passo

1. Abra o menu de stacks e escolha N8N Editor
   No menu principal digite 11, depois 3.
2. Forneça a senha do Postgres
   Cole a senha que você anotou ao instalar o Postgres. Atenção: caracteres especiais ($, !, @) podem confundir. Se gerou a senha automaticamente, ela já é segura.
3. Anote a encryption key

   O script vai mostrar uma linha como:

   N8N_ENCRYPTION_KEY = a3f9c2e7b1d8f4a6c5e2b9d7f1a4c6e8

   Copie essa chave inteira e cole no seu gerenciador de senhas com a label N8N Encryption Key.

4. Defina o domínio (ou aceite o padrão)
   Se tem domínio: digite n8n.seusite.com. Se não tem: dê ENTER (vai usar IP:5678 mesmo).
5. Aguarde o deploy
   ~1 minuto. O N8N é maior que o Postgres, demora um pouco mais.

Primeiro acesso

Abra no navegador http://SEU-IP:5678 (ou https://n8n.seusite.com se configurou domínio). Você vai ver a tela de criar o primeiro usuário admin.

Como saber se deu certo

Próximo passo

Pra fluxos pesados: instale os N8N Workers. Pra receber webhooks externos: instale os N8N Webhooks.

Menu do script — referência completa

Tabela com todas as opções do easy-setup.sh: o que cada uma faz, quanto demora, e o que ela precisa pra funcionar.

Preparo do servidor

Stacks (opção 11)

Portas padrão

Arquivos importantes

Tudo que o script gera fica em /root/dados_vps/:

Portainer — primeiro acesso

O Portainer é o painel visual do Docker. É por ele que você vê o que está rodando, logs, e pode reiniciar serviços. Mas ele tem uma janela de 5 minutos pra criar o admin — leia isso primeiro.

Passo a passo

1. Confirme que o Portainer subiu
   No final da opção 9, o script mostra: ✅ Portainer disponível em http://SEU-IP:9000. Você tem 5 min a partir desse momento.
2. Abra o navegador no IP:9000

   No seu computador (não na VPS), abra Chrome/Firefox e digite:

   url

   Copiar

   → http://SEU-IP:9000

   Troque SEU-IP pelo IP que você anotou da Hostinger/Contabo/etc.

   ⚠️

   Aviso de "não seguro"?

   O navegador pode mostrar "conexão não privada" — isso é normal nessa fase. Clique em "Avançado" → "Continuar mesmo assim". O HTTPS vem depois, com o Cloudflare Tunnel.
3. Crie o usuário admin

   A tela vai pedir 3 coisas:

   • Username: sugerimos admin (ou seu nome, sem espaços)
   • Password: mínimo 12 caracteres — gere uma no Bitwarden
   • Confirm: a mesma senha

   📝

   Salve no gerenciador de senhas

   Label: Portainer · SEU-IP. Username e password. Você vai usar isso toda vez que entrar.
4. Escolha o ambiente
   Na tela seguinte, o Portainer pergunta o que você quer gerenciar. Clique em "Get Started" ou "Local" — ele detecta o Docker Swarm da própria VPS automaticamente.

Como saber se deu certo

Se passou dos 5 minutos

Acontece. Volte ao terminal SSH e rode opção 10 do menu. Em 20 segundos você tem mais 5 minutos. Aí é só repetir os passos acima.

Perguntas frequentes

As dúvidas que mais aparecem. Se a sua não estiver aqui, abra uma issue no GitHub.

Preciso saber programar pra usar isso?

Não. O manual inteiro é "copiar comando → colar no terminal → ENTER". Você não vai escrever uma linha de código sequer. Os comandos têm botão "Copiar" pra evitar erros de digitação.

Quanto custa uma VPS pra rodar tudo?

Entre R$ 30 e R$ 60 por mês, dependendo do provedor. Pra começar, qualquer VPS com 2 vCPU, 4 GB de RAM e 40 GB de disco serve. Hostinger e Contabo costumam ter as opções mais baratas no Brasil.

Posso instalar em um Raspberry Pi?

Tecnicamente sim, mas não recomendamos. O Pi tem pouca RAM pra rodar várias stacks ao mesmo tempo, e o cartão SD não aguenta bem o uso intenso de banco de dados (vai corromper em alguns meses). VPS é mais barata no longo prazo.

É seguro? Minhas senhas ficam protegidas?

O script segue boas práticas (firewall, senhas geradas aleatoriamente, sem portas desnecessárias expostas). Mas a segurança final depende de você: senha forte no SSH, gerenciador de senhas pros admins, e nunca compartilhe o arquivo /root/dados_vps/.

Preciso de domínio próprio?

Não pra começar — você pode usar http://SEU-IP:5678. Mas pra ter HTTPS bonito (https://n8n.seusite.com) e poder receber webhooks do mundo externo com segurança, sim. Cloudflare oferece domínios a partir de US$ 10/ano.

Funciona em Windows Server?

Não. O script é Linux-only (Ubuntu/Debian). Se você comprou Windows Server por engano, peça pra reinstalar com Ubuntu 22.04 — todos os provedores fazem isso de graça pelo painel.

Como atualizo o N8N pra uma versão mais nova?

Rode o script de novo: sudo bash easy-setup.sh → opção 11 → opção 3. Ele detecta que já existe e pergunta se quer atualizar. Seus workflows e dados ficam intactos (estão no Postgres, separado).

Posso rodar N8N de vários clientes na mesma VPS?

Não diretamente — o script é otimizado pra uma instalação por VPS. Pra atender múltiplos clientes, o ideal é uma VPS por cliente (mais simples e mais seguro).

Glossário

Termos técnicos que aparecem no manual, em ordem alfabética. Sempre com uma analogia pra ficar fácil de lembrar.

Container

Uma caixa isolada que roda um programa. Analogia: é como um apartamento dentro do prédio (servidor) — cada um tem suas coisas, mas dividem a estrutura. Se um pegar fogo, os outros não são afetados.

Docker

O programa que cria e gerencia os containers. Analogia: o porteiro do prédio que decide quem entra, quem sai, e qual andar cada um ocupa.

Encryption Key

Uma chave aleatória que o N8N usa pra criptografar as credenciais que você guarda nele (tokens, senhas de API). Crítico: se perder, perde tudo. Anote sempre.

Hostname

O "nome" do servidor. Igual nome de pessoa, mas pra computador. Ex.: srv-01, n8n-prod.

IP

O "endereço" do servidor na internet. Quatro números separados por ponto: 123.45.67.89. Quando você compra uma VPS, ela vem com um IP fixo.

Porta

Um "número de apartamento" dentro do servidor. O servidor (IP) é o prédio; a porta diz qual serviço atende. Ex.: porta 5678 é o N8N, porta 9000 é o Portainer.

SSH

"Secure Shell". O programa que você usa pra acessar o terminal da VPS pela internet, com segurança. Analogia: um portão automático com chave digital — você prova quem é (com senha ou chave) e entra.

Stack

Um conjunto de containers que trabalham juntos. Analogia: um time — o N8N tem 4 jogadores (Editor, Workers, Webhooks, MCP) que precisam estar todos em campo pra funcionar.

Swarm

Modo "cluster" do Docker — permite escalar e replicar containers. Pra quem usa esse script: está ativado por padrão, mas você nem precisa pensar nele. Só funciona.

Volume

Onde os dados ficam guardados pra não sumir quando o container reinicia. Analogia: o HD externo do apartamento — se você mudar de prédio (recriar o container), pode levar o HD junto.

VPS

"Virtual Private Server". Um computador alugado na nuvem. Analogia: apartamento alugado, mas pra rodar programas em vez de morar. Hostinger, Contabo, DigitalOcean são "imobiliárias" de VPS.

N8N não conecta no banco de dados

O N8N subiu, mas ao abrir SEU-IP:5678 aparece tela branca ou erro de conexão. Causa quase sempre é a senha do Postgres com caractere especial.

Sintomas

• Página SEU-IP:5678 não carrega ou mostra erro 502
• docker service ls mostra n8n_editor 0/1 (não fica 1/1)
• docker service logs n8n_editor mostra FATAL: password authentication failed

Causa provável

A senha do Postgres tem caracteres especiais ($, !, @, %) que confundem o N8N na hora de conectar. O Postgres aceita; o driver do N8N não escapa direito.

Solução

1. Veja a senha atual do Postgres
   bash

   Copiar

   # cat /root/dados_vps/postgres/credenciais.txt

   Se ela tem $, !, @, #, % ou &: é o problema.

2. Gere uma senha "limpa"

   Use só letras e números (mínimo 24 caracteres). Pode usar este comando pra gerar uma:

   bash · gerar senha

   Copiar

   # openssl rand -base64 32 | tr -dc 'a-zA-Z0-9' | head -c 32

3. Resete o Postgres com a nova senha
   🔥

   Atenção: vai apagar os dados do Postgres

   Se você já tinha workflows no N8N, faça backup antes (opção 11 → pgBackWeb → Export). Como o erro está acontecendo agora, provavelmente é uma instalação nova e não tem dados ainda.

   No menu do script: opção 11 → 1, e quando perguntar a senha, cole a nova senha limpa.

4. Reinstale o N8N Editor com a nova senha
   No menu: opção 11 → 3. Use a nova senha do Postgres quando perguntado. Mantenha a mesma N8N_ENCRYPTION_KEY de antes (se já tinha gerado).

Como prevenir no futuro

Quando o script perguntar a senha do Postgres pela primeira vez, aperte ENTER pra deixar ele gerar. As senhas auto-geradas pelo script são "limpas" (só letras e números) e nunca dão esse problema.

Comprando uma VPS

Qualquer provedor com Ubuntu 22.04, 2 GB de RAM e 40 GB de disco funciona. Contabo é a mais barata (~R$ 40/mês). Hostinger e DigitalOcean são boas opções com interface em português.

O que o servidor precisa ter

Provedores que funcionam bem

• Contabo — mais barata (CLOUD VPS 1: ~R$ 40/mês, 4 GB RAM). Interface em inglês.
• Hostinger — suporte em português, boa interface.
• DigitalOcean — simples de usar, Droplet 2 GB (~US$ 12/mês).
• Hetzner — ótimo custo-benefício (servidores na Europa).

Comprando na Contabo (passo a passo)

1. Acesse contabo.com e escolha o plano CLOUD VPS 1
   4 GB RAM, 100 GB SSD. É o mais barato que comporta o stack completo.
2. Selecione a região
   Se seu público é brasileiro, escolha Brazil (South America).
3. Sistema operacional: Ubuntu 22.04
   Na lista de imagens, selecione Ubuntu 22.04. Não selecione outra versão.
4. Defina a senha root

   Use uma senha forte e anote imediatamente. Você vai usar ela na próxima etapa pra entrar via SSH.

   📝

   Anote agora

   IP do servidor + senha root. Sem eles você não consegue entrar.
5. Conclua a compra
   O servidor fica pronto em 2–10 minutos. Você recebe o IP por e-mail ou no painel do provedor.

Como saber se está pronto

Acessando a VPS via SSH

SSH é o "controle remoto" da VPS — você digita comandos no seu computador e eles executam no servidor. É mais simples do que parece.

Qual programa usar

• Windows: PowerShell (já vem instalado) — recomendado.
• Mac/Linux: Terminal (já vem instalado).
• Celular: app Termius (iOS/Android, grátis).

Conectando

1. Abra o terminal
   Windows: Win + X → Windows PowerShell. Mac: Cmd + Espaço → "Terminal".
2. Digite o comando de conexão

   Substitua SEU-IP pelo IP da VPS:

   bash

   Copiar

   # ssh root@SEU-IP

3. Aceite a chave do servidor
   Na primeira conexão: Are you sure you want to continue connecting (yes/no)? — Digite yes e ENTER.
4. Digite a senha root
   Normal não aparecer nada enquanto digita — é medida de segurança. Cole a senha e pressione ENTER.

Como saber que entrou

Problemas comuns

Connection timed out

A VPS ainda não terminou de inicializar. Espere 2–5 minutos e tente de novo.

Permission denied (publickey,password)

Senha errada. Verifique no painel do provedor se ela foi definida corretamente.

Connection refused na porta 22

O servidor ainda está inicializando. Verifique se o status é "Running" no painel.

Preparo do servidor

A opção A do script faz tudo: instala Docker, configura Swarm, abre as portas e baixa as imagens. Você só espera ~12 minutos.

O que a opção A faz

A opção A roda os passos 1–9 em sequência:

1. Atualiza o sistema (apt update && upgrade)
2. Instala dependências básicas
3. Instala Docker Engine (versão estável)
4. Inicia o Docker Swarm no modo manager
5. Configura as redes Docker internas
6. Abre as portas no firewall (UFW): 22, 80, 443, 5678, 9000, etc.
7. Instala o Portainer
8. Cria a estrutura de diretórios em /root/dados_vps/
9. Exibe o resumo com IP e portas

Executando a opção A

1. No menu do script, pressione A
   Digite A (maiúsculo) e ENTER. Quando perguntar Confirmar? [s/N], digite s e ENTER.
2. Aguarde os ~12 minutos

   O terminal vai rolar bastante — isso é normal. Não feche a janela.

   ⚠️

   Não feche o terminal

   Se a conexão SSH cair no meio, é seguro rodar de novo — o script é idempotente.
3. Observe o resumo final
   Quando terminar, o script exibe uma tabela com IP e portas. Esse é o sinal de que deu certo.

Como saber se deu certo

Cloudflare Tunnel

Troca o IP:porta feio por um domínio bonito (n8n.seusite.com) com HTTPS automático. Sem abrir porta 80/443 no servidor.

Parte 1 — Criar o Tunnel no Cloudflare

1. Acesse o painel do Cloudflare
   Entre em one.dash.cloudflare.com → selecione sua conta → menu lateral: Networks > Tunnels.
2. Clique em "Create a tunnel"
   Escolha Cloudflared (não WARP Connector). Clique em Next.
3. Dê um nome ao tunnel
   Pode ser qualquer coisa, ex.: vps-mlc. Clique em Save Tunnel.
4. Copie o token

   O Cloudflare mostra um comando de instalação. O token é a parte longa após --token:

   cloudflared service install eyJhIjoiNDhkO...[muito longo]

   📝

   Anote o token

   Você vai colar no script agora. O script também salva em /root/dados_vps/cloudflare/tunnel_token.txt.

Parte 2 — Instalar o Tunnel no servidor

1. No menu do script, escolha a opção 8
   Digite 8 e ENTER. O script vai perguntar: Token do Cloudflare Tunnel:
2. Cole o token e aguarde
   Cole o token copiado e pressione ENTER. O script instala e inicia o cloudflared automaticamente. Deve mostrar ✅ Cloudflare Tunnel ativo.

Parte 3 — Configurar o domínio

1. No Cloudflare: Tunnels → seu tunnel → Public Hostnames
   Clique em Add a public hostname.
2. Configure o hostname do N8N
   • Subdomain: n8n
   • Domain: seusite.com
   • Service Type: HTTP
   • URL: SEU-IP:5678

   Para outros serviços, adicione mais hostnames (ex.: portainer.seusite.com → SEU-IP:9000).

3. Salve e teste
   Em até 2 minutos, https://n8n.seusite.com já deve funcionar com HTTPS.

Como saber se deu certo

Redis

Banco de dados em memória que o N8N usa como fila de tarefas. Sem ele, Workers e Webhooks não funcionam. Instalação rápida e sem perguntas difíceis.

O que é

Redis é um banco em memória (RAM). O N8N usa ele como fila: quando você dispara uma automação pesada, ela vai pra fila do Redis e os Workers pegam as tarefas de lá. Analogia: Redis é a "sala de espera" dos trabalhos.

Passo a passo

1. Acesse o menu de stacks
   No menu principal: 11 → ENTER → 2 → ENTER.
2. Aguarde o deploy
   Sem perguntas. O Redis é leve, demora ~20 segundos.

Como saber se deu certo

# docker service ls | grep redis

N8N Workers

Processos em segundo plano que executam os workflows sem travar a interface. Necessário pra fluxos pesados ou paralelos.

O que é

O N8N Worker executa os workflows em segundo plano. Analogia: o Editor é o gerente que aceita tarefas; os Workers são os funcionários que realmente fazem o trabalho. Sem Workers, o próprio Editor precisa fazer tudo, deixando a interface lenta.

O que você vai precisar

• N8N Editor instalado e rodando
• A N8N_ENCRYPTION_KEY que você anotou na instalação do Editor
• Senha do Postgres

Passo a passo

1. Acesse o menu 11 → 4
   No menu principal: 11 → ENTER → 4 → ENTER.
2. Informe senha do Postgres e Encryption Key

   Os mesmos valores usados no N8N Editor. A chave precisa ser idêntica.

   🔥

   Chave tem que ser a mesma

   Encryption Key diferente faz o Worker falhar silenciosamente e corrompe as credenciais das suas integrações.
3. Aguarde o deploy
   ~30 segundos.

Como saber se deu certo

N8N Webhooks

Processo dedicado a receber chamadas externas. Roda na porta 5679, separado do Editor, pra não derrubar a interface quando receber muitas chamadas.

O que é

Quando Stripe, WhatsApp, GitHub, etc. chamam seu N8N, a chamada vai para o processo de Webhooks, não pro Editor. Isso evita que tráfego de entrada trave a interface que você usa pra editar fluxos.

O que você vai precisar

• N8N Editor instalado
• Redis instalado
• A mesma N8N_ENCRYPTION_KEY
• Senha do Postgres

Passo a passo

1. Acesse menu 11 → 5
   Digite 11 → ENTER → 5 → ENTER.
2. Informe Postgres, Encryption Key e URL base
   Mesmos valores do Editor. Na URL base: se tem domínio, coloque https://n8n.seusite.com. Se não, deixe o padrão com o IP.
3. Aguarde o deploy
   ~30 segundos.

Como saber se deu certo

N8N MCP

Servidor MCP (Model Context Protocol) do N8N — permite que IAs como Claude controlem seus workflows diretamente. Opcional, mas poderoso.

O que é

O MCP Server expõe seus workflows do N8N como "ferramentas" que uma IA pode chamar. Exemplo: você diz ao Claude "execute o workflow de relatório semanal" e ele chama diretamente via MCP, sem você precisar clicar em nada.

O que você vai precisar

• N8N Editor instalado e com usuário criado
• A mesma N8N_ENCRYPTION_KEY
• Senha do Postgres

Passo a passo

1. Acesse menu 11 → 6
   Digite 11 → ENTER → 6 → ENTER.
2. Informe os dados solicitados
   Senha do Postgres, Encryption Key e URL do N8N (ex.: https://n8n.seusite.com).
3. Aguarde o deploy
   ~30 segundos. O MCP fica disponível em SEU-IP:5680.

Como saber se deu certo

Stirling PDF

Ferramenta local pra manipular PDFs: juntar, separar, comprimir, OCR, converter. Roda na porta 8080. Seus documentos nunca saem da sua VPS.

O que é

Stirling PDF é um app web de código aberto pra processar PDFs no seu próprio servidor. Analogia: é como ter o iLovePDF instalado na sua máquina, sem enviar nada pra nuvem.

Passo a passo

1. Acesse menu 11 → 7
   Digite 11 → ENTER → 7 → ENTER. Sem perguntas adicionais.
2. Aguarde o download da imagem
   A imagem é maior (~600 MB). Pode demorar 1–2 minutos na primeira instalação.

Como saber se deu certo

pgAdmin

Interface visual pra gerenciar o PostgreSQL. Roda na porta 5050. Use pra ver tabelas, rodar queries SQL e monitorar o banco sem precisar da linha de comando.

O que é

pgAdmin é a ferramenta oficial de gestão do PostgreSQL. Você acessa pelo navegador, conecta no Postgres da sua VPS e consegue ver todas as tabelas que o N8N criou, rodar queries e criar backups manuais.

O que você vai precisar

• PostgreSQL instalado e rodando
• Senha do PostgreSQL em mãos

Passo a passo

1. Acesse menu 11 → 8
   Digite 11 → ENTER → 8 → ENTER.
2. Defina e-mail e senha do pgAdmin
   Pode ser qualquer e-mail (ex.: admin@local.com). A senha é só pra entrar na interface web. Anote.
3. Aguarde o deploy
   ~1 minuto (a imagem é um pouco pesada).
4. Conecte o pgAdmin ao Postgres

   Acesse http://SEU-IP:5050, faça login. Depois: Add New Server:

   • Name: VPS Postgres
   • Host: postgres (nome do serviço Docker interno)
   • Port: 5432
   • Username: postgres
   • Password: senha do Postgres que você anotou

Como saber se deu certo

pgBackWeb

Interface web pra agendar e gerenciar backups automáticos do PostgreSQL. Roda na porta 8085. Configure uma vez e esqueça — ele faz backup sozinho.

O que é

pgBackWeb cria backups do Postgres com agendamento automático. Você define "backup todo dia às 3h" e ele faz, salvando o arquivo dentro da VPS. Você pode baixar quando quiser.

O que você vai precisar

• PostgreSQL instalado e rodando
• Senha do PostgreSQL

Passo a passo

1. Acesse menu 11 → 9
   Digite 11 → ENTER → 9 → ENTER.
2. Informe a senha do Postgres
   Mesma senha usada no N8N e pgAdmin.
3. Aguarde e configure o agendamento

   Acesse http://SEU-IP:8085 → Databases → Add Database:

   • Host: postgres
   • Port: 5432
   • Username: postgres
   • Password: senha do Postgres

   Depois em Backups → Add Backup, configure o horário desejado.

Como saber se deu certo

Portas padrão

Todas as portas usadas pelo script. Guia rápido pra saber qual URL acessar em cada serviço.

Tabela de portas

Verificar portas abertas no firewall

# ufw status numbered

Você deve ver 22, 80, 443, 5050, 5678, 5679, 8080, 8085, 9000 listados como ALLOW.

Comandos úteis

Os comandos mais usados do dia a dia: verificar serviços, ver logs, reiniciar stacks. Cole direto no terminal da VPS.

Listar serviços Docker

# docker service ls

A coluna REPLICAS deve mostrar 1/1 pra cada serviço.

Ver logs de um serviço

# docker service logs NOME-DO-SERVICO --tail 50

Nomes: n8n_editor, postgres_postgres, redis_redis, portainer_portainer.

Forçar reinício de um serviço

# docker service update --force NOME-DO-SERVICO

Uso de recursos

# free -m && df -h

free -m mostra RAM livre. df -h mostra disco. Se o disco estiver acima de 85%, libere espaço.

Ler credenciais salvas

# cat /root/dados_vps/postgres/credenciais.txt

Rodar o script de novo

# sudo bash <(curl -fsSL https://raw.githubusercontent.com/madeinlowcode/easy-setup/main/setup-mlc.sh)

Portainer timeout

O Portainer travou antes de você criar o usuário admin. Acontece porque ele tem uma janela de 5 minutos de segurança. A solução é rápida.

Sintomas

• Acessar http://SEU-IP:9000 mostra "Portainer timeout" ou loop de carregamento
• A página de criação de usuário admin não aparece mais

Por que acontece

O Portainer tem um timer de 5 minutos após a primeira inicialização. Se você não criar o usuário admin nesse prazo, ele "trava" por segurança pra evitar que alguém na internet crie o admin sem ser você.

Solução

1. Rode o script e escolha a opção 10
   No menu principal: 10 → ENTER. Essa opção reinicia o Portainer e zera o timer.
2. Acesse o Portainer imediatamente
   Abra http://SEU-IP:9000 no navegador o mais rápido possível após o reinício.
3. Crie o usuário admin

   Defina username e senha forte. Anote no gerenciador de senhas.

   ⚠️

   Você tem 5 minutos de novo

   O timer reinicia. Vá direto criar o usuário, não dê voltas.

Como saber se deu certo

Porta em uso

O deploy falhou com "address already in use". Outra coisa já está escutando na mesma porta. Siga os passos pra identificar e liberar.

Sintomas

• docker service ps NOME --no-trunc mostra bind: address already in use
• O serviço fica em 0/1 e nunca sobe

Diagnóstico

# ss -tlnp | grep PORTA

Substitua PORTA pelo número (ex.: 5678). O output mostra o PID do processo ocupando a porta.

Solução

1. Identifique o processo
   bash

   Copiar

   # lsof -i :PORTA

2. Se for um container Docker antigo
   bash

   Copiar

   # docker ps -a && docker rm -f CONTAINER-ID

3. Se for outro processo do sistema
   bash

   Copiar

   # kill -9 PID

4. Reinstale a stack pelo script
   Rode o script de novo e escolha a opção correspondente (ex.: 11 → 3 pra N8N).

Senha perdida

Perdeu a senha do N8N, do Portainer ou do Postgres? Tem como recuperar ou resetar. Depende de qual serviço.

Senha do Postgres

A senha é sempre salva em arquivo no servidor:

# cat /root/dados_vps/postgres/credenciais.txt

Senha do usuário N8N

1. Acesse o container do N8N
   bash

   Copiar

   # docker exec -it $(docker ps -qf name=n8n_editor) /bin/sh

2. Redefina a senha via CLI do N8N
   bash · dentro do container

   Copiar

   # n8n user-management:reset --email SEU-EMAIL

   Siga as instruções pra definir a nova senha. Depois exit pra sair do container.

Senha do Portainer

1. Remova o volume do Portainer
   🔥

   Vai apagar configurações do Portainer

   Seus containers e stacks continuam rodando. Só as configurações da interface são apagadas.

   bash

   Copiar

   # docker service rm portainer_portainer && docker volume rm portainer_portainer_data

2. Reinstale o Portainer
   No menu do script, opção 7. Depois acesse http://SEU-IP:9000 e crie novo usuário admin (lembre dos 5 minutos).

Reset completo

Quando nada mais funciona: apagar tudo e começar do zero. Isso apaga todos os seus dados. Use só como último recurso.

Quando usar

• Estado tão corrompido que nenhuma stack sobe
• Você quer recomeçar com uma instalação limpa
• Vai passar a VPS pra outra pessoa e quer zerar tudo

Passo a passo

1. Faça backup se possível
   Se o N8N ainda está acessível: Settings > Download. Se pgBackWeb está acessível: Export manual.
2. Pare e remova todos os serviços
   bash

   Copiar

   # docker service rm $(docker service ls -q)

3. Remova todos os volumes
   🔥

   Apaga todos os dados

   Esse comando apaga TODOS os volumes Docker, incluindo banco de dados.

   bash

   Copiar

   # docker volume rm $(docker volume ls -q)

4. Rode o script do zero
   bash

   Copiar

   # sudo bash <(curl -fsSL https://raw.githubusercontent.com/madeinlowcode/easy-setup/main/setup-mlc.sh)

   Escolha A pra instalação completa. Depois instale as stacks que precisar.

Como saber se deu certo

Cloudflare Hyperdrive

Como conectar seu PostgreSQL da VPS a Workers da Cloudflare — com pool de conexões automático e cache de queries no edge.

O que é o Hyperdrive

O Hyperdrive é um serviço da Cloudflare que fica na frente do seu PostgreSQL e resolve dois problemas de quem usa Workers: o tempo gasto para abrir uma conexão com o banco (que pode levar sete roundtrips antes de você conseguir mandar a primeira query) e a distância física entre o Worker — que pode rodar em qualquer canto do mundo — e sua VPS, que fica num único datacenter.

Em vez de cada Worker abrir uma conexão nova do zero, o Hyperdrive mantém um pool de conexões permanente dentro da rede da Cloudflare. E pra queries de leitura (SELECT), ele guarda o resultado em cache por até 60 segundos — você nem chega a bater no banco.

Como funciona

Connection pooling: O Hyperdrive mantém conexões abertas com seu banco dentro da rede da Cloudflare. Funciona no modo transaction: cada query usa uma conexão do pool durante a transação e a devolve logo que termina. Isso significa que dezenas de Workers simultâneos podem consultar o banco sem precisar abrir dezenas de conexões novas — o banco vê apenas as conexões do pool (cerca de 20 no plano gratuito).

Query cache: Queries que não escrevem nada no banco (SELECT) são cacheadas automaticamente por 60 segundos (configurável até 1 hora). Writes (INSERT, UPDATE, DELETE) nunca são cacheados — o Hyperdrive detecta isso automaticamente analisando o SQL. Evite usar NOW() ou RANDOM() em SELECTs se quiser que eles caiam no cache (resultado muda sempre, impossível cachear).

Pré-requisitos

• PostgreSQL instalado na VPS (opção 11 → 1 do easy-setup)
• Conta gratuita na Cloudflare — crie em dash.cloudflare.com/sign-up se ainda não tiver
• Node.js ≥ 16.17 instalado na sua máquina local (não na VPS)
• Porta 5432 aberta no firewall da VPS para conexões externas (veja o callout abaixo)

Passo a passo

1. Instale o Wrangler CLI

   O Wrangler é a ferramenta de linha de comando da Cloudflare pra gerenciar Workers. Rode na sua máquina local (não na VPS):

   bash · máquina local

   Copiar

   $ npm install -g wrangler

2. Faça login na Cloudflare

   Esse comando abre o navegador pra você autorizar o Wrangler com sua conta Cloudflare.

   bash

   Copiar

   $ npx wrangler login

3. Crie o projeto do Worker

   Cria a estrutura de pastas do Worker. Quando o assistente perguntar, escolha Hello World como tipo e TypeScript como linguagem.

   bash

   Copiar

   $ npm create cloudflare@latest meu-worker

   bash

   Copiar

   $ cd meu-worker

4. Leia as credenciais do Postgres e crie a configuração Hyperdrive

   Primeiro pegue as credenciais do Postgres salvas pelo easy-setup (rode na VPS via SSH):

   bash · na VPS via SSH

   Copiar

   # cat /root/dados_vps/postgres/credenciais.txt

   Agora crie a configuração Hyperdrive na sua máquina local, substituindo os valores pelos que você acabou de ler:

   bash · máquina local

   Copiar

   $ npx wrangler hyperdrive create meu-postgres --connection-string="postgres://USUARIO:SENHA@IP-DA-VPS:5432/postgres"

   O comando retorna um bloco JSON com um campo id. Copie esse ID — você vai precisar no próximo passo.

5. Configure o wrangler.toml

   Abra o arquivo wrangler.toml na raiz do projeto e adicione as linhas abaixo. Substitua SEU-ID-AQUI pelo ID do passo anterior.

   wrangler.toml

   Copiar

   compatibility_flags = ["nodejs_compat"]
   
   [[hyperdrive]]
   binding = "HYPERDRIVE"
   id = "SEU-ID-AQUI"

6. Instale o driver do PostgreSQL

   O Hyperdrive funciona com qualquer driver Postgres padrão. Use o pg (node-postgres):

   bash

   Copiar

   $ npm i pg && npm i -D @types/pg

7. Escreva o Worker

   Substitua o conteúdo de src/index.ts pelo código abaixo. Ele conecta via Hyperdrive e retorna o resultado de uma query como JSON:

   src/index.ts

   Copiar

   import { Client } from "pg";
   
   interface Env {
     HYPERDRIVE: Hyperdrive;
   }
   
   export default {
     async fetch(request: Request, env: Env): Promise<Response> {
       const client = new Client({
         connectionString: env.HYPERDRIVE.connectionString,
       });
       await client.connect();
       const result = await client.query("SELECT NOW() AS agora");
       await client.end();
       return Response.json(result.rows);
     },
   };

   💡

   Troque a query pelo que você precisar

   O SELECT NOW() é só pra testar a conexão — substitua pela sua query real. Detalhe: queries com NOW() não são cacheadas pelo Hyperdrive porque o resultado muda a cada segundo.
8. Faça o deploy

   Publica o Worker na rede da Cloudflare e retorna uma URL pública pra você testar no navegador:

   bash

   Copiar

   $ npx wrangler deploy

Configurações opcionais

Você pode personalizar o comportamento do cache ao criar (ou atualizar) a configuração:

Aumentar o tempo de cache — padrão é 60 s, máximo é 3600 s (1 hora):

$ npx wrangler hyperdrive create meu-postgres --connection-string="..." --max-age=300 --swr=30

Desabilitar cache — útil pra dados que mudam o tempo todo:

$ npx wrangler hyperdrive create meu-postgres --connection-string="..." --caching-disabled true

Limites do plano gratuito

Os limites resetam todo dia às 00:00 UTC. Se você estourar o limite diário, as queries do Worker vão falhar com erro até o reset.

Desenvolvimento local

Pra testar sem fazer deploy, o wrangler dev usa uma conexão direta (sem passar pelo Hyperdrive de verdade). Defina a string de conexão via variável de ambiente:

$ CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://usuario:senha@IP-DA-VPS:5432/postgres" npx wrangler dev

Em construção

Esta página está no roadmap mas ainda não foi escrita. Algumas das páginas-modelo já estão prontas — explore-as no menu lateral.