<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Nuvits</title>
    <description>The latest articles on DEV Community by Nuvits (nuvits).</description>
    <link>https://dev.to/nuvits</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Forganization%2Fprofile_image%2F16029%2Fe9302a65-4a8e-4814-9513-b05850ae5df9.png</url>
      <title>DEV Community: Nuvits</title>
      <link>https://dev.to/nuvits</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/nuvits"/>
    <language>en</language>
    <item>
      <title>Backup automático do n8n: cron, cópia criptografada e restauração testada</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Fri, 20 Nov 2026 12:36:40 +0000</pubDate>
      <link>https://dev.to/nuvits/backup-automatico-do-n8n-cron-copia-criptografada-e-restauracao-testada-43l</link>
      <guid>https://dev.to/nuvits/backup-automatico-do-n8n-cron-copia-criptografada-e-restauracao-testada-43l</guid>
      <description>&lt;p&gt;Este guia transforma o backup manual do n8n num backup diário que roda sozinho: um script faz o dump do PostgreSQL, guarda a pasta &lt;code&gt;.n8n&lt;/code&gt; e o &lt;code&gt;.env&lt;/code&gt; com a chave de criptografia, manda tudo criptografado para um bucket S3 fora da VPS e apaga as cópias antigas. No fim, você restaura a cópia num projeto separado e confere que os workflows voltaram e que as credenciais ainda podem ser lidas.&lt;/p&gt;

&lt;h2&gt;
  
  
  Antes de começar
&lt;/h2&gt;

&lt;p&gt;O ponto de partida é a instalação do guia &lt;a href="https://nuvits.net/blog/como-instalar-n8n-docker-vps" rel="noopener noreferrer"&gt;Como instalar o n8n com Docker numa VPS&lt;/a&gt;: n8n com PostgreSQL em Docker Compose, na pasta &lt;code&gt;/home/deploy/n8n&lt;/code&gt;. Se a sua pasta ou o nome dos serviços forem outros, ajuste as variáveis no começo do script.&lt;/p&gt;

&lt;p&gt;Você também vai precisar de um bucket num armazenamento compatível com S3 que não esteja na mesma VPS: Backblaze B2, Cloudflare R2, Wasabi, Amazon S3 ou outro. Crie o bucket e uma chave de acesso que só enxergue esse bucket. Anote o endpoint, a região, o nome do bucket e o par de chaves.&lt;/p&gt;

&lt;h2&gt;
  
  
  O que entra no backup
&lt;/h2&gt;

&lt;p&gt;Um backup que restaura o n8n inteiro tem quatro partes:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;O banco PostgreSQL&lt;/strong&gt;, com workflows, credenciais (criptografadas), usuários e histórico de execuções.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A pasta &lt;code&gt;.n8n&lt;/code&gt;&lt;/strong&gt;, que fica no volume &lt;code&gt;n8n_data&lt;/code&gt; e guarda o arquivo &lt;code&gt;config&lt;/code&gt; com a chave de criptografia.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;O &lt;code&gt;.env&lt;/code&gt;&lt;/strong&gt;, com a &lt;code&gt;N8N_ENCRYPTION_KEY&lt;/code&gt; e as senhas do banco e do runner.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;O &lt;code&gt;docker-compose.yml&lt;/code&gt; e o &lt;code&gt;Caddyfile&lt;/code&gt;&lt;/strong&gt;, para subir a mesma stack numa VPS nova.&lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Sem a chave, as credenciais se perdem.&lt;/strong&gt; O banco restaura, os workflows aparecem, mas o n8n não consegue ler nenhuma credencial salva. Por isso o &lt;code&gt;.env&lt;/code&gt; vai junto, e por isso a cópia que sai da VPS precisa ser criptografada.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Instalar o rclone
&lt;/h2&gt;

&lt;p&gt;O rclone copia arquivos para quase qualquer armazenamento em nuvem e criptografa no caminho. O pacote do Ubuntu 24.04 está várias versões atrás, então instale o &lt;code&gt;.deb&lt;/code&gt; do próprio projeto:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; /tmp
curl -fsSLO https://downloads.rclone.org/rclone-current-linux-&lt;span class="nv"&gt;$(&lt;/span&gt;dpkg --print-architecture&lt;span class="o"&gt;)&lt;/span&gt;.deb
sudo apt install ./rclone-current-linux-&lt;span class="nv"&gt;$(&lt;/span&gt;dpkg --print-architecture&lt;span class="o"&gt;)&lt;/span&gt;.deb
rclone version
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O backup vai rodar como &lt;code&gt;root&lt;/code&gt;, pelo cron, então a configuração do rclone também fica no &lt;code&gt;root&lt;/code&gt;. Por isso os comandos abaixo usam &lt;code&gt;sudo rclone&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Configurar o destino criptografado
&lt;/h2&gt;

&lt;p&gt;Primeiro, o acesso ao bucket. O &lt;code&gt;read&lt;/code&gt; pede os valores sem que eles fiquem no histórico do shell:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;read&lt;/span&gt; -rp &lt;span class="s2"&gt;"Endpoint S3 (https://...): "&lt;/span&gt; S3_ENDPOINT
&lt;span class="nb"&gt;read&lt;/span&gt; -rp &lt;span class="s2"&gt;"Região: "&lt;/span&gt; S3_REGION
&lt;span class="nb"&gt;read&lt;/span&gt; -rp &lt;span class="s2"&gt;"Access key ID: "&lt;/span&gt; S3_KEY
&lt;span class="nb"&gt;read&lt;/span&gt; -rsp &lt;span class="s2"&gt;"Secret access key: "&lt;/span&gt; S3_SECRET&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt;

sudo rclone config create n8n-s3 s3 &lt;span class="nv"&gt;provider&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;Other \
  &lt;span class="nv"&gt;endpoint&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$S3_ENDPOINT"&lt;/span&gt; &lt;span class="nv"&gt;region&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$S3_REGION"&lt;/span&gt; \
  &lt;span class="nv"&gt;access_key_id&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$S3_KEY"&lt;/span&gt; &lt;span class="nv"&gt;secret_access_key&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$S3_SECRET"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /dev/null

sudo rclone lsd n8n-s3:
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;rclone config create&lt;/code&gt; imprime a configuração que acabou de criar, com a chave secreta; o &lt;code&gt;&amp;gt; /dev/null&lt;/code&gt; evita que ela apareça na tela. O último comando lista os buckets que a chave enxerga. Se o seu provedor estiver na &lt;a href="https://rclone.org/s3/" rel="noopener noreferrer"&gt;lista do rclone&lt;/a&gt; (AWS, Cloudflare, Wasabi e outros), troque &lt;code&gt;provider=Other&lt;/code&gt; pelo nome dele.&lt;/p&gt;

&lt;p&gt;Depois, a camada de criptografia. Ela fica por cima do bucket, numa pasta &lt;code&gt;n8n&lt;/code&gt;, e cifra o conteúdo e os nomes dos arquivos antes do envio. Gere duas senhas longas e guarde as duas num gerenciador de senhas antes de continuar:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;openssl rand -hex 32
openssl rand -hex 32
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;read&lt;/span&gt; -rp &lt;span class="s2"&gt;"Nome do bucket: "&lt;/span&gt; S3_BUCKET
&lt;span class="nb"&gt;read&lt;/span&gt; -rsp &lt;span class="s2"&gt;"Senha da criptografia: "&lt;/span&gt; CRYPT_PASS&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt;
&lt;span class="nb"&gt;read&lt;/span&gt; -rsp &lt;span class="s2"&gt;"Segunda senha (salt): "&lt;/span&gt; CRYPT_SALT&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt;

sudo rclone config create n8n-offsite crypt \
  &lt;span class="nv"&gt;remote&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"n8n-s3:$S3_BUCKET/n8n"&lt;/span&gt; \
  &lt;span class="nv"&gt;password&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$CRYPT_PASS"&lt;/span&gt; &lt;span class="nv"&gt;password2&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$CRYPT_SALT"&lt;/span&gt; --obscure &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /dev/null

&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"teste"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; sudo rclone rcat n8n-offsite:teste.txt
sudo rclone cat n8n-offsite:teste.txt
sudo rclone deletefile n8n-offsite:teste.txt
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;rclone cat&lt;/code&gt; precisa imprimir &lt;code&gt;teste&lt;/code&gt;. O aviso &lt;code&gt;NOTICE&lt;/code&gt; sobre &lt;code&gt;--checksum&lt;/code&gt; que o &lt;code&gt;rcat&lt;/code&gt; mostra pode ser ignorado. No painel do provedor, o arquivo aparece com nome embaralhado dentro de &lt;code&gt;n8n/&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Sem as duas senhas, o backup não abre.&lt;/strong&gt; A &lt;a href="https://rclone.org/crypt/" rel="noopener noreferrer"&gt;documentação do rclone&lt;/a&gt; é direta: perdeu a senha, perdeu os dados. O arquivo &lt;code&gt;/root/.config/rclone/rclone.conf&lt;/code&gt; guarda as senhas apenas ofuscadas, não protegidas; não o copie para lugares públicos.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  O script de backup
&lt;/h2&gt;

&lt;p&gt;Crie o script com &lt;code&gt;sudo nano /usr/local/sbin/n8n-backup.sh&lt;/code&gt; e cole:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;#!/usr/bin/env bash&lt;/span&gt;
&lt;span class="c"&gt;# Backup diário do n8n: banco, pasta .n8n e arquivos da stack,&lt;/span&gt;
&lt;span class="c"&gt;# com cópia criptografada fora da VPS.&lt;/span&gt;
&lt;span class="nb"&gt;set&lt;/span&gt; -euo pipefail

&lt;span class="nv"&gt;N8N_DIR&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;/home/deploy/n8n        &lt;span class="c"&gt;# pasta do docker-compose.yml&lt;/span&gt;
&lt;span class="nv"&gt;LOCAL_DIR&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;/var/backups/n8n      &lt;span class="c"&gt;# cópias locais&lt;/span&gt;
&lt;span class="nv"&gt;REMOTE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;n8n-offsite:             &lt;span class="c"&gt;# destino criptografado do rclone&lt;/span&gt;
&lt;span class="nv"&gt;KEEP_LOCAL_DAYS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;7               &lt;span class="c"&gt;# dias de cópias na VPS&lt;/span&gt;
&lt;span class="nv"&gt;KEEP_REMOTE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;30d                 &lt;span class="c"&gt;# tempo de cópias no bucket&lt;/span&gt;

&lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="s2"&gt;"$N8N_DIR"&lt;/span&gt;
&lt;span class="nb"&gt;set&lt;/span&gt; -a&lt;span class="o"&gt;;&lt;/span&gt; . ./.env&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;set&lt;/span&gt; +a

&lt;span class="nv"&gt;STAMP&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F-%H%M&lt;span class="o"&gt;)&lt;/span&gt;
&lt;span class="nv"&gt;DEST&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$LOCAL_DIR/$STAMP"&lt;/span&gt;
install -d -m 700 &lt;span class="s2"&gt;"$LOCAL_DIR"&lt;/span&gt; &lt;span class="s2"&gt;"$DEST"&lt;/span&gt;

&lt;span class="c"&gt;# 1. Banco, no formato do pg_restore, e conferência do arquivo&lt;/span&gt;
docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T postgres pg_dump -U &lt;span class="s2"&gt;"$POSTGRES_USER"&lt;/span&gt; -d &lt;span class="s2"&gt;"$POSTGRES_DB"&lt;/span&gt; -Fc &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="s2"&gt;"$DEST/n8n-db.dump"&lt;/span&gt;
docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T postgres pg_restore --list &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="s2"&gt;"$DEST/n8n-db.dump"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /dev/null

&lt;span class="c"&gt;# 2. Pasta .n8n, de dentro do volume&lt;/span&gt;
docker run --rm --volumes-from &lt;span class="s2"&gt;"$(docker compose ps -q n8n)"&lt;/span&gt; -v &lt;span class="s2"&gt;"$DEST"&lt;/span&gt;:/backup \
  ubuntu:24.04 tar czf /backup/n8n-data.tar.gz -C /home/node .n8n

&lt;span class="c"&gt;# 3. Arquivos da stack&lt;/span&gt;
cp .env &lt;span class="s2"&gt;"$DEST/env"&lt;/span&gt;
cp docker-compose.yml Caddyfile &lt;span class="s2"&gt;"$DEST/"&lt;/span&gt;

&lt;span class="c"&gt;# 4. Cópia para fora da VPS e conferência&lt;/span&gt;
rclone copy &lt;span class="s2"&gt;"$DEST"&lt;/span&gt; &lt;span class="s2"&gt;"$REMOTE$STAMP"&lt;/span&gt;
rclone cryptcheck &lt;span class="s2"&gt;"$DEST"&lt;/span&gt; &lt;span class="s2"&gt;"$REMOTE$STAMP"&lt;/span&gt;

&lt;span class="c"&gt;# 5. Limpeza das cópias antigas&lt;/span&gt;
find &lt;span class="s2"&gt;"$LOCAL_DIR"&lt;/span&gt; -mindepth 1 -maxdepth 1 -type d -mtime +&lt;span class="s2"&gt;"$KEEP_LOCAL_DAYS"&lt;/span&gt; -exec rm -rf &lt;span class="o"&gt;{&lt;/span&gt;&lt;span class="o"&gt;}&lt;/span&gt; +
rclone delete &lt;span class="s2"&gt;"$REMOTE"&lt;/span&gt; --min-age &lt;span class="s2"&gt;"$KEEP_REMOTE"&lt;/span&gt;
rclone rmdirs &lt;span class="s2"&gt;"$REMOTE"&lt;/span&gt; --leave-root

&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"$(date -Is) backup $STAMP concluído"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo chmod 700 /usr/local/sbin/n8n-backup.sh
sudo /usr/local/sbin/n8n-backup.sh
sudo rclone lsl n8n-offsite:
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A primeira execução precisa terminar com &lt;code&gt;backup ... concluído&lt;/code&gt;, e o &lt;code&gt;rclone lsl&lt;/code&gt; precisa listar os cinco arquivos dentro de uma pasta com a data e a hora.&lt;/p&gt;

&lt;p&gt;O que vale saber sobre o script:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;O &lt;code&gt;set -euo pipefail&lt;/code&gt; faz o script parar no primeiro erro. Um dump que falha não chega ao bucket, e a limpeza das cópias antigas não roda.&lt;/li&gt;
&lt;li&gt;O dump sai no formato próprio do PostgreSQL (&lt;code&gt;-Fc&lt;/code&gt;), em vez do &lt;code&gt;pg_dumpall&lt;/code&gt; do guia de instalação. Ele restaura dentro de um banco que já existe, que é o caso de um contêiner novo do Postgres. O &lt;code&gt;pg_restore --list&lt;/code&gt; lê o arquivo inteiro e falha se ele estiver corrompido.&lt;/li&gt;
&lt;li&gt;O &lt;code&gt;pg_dump&lt;/code&gt; lê um retrato consistente do banco com o n8n rodando. Não é preciso parar a stack.&lt;/li&gt;
&lt;li&gt;O &lt;code&gt;rclone cryptcheck&lt;/code&gt; confere cada arquivo do bucket contra o original, pelo hash, sem baixar nada.&lt;/li&gt;
&lt;li&gt;A limpeza apaga cópias locais com mais de 7 dias e cópias no bucket com mais de 30. Mude &lt;code&gt;KEEP_LOCAL_DAYS&lt;/code&gt; e &lt;code&gt;KEEP_REMOTE&lt;/code&gt; se o seu banco for grande ou se precisar guardar por mais tempo.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Agendar com o cron
&lt;/h2&gt;

&lt;p&gt;Crie o arquivo &lt;code&gt;/etc/cron.d/n8n-backup&lt;/code&gt; com &lt;code&gt;sudo nano /etc/cron.d/n8n-backup&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ini"&gt;&lt;code&gt;&lt;span class="na"&gt;SHELL&lt;/span&gt;&lt;span class="o"&gt;=/&lt;/span&gt;&lt;span class="n"&gt;bin&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;bash&lt;/span&gt;
&lt;span class="na"&gt;PATH&lt;/span&gt;&lt;span class="o"&gt;=/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;local&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;sbin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;local&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;bin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;sbin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;bin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;sbin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;bin&lt;/span&gt;
&lt;span class="mi"&gt;30&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="n"&gt;root&lt;/span&gt; &lt;span class="n"&gt;flock&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;run&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;backup&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lock&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;local&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;sbin&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;backup&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sh&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;log&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;backup&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;log&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&amp;amp;&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O backup roda todo dia às 3h30 no fuso da VPS. Confira o fuso com &lt;code&gt;timedatectl&lt;/code&gt;: muitas VPS vêm em UTC, e 3h30 UTC são 0h30 em Brasília. Se mudar o fuso com &lt;code&gt;sudo timedatectl set-timezone&lt;/code&gt;, reinicie o cron com &lt;code&gt;sudo systemctl restart cron&lt;/code&gt;, porque ele só lê o fuso ao iniciar. O &lt;code&gt;flock&lt;/code&gt; impede que duas execuções rodem ao mesmo tempo, e a saída de cada uma vai para &lt;code&gt;/var/log/n8n-backup.log&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Arquivos em &lt;code&gt;/etc/cron.d&lt;/code&gt; não podem ter ponto no nome e precisam terminar com uma quebra de linha. O cron lê o arquivo sozinho, sem reiniciar nada. No dia seguinte, confira:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;tail -n 5 /var/log/n8n-backup.log
sudo rclone lsd n8n-offsite:
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Backup que falha em silêncio não é backup.&lt;/strong&gt; O cron não avisa ninguém quando o script falha. Um serviço de monitoramento de cron, como o &lt;a href="https://healthchecks.io/" rel="noopener noreferrer"&gt;Healthchecks.io&lt;/a&gt;, avisa por e-mail quando a execução do dia não chega: acrescente &lt;code&gt;curl -fsS -m 10 --retry 3 https://hc-ping.com/SEU-UUID&lt;/code&gt; como última linha do script.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Testar a restauração
&lt;/h2&gt;

&lt;p&gt;Um backup só vale se restaura. O teste abaixo baixa a cópia mais recente do bucket e a restaura na mesma VPS, num projeto separado do Compose. Ele não publica portas nem inicia o servidor do n8n. Assim, nenhum gatilho ou workflow agendado roda em dobro, e a instância de produção continua intacta.&lt;/p&gt;

&lt;p&gt;Baixe a cópia mais recente:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/n8n-restore-test &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd&lt;/span&gt; ~/n8n-restore-test

&lt;span class="nv"&gt;STAMP&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$(&lt;/span&gt;sudo rclone lsf --dirs-only n8n-offsite: &lt;span class="o"&gt;|&lt;/span&gt; sort &lt;span class="o"&gt;|&lt;/span&gt; tail -n 1 &lt;span class="o"&gt;|&lt;/span&gt; tr -d /&lt;span class="o"&gt;)&lt;/span&gt;
&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"$STAMP"&lt;/span&gt;
&lt;span class="o"&gt;[&lt;/span&gt; -n &lt;span class="s2"&gt;"$STAMP"&lt;/span&gt; &lt;span class="o"&gt;]&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; sudo rclone copy &lt;span class="s2"&gt;"n8n-offsite:$STAMP"&lt;/span&gt; ./backup
sudo chown -R &lt;span class="s2"&gt;"$USER"&lt;/span&gt;: backup

cp backup/env .env
cp backup/docker-compose.yml backup/Caddyfile .
chmod 600 .env
&lt;span class="nb"&gt;set&lt;/span&gt; -a &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; . ./.env &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;set&lt;/span&gt; +a
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;echo&lt;/code&gt; precisa mostrar a data e a hora da cópia; se sair vazio, o bucket não tem backup e o comando seguinte não baixa nada.&lt;/p&gt;

&lt;p&gt;Como a pasta se chama &lt;code&gt;n8n-restore-test&lt;/code&gt;, o Compose cria contêineres e volumes com esse prefixo, separados dos de produção. Restaure o banco num Postgres novo:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose up -d --wait postgres
sudo docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T postgres pg_restore -U &lt;span class="s2"&gt;"$POSTGRES_USER"&lt;/span&gt; -d &lt;span class="s2"&gt;"$POSTGRES_DB"&lt;/span&gt; --no-owner --exit-on-error &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; backup/n8n-db.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Devolva a pasta &lt;code&gt;.n8n&lt;/code&gt; ao volume do n8n:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose run --rm --no-deps -v &lt;span class="s2"&gt;"$PWD/backup"&lt;/span&gt;:/backup --entrypoint tar n8n xzf /backup/n8n-data.tar.gz -C /home/node
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Agora confira os workflows e as credenciais com a linha de comando do n8n, que roda e sai sem iniciar o servidor:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose run --rm --no-deps n8n export:workflow --all --pretty &lt;span class="o"&gt;|&lt;/span&gt; grep &lt;span class="s1"&gt;'"name"'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; head
sudo docker compose run --rm --no-deps n8n export:credentials --all --decrypted --pretty &lt;span class="o"&gt;|&lt;/span&gt; grep -c &lt;span class="s1"&gt;'"data"'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O primeiro comando lista os nomes dos workflows e dos nós. O segundo conta as credenciais que o n8n conseguiu abrir com a chave do backup; o número precisa bater com o total de credenciais da sua instância. Se ele der &lt;code&gt;0&lt;/code&gt; e aparecer &lt;code&gt;Credentials could not be decrypted&lt;/code&gt; ou &lt;code&gt;Mismatching encryption keys&lt;/code&gt;, a chave do backup não confere com a do banco, e esse backup não restauraria as credenciais. Os dois comandos não gravam nada em disco, mas o segundo lê as credenciais abertas: não troque o &lt;code&gt;grep -c&lt;/code&gt; por algo que as imprima na tela.&lt;/p&gt;

&lt;p&gt;Por fim, apague o ambiente de teste. Aqui, e só aqui, o &lt;code&gt;-v&lt;/code&gt; é o que você quer, porque apaga os volumes do teste:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/n8n-restore-test
sudo docker compose down -v
&lt;span class="nb"&gt;cd&lt;/span&gt; ~ &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; rm -rf ~/n8n-restore-test
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Confira a pasta antes do &lt;code&gt;down -v&lt;/code&gt;.&lt;/strong&gt; O comando apaga os volumes do projeto da pasta em que você está. Em &lt;code&gt;~/n8n&lt;/code&gt;, ele apagaria o banco e a chave de produção.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Repita o teste de tempos em tempos, por exemplo depois de cada atualização do n8n ou uma vez por mês.&lt;/p&gt;

&lt;h2&gt;
  
  
  Restaurar numa VPS nova
&lt;/h2&gt;

&lt;p&gt;Se a VPS se perder, o caminho é o mesmo do teste, com a stack de produção:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Instale o Docker e o rclone na VPS nova, como no guia de instalação e neste guia.&lt;/li&gt;
&lt;li&gt;Recrie os dois destinos do rclone com as mesmas chaves do bucket e as mesmas duas senhas do gerenciador de senhas.&lt;/li&gt;
&lt;li&gt;Baixe a cópia mais recente para &lt;code&gt;/home/deploy/n8n/backup&lt;/code&gt; e coloque &lt;code&gt;env&lt;/code&gt; (renomeado para &lt;code&gt;.env&lt;/code&gt;), &lt;code&gt;docker-compose.yml&lt;/code&gt; e &lt;code&gt;Caddyfile&lt;/code&gt; em &lt;code&gt;/home/deploy/n8n&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Suba só o Postgres, restaure o banco e a pasta &lt;code&gt;.n8n&lt;/code&gt; com os mesmos comandos do teste.&lt;/li&gt;
&lt;li&gt;Aponte o DNS para o IP novo e suba a stack inteira com &lt;code&gt;sudo docker compose up -d&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Entre no editor com a mesma conta de antes e, depois de conferir, apague a pasta &lt;code&gt;backup&lt;/code&gt;, que tem uma cópia do &lt;code&gt;.env&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Próximos passos
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Se o provedor do bucket permitir, use uma chave que lista, lê e grava, mas não apaga, e ligue o versionamento ou o bloqueio de objetos (object lock) do bucket. A retenção passa para uma regra de ciclo de vida do bucket, e as duas linhas de limpeza com &lt;code&gt;rclone&lt;/code&gt; saem do script. Assim, quem invadir a VPS não consegue apagar nem sobrescrever as cópias antigas. A chave não pode ser só de escrita: o &lt;code&gt;rclone copy&lt;/code&gt;, o &lt;code&gt;cryptcheck&lt;/code&gt; e a restauração precisam listar e ler o bucket.&lt;/li&gt;
&lt;li&gt;Guarde o &lt;code&gt;.env&lt;/code&gt; e as duas senhas do rclone num gerenciador de senhas, fora da VPS e fora do bucket.&lt;/li&gt;
&lt;li&gt;Para o servidor inteiro, e não só o n8n, o passo seguinte é um backup com versões e deduplicação, como o do restic.&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>braziliandevs</category>
      <category>portugues</category>
      <category>n8n</category>
      <category>backup</category>
    </item>
    <item>
      <title>Automatic n8n backups: cron, encrypted copies and a tested restore</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Fri, 20 Nov 2026 12:36:33 +0000</pubDate>
      <link>https://dev.to/nuvits/automatic-n8n-backups-cron-encrypted-copies-and-a-tested-restore-2hbj</link>
      <guid>https://dev.to/nuvits/automatic-n8n-backups-cron-encrypted-copies-and-a-tested-restore-2hbj</guid>
      <description>&lt;p&gt;This guide turns the manual n8n backup into a daily one that runs on its own: a script dumps PostgreSQL, saves the &lt;code&gt;.n8n&lt;/code&gt; folder and the &lt;code&gt;.env&lt;/code&gt; with the encryption key, sends everything encrypted to an S3 bucket off the VPS and deletes old copies. At the end, you restore the copy into a separate project and check that the workflows came back and that the credentials can still be read.&lt;/p&gt;

&lt;h2&gt;
  
  
  Before you start
&lt;/h2&gt;

&lt;p&gt;The starting point is the setup from &lt;a href="https://nuvits.net/en/blog/install-n8n-docker-vps" rel="noopener noreferrer"&gt;How to install n8n with Docker on a VPS&lt;/a&gt;: n8n with PostgreSQL on Docker Compose, in &lt;code&gt;/home/deploy/n8n&lt;/code&gt;. If your folder or service names are different, adjust the variables at the top of the script.&lt;/p&gt;

&lt;p&gt;You also need a bucket in S3-compatible storage that is not on the same VPS: Backblaze B2, Cloudflare R2, Wasabi, Amazon S3 or another. Create the bucket and an access key that can only see that bucket. Note down the endpoint, the region, the bucket name and the key pair.&lt;/p&gt;

&lt;h2&gt;
  
  
  What goes into the backup
&lt;/h2&gt;

&lt;p&gt;A backup that restores all of n8n has four parts:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The PostgreSQL database&lt;/strong&gt;, with workflows, credentials (encrypted), users and execution history.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The &lt;code&gt;.n8n&lt;/code&gt; folder&lt;/strong&gt;, which lives in the &lt;code&gt;n8n_data&lt;/code&gt; volume and holds the &lt;code&gt;config&lt;/code&gt; file with the encryption key.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The &lt;code&gt;.env&lt;/code&gt;&lt;/strong&gt;, with &lt;code&gt;N8N_ENCRYPTION_KEY&lt;/code&gt; and the database and runner passwords.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The &lt;code&gt;docker-compose.yml&lt;/code&gt; and the &lt;code&gt;Caddyfile&lt;/code&gt;&lt;/strong&gt;, to bring the same stack up on a new VPS.&lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Without the key, the credentials are lost.&lt;/strong&gt; The database restores and the workflows show up, but n8n can't read any saved credential. That's why the &lt;code&gt;.env&lt;/code&gt; goes along, and why the copy that leaves the VPS has to be encrypted.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Install rclone
&lt;/h2&gt;

&lt;p&gt;rclone copies files to almost any cloud storage and encrypts them on the way. The Ubuntu 24.04 package is several versions behind, so install the &lt;code&gt;.deb&lt;/code&gt; from the project itself:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; /tmp
curl -fsSLO https://downloads.rclone.org/rclone-current-linux-&lt;span class="nv"&gt;$(&lt;/span&gt;dpkg --print-architecture&lt;span class="o"&gt;)&lt;/span&gt;.deb
sudo apt install ./rclone-current-linux-&lt;span class="nv"&gt;$(&lt;/span&gt;dpkg --print-architecture&lt;span class="o"&gt;)&lt;/span&gt;.deb
rclone version
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The backup will run as &lt;code&gt;root&lt;/code&gt;, from cron, so the rclone configuration also lives under &lt;code&gt;root&lt;/code&gt;. That's why the commands below use &lt;code&gt;sudo rclone&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Set up the encrypted destination
&lt;/h2&gt;

&lt;p&gt;First, access to the bucket. &lt;code&gt;read&lt;/code&gt; asks for the values without leaving them in your shell history:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;read&lt;/span&gt; -rp &lt;span class="s2"&gt;"S3 endpoint (https://...): "&lt;/span&gt; S3_ENDPOINT
&lt;span class="nb"&gt;read&lt;/span&gt; -rp &lt;span class="s2"&gt;"Region: "&lt;/span&gt; S3_REGION
&lt;span class="nb"&gt;read&lt;/span&gt; -rp &lt;span class="s2"&gt;"Access key ID: "&lt;/span&gt; S3_KEY
&lt;span class="nb"&gt;read&lt;/span&gt; -rsp &lt;span class="s2"&gt;"Secret access key: "&lt;/span&gt; S3_SECRET&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt;

sudo rclone config create n8n-s3 s3 &lt;span class="nv"&gt;provider&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;Other \
  &lt;span class="nv"&gt;endpoint&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$S3_ENDPOINT"&lt;/span&gt; &lt;span class="nv"&gt;region&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$S3_REGION"&lt;/span&gt; \
  &lt;span class="nv"&gt;access_key_id&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$S3_KEY"&lt;/span&gt; &lt;span class="nv"&gt;secret_access_key&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$S3_SECRET"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /dev/null

sudo rclone lsd n8n-s3:
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;rclone config create&lt;/code&gt; prints the configuration it just created, secret key included; the &lt;code&gt;&amp;gt; /dev/null&lt;/code&gt; keeps it off the screen. The last command lists the buckets the key can see. If your provider is on &lt;a href="https://rclone.org/s3/" rel="noopener noreferrer"&gt;rclone's list&lt;/a&gt; (AWS, Cloudflare, Wasabi and others), replace &lt;code&gt;provider=Other&lt;/code&gt; with its name.&lt;/p&gt;

&lt;p&gt;Then, the encryption layer. It sits on top of the bucket, in an &lt;code&gt;n8n&lt;/code&gt; folder, and encrypts both contents and file names before upload. Generate two long passwords and store both in a password manager before you continue:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;openssl rand -hex 32
openssl rand -hex 32
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;read&lt;/span&gt; -rp &lt;span class="s2"&gt;"Bucket name: "&lt;/span&gt; S3_BUCKET
&lt;span class="nb"&gt;read&lt;/span&gt; -rsp &lt;span class="s2"&gt;"Encryption password: "&lt;/span&gt; CRYPT_PASS&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt;
&lt;span class="nb"&gt;read&lt;/span&gt; -rsp &lt;span class="s2"&gt;"Second password (salt): "&lt;/span&gt; CRYPT_SALT&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt;

sudo rclone config create n8n-offsite crypt \
  &lt;span class="nv"&gt;remote&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"n8n-s3:$S3_BUCKET/n8n"&lt;/span&gt; \
  &lt;span class="nv"&gt;password&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$CRYPT_PASS"&lt;/span&gt; &lt;span class="nv"&gt;password2&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$CRYPT_SALT"&lt;/span&gt; --obscure &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /dev/null

&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"test"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; sudo rclone rcat n8n-offsite:test.txt
sudo rclone cat n8n-offsite:test.txt
sudo rclone deletefile n8n-offsite:test.txt
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;rclone cat&lt;/code&gt; must print &lt;code&gt;test&lt;/code&gt;. You can ignore the &lt;code&gt;NOTICE&lt;/code&gt; about &lt;code&gt;--checksum&lt;/code&gt; that &lt;code&gt;rcat&lt;/code&gt; shows. In the provider's dashboard, the file shows up with a scrambled name inside &lt;code&gt;n8n/&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Without both passwords, the backup won't open.&lt;/strong&gt; The &lt;a href="https://rclone.org/crypt/" rel="noopener noreferrer"&gt;rclone documentation&lt;/a&gt; is blunt about it: lose the password and you lose the data. The file &lt;code&gt;/root/.config/rclone/rclone.conf&lt;/code&gt; keeps the passwords only obscured, not protected; don't copy it anywhere public.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  The backup script
&lt;/h2&gt;

&lt;p&gt;Create the script with &lt;code&gt;sudo nano /usr/local/sbin/n8n-backup.sh&lt;/code&gt; and paste:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;#!/usr/bin/env bash&lt;/span&gt;
&lt;span class="c"&gt;# Daily n8n backup: database, .n8n folder and stack files,&lt;/span&gt;
&lt;span class="c"&gt;# with an encrypted copy off the VPS.&lt;/span&gt;
&lt;span class="nb"&gt;set&lt;/span&gt; -euo pipefail

&lt;span class="nv"&gt;N8N_DIR&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;/home/deploy/n8n        &lt;span class="c"&gt;# folder with docker-compose.yml&lt;/span&gt;
&lt;span class="nv"&gt;LOCAL_DIR&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;/var/backups/n8n      &lt;span class="c"&gt;# local copies&lt;/span&gt;
&lt;span class="nv"&gt;REMOTE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;n8n-offsite:             &lt;span class="c"&gt;# encrypted rclone destination&lt;/span&gt;
&lt;span class="nv"&gt;KEEP_LOCAL_DAYS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;7               &lt;span class="c"&gt;# days of copies on the VPS&lt;/span&gt;
&lt;span class="nv"&gt;KEEP_REMOTE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;30d                 &lt;span class="c"&gt;# how long copies stay in the bucket&lt;/span&gt;

&lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="s2"&gt;"$N8N_DIR"&lt;/span&gt;
&lt;span class="nb"&gt;set&lt;/span&gt; -a&lt;span class="o"&gt;;&lt;/span&gt; . ./.env&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;set&lt;/span&gt; +a

&lt;span class="nv"&gt;STAMP&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F-%H%M&lt;span class="o"&gt;)&lt;/span&gt;
&lt;span class="nv"&gt;DEST&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$LOCAL_DIR/$STAMP"&lt;/span&gt;
install -d -m 700 &lt;span class="s2"&gt;"$LOCAL_DIR"&lt;/span&gt; &lt;span class="s2"&gt;"$DEST"&lt;/span&gt;

&lt;span class="c"&gt;# 1. Database, in pg_restore format, and a check of the file&lt;/span&gt;
docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T postgres pg_dump -U &lt;span class="s2"&gt;"$POSTGRES_USER"&lt;/span&gt; -d &lt;span class="s2"&gt;"$POSTGRES_DB"&lt;/span&gt; -Fc &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="s2"&gt;"$DEST/n8n-db.dump"&lt;/span&gt;
docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T postgres pg_restore --list &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="s2"&gt;"$DEST/n8n-db.dump"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /dev/null

&lt;span class="c"&gt;# 2. The .n8n folder, from inside the volume&lt;/span&gt;
docker run --rm --volumes-from &lt;span class="s2"&gt;"$(docker compose ps -q n8n)"&lt;/span&gt; -v &lt;span class="s2"&gt;"$DEST"&lt;/span&gt;:/backup \
  ubuntu:24.04 tar czf /backup/n8n-data.tar.gz -C /home/node .n8n

&lt;span class="c"&gt;# 3. Stack files&lt;/span&gt;
cp .env &lt;span class="s2"&gt;"$DEST/env"&lt;/span&gt;
cp docker-compose.yml Caddyfile &lt;span class="s2"&gt;"$DEST/"&lt;/span&gt;

&lt;span class="c"&gt;# 4. Off-site copy and check&lt;/span&gt;
rclone copy &lt;span class="s2"&gt;"$DEST"&lt;/span&gt; &lt;span class="s2"&gt;"$REMOTE$STAMP"&lt;/span&gt;
rclone cryptcheck &lt;span class="s2"&gt;"$DEST"&lt;/span&gt; &lt;span class="s2"&gt;"$REMOTE$STAMP"&lt;/span&gt;

&lt;span class="c"&gt;# 5. Remove old copies&lt;/span&gt;
find &lt;span class="s2"&gt;"$LOCAL_DIR"&lt;/span&gt; -mindepth 1 -maxdepth 1 -type d -mtime +&lt;span class="s2"&gt;"$KEEP_LOCAL_DAYS"&lt;/span&gt; -exec rm -rf &lt;span class="o"&gt;{&lt;/span&gt;&lt;span class="o"&gt;}&lt;/span&gt; +
rclone delete &lt;span class="s2"&gt;"$REMOTE"&lt;/span&gt; --min-age &lt;span class="s2"&gt;"$KEEP_REMOTE"&lt;/span&gt;
rclone rmdirs &lt;span class="s2"&gt;"$REMOTE"&lt;/span&gt; --leave-root

&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"$(date -Is) backup $STAMP done"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo chmod 700 /usr/local/sbin/n8n-backup.sh
sudo /usr/local/sbin/n8n-backup.sh
sudo rclone lsl n8n-offsite:
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The first run must end with &lt;code&gt;backup ... done&lt;/code&gt;, and &lt;code&gt;rclone lsl&lt;/code&gt; must list five files inside a folder named with the date and time.&lt;/p&gt;

&lt;p&gt;What's worth knowing about the script:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;set -euo pipefail&lt;/code&gt; stops the script at the first error. A failed dump never reaches the bucket, and old copies aren't cleaned up.&lt;/li&gt;
&lt;li&gt;The dump uses PostgreSQL's own format (&lt;code&gt;-Fc&lt;/code&gt;) instead of the &lt;code&gt;pg_dumpall&lt;/code&gt; from the install guide. It restores into a database that already exists, which is what a fresh Postgres container gives you. &lt;code&gt;pg_restore --list&lt;/code&gt; reads the whole file and fails if it's corrupted.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;pg_dump&lt;/code&gt; reads a consistent snapshot of the database while n8n keeps running. You don't need to stop the stack.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;rclone cryptcheck&lt;/code&gt; checks every file in the bucket against the original by hash, without downloading anything.&lt;/li&gt;
&lt;li&gt;The cleanup deletes local copies older than 7 days and bucket copies older than 30. Change &lt;code&gt;KEEP_LOCAL_DAYS&lt;/code&gt; and &lt;code&gt;KEEP_REMOTE&lt;/code&gt; if your database is large or you need to keep copies longer.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Schedule it with cron
&lt;/h2&gt;

&lt;p&gt;Create &lt;code&gt;/etc/cron.d/n8n-backup&lt;/code&gt; with &lt;code&gt;sudo nano /etc/cron.d/n8n-backup&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ini"&gt;&lt;code&gt;&lt;span class="na"&gt;SHELL&lt;/span&gt;&lt;span class="o"&gt;=/&lt;/span&gt;&lt;span class="n"&gt;bin&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;bash&lt;/span&gt;
&lt;span class="na"&gt;PATH&lt;/span&gt;&lt;span class="o"&gt;=/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;local&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;sbin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;local&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;bin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;sbin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;bin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;sbin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;bin&lt;/span&gt;
&lt;span class="mi"&gt;30&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="n"&gt;root&lt;/span&gt; &lt;span class="n"&gt;flock&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;run&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;backup&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lock&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;local&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;sbin&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;backup&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sh&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;log&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;backup&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;log&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&amp;amp;&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The backup runs every day at 3:30 in the VPS time zone. Check it with &lt;code&gt;timedatectl&lt;/code&gt;: many VPSs run on UTC. If you change the time zone with &lt;code&gt;sudo timedatectl set-timezone&lt;/code&gt;, restart cron with &lt;code&gt;sudo systemctl restart cron&lt;/code&gt;, because it only reads the time zone when it starts. &lt;code&gt;flock&lt;/code&gt; keeps two runs from overlapping, and each run's output goes to &lt;code&gt;/var/log/n8n-backup.log&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Files in &lt;code&gt;/etc/cron.d&lt;/code&gt; can't have a dot in their name and must end with a newline. Cron picks the file up on its own, without restarting anything. The next day, check:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;tail -n 5 /var/log/n8n-backup.log
sudo rclone lsd n8n-offsite:
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;A backup that fails silently isn't a backup.&lt;/strong&gt; Cron doesn't tell anyone when the script fails. A cron monitoring service such as &lt;a href="https://healthchecks.io/" rel="noopener noreferrer"&gt;Healthchecks.io&lt;/a&gt; emails you when the day's run doesn't check in: add &lt;code&gt;curl -fsS -m 10 --retry 3 https://hc-ping.com/YOUR-UUID&lt;/code&gt; as the last line of the script.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Test the restore
&lt;/h2&gt;

&lt;p&gt;A backup is only worth something if it restores. The test below downloads the latest copy from the bucket and restores it on the same VPS, in a separate Compose project. It publishes no ports and never starts the n8n server. That way no trigger or scheduled workflow runs twice, and the production instance stays untouched.&lt;/p&gt;

&lt;p&gt;Download the latest copy:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/n8n-restore-test &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd&lt;/span&gt; ~/n8n-restore-test

&lt;span class="nv"&gt;STAMP&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$(&lt;/span&gt;sudo rclone lsf --dirs-only n8n-offsite: &lt;span class="o"&gt;|&lt;/span&gt; sort &lt;span class="o"&gt;|&lt;/span&gt; tail -n 1 &lt;span class="o"&gt;|&lt;/span&gt; tr -d /&lt;span class="o"&gt;)&lt;/span&gt;
&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"$STAMP"&lt;/span&gt;
&lt;span class="o"&gt;[&lt;/span&gt; -n &lt;span class="s2"&gt;"$STAMP"&lt;/span&gt; &lt;span class="o"&gt;]&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; sudo rclone copy &lt;span class="s2"&gt;"n8n-offsite:$STAMP"&lt;/span&gt; ./backup
sudo chown -R &lt;span class="s2"&gt;"$USER"&lt;/span&gt;: backup

cp backup/env .env
cp backup/docker-compose.yml backup/Caddyfile .
chmod 600 .env
&lt;span class="nb"&gt;set&lt;/span&gt; -a &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; . ./.env &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;set&lt;/span&gt; +a
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;echo&lt;/code&gt; must print the date and time of the copy; if it prints nothing, the bucket has no backup and the next command downloads nothing.&lt;/p&gt;

&lt;p&gt;Because the folder is called &lt;code&gt;n8n-restore-test&lt;/code&gt;, Compose creates containers and volumes with that prefix, separate from production. Restore the database into a fresh Postgres:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose up -d --wait postgres
sudo docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T postgres pg_restore -U &lt;span class="s2"&gt;"$POSTGRES_USER"&lt;/span&gt; -d &lt;span class="s2"&gt;"$POSTGRES_DB"&lt;/span&gt; --no-owner --exit-on-error &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; backup/n8n-db.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Put the &lt;code&gt;.n8n&lt;/code&gt; folder back into the n8n volume:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose run --rm --no-deps -v &lt;span class="s2"&gt;"$PWD/backup"&lt;/span&gt;:/backup --entrypoint tar n8n xzf /backup/n8n-data.tar.gz -C /home/node
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now check the workflows and credentials with the n8n command line, which runs and exits without starting the server:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose run --rm --no-deps n8n export:workflow --all --pretty &lt;span class="o"&gt;|&lt;/span&gt; grep &lt;span class="s1"&gt;'"name"'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; head
sudo docker compose run --rm --no-deps n8n export:credentials --all --decrypted --pretty &lt;span class="o"&gt;|&lt;/span&gt; grep -c &lt;span class="s1"&gt;'"data"'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The first command lists the names of the workflows and their nodes. The second counts the credentials n8n could open with the key from the backup; the number must match the total number of credentials in your instance. If it prints &lt;code&gt;0&lt;/code&gt; along with &lt;code&gt;Credentials could not be decrypted&lt;/code&gt; or &lt;code&gt;Mismatching encryption keys&lt;/code&gt;, the key in the backup doesn't match the database, and this backup wouldn't restore your credentials. Neither command writes anything to disk, but the second one reads the decrypted credentials: don't swap &lt;code&gt;grep -c&lt;/code&gt; for something that prints them.&lt;/p&gt;

&lt;p&gt;Finally, remove the test environment. Here, and only here, &lt;code&gt;-v&lt;/code&gt; is what you want, because it deletes the test volumes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/n8n-restore-test
sudo docker compose down -v
&lt;span class="nb"&gt;cd&lt;/span&gt; ~ &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; rm -rf ~/n8n-restore-test
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Check the folder before &lt;code&gt;down -v&lt;/code&gt;.&lt;/strong&gt; The command deletes the volumes of the project in the folder you're in. In &lt;code&gt;~/n8n&lt;/code&gt;, it would delete the production database and key.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Repeat the test from time to time, for example after each n8n update or once a month.&lt;/p&gt;

&lt;h2&gt;
  
  
  Restore on a new VPS
&lt;/h2&gt;

&lt;p&gt;If you lose the VPS, the path is the same as the test, with the production stack:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Install Docker and rclone on the new VPS, as in the install guide and in this one.&lt;/li&gt;
&lt;li&gt;Recreate both rclone destinations with the same bucket keys and the same two passwords from your password manager.&lt;/li&gt;
&lt;li&gt;Download the latest copy into &lt;code&gt;/home/deploy/n8n/backup&lt;/code&gt; and put &lt;code&gt;env&lt;/code&gt; (renamed to &lt;code&gt;.env&lt;/code&gt;), &lt;code&gt;docker-compose.yml&lt;/code&gt; and &lt;code&gt;Caddyfile&lt;/code&gt; in &lt;code&gt;/home/deploy/n8n&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Start only Postgres, then restore the database and the &lt;code&gt;.n8n&lt;/code&gt; folder with the same commands as the test.&lt;/li&gt;
&lt;li&gt;Point DNS to the new IP and bring the whole stack up with &lt;code&gt;sudo docker compose up -d&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Sign in to the editor with the same account as before and, once you've checked, delete the &lt;code&gt;backup&lt;/code&gt; folder, which holds a copy of the &lt;code&gt;.env&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Next steps
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;If your bucket provider allows it, use a key that can list, read and write but not delete, and turn on bucket versioning or object lock. Retention then moves to a bucket lifecycle rule, and the two &lt;code&gt;rclone&lt;/code&gt; cleanup lines come out of the script. That way, someone who breaks into the VPS can't delete or overwrite the older copies. The key can't be write-only: &lt;code&gt;rclone copy&lt;/code&gt;, &lt;code&gt;cryptcheck&lt;/code&gt; and the restore all need to list and read the bucket.&lt;/li&gt;
&lt;li&gt;Keep the &lt;code&gt;.env&lt;/code&gt; and both rclone passwords in a password manager, off the VPS and outside the bucket.&lt;/li&gt;
&lt;li&gt;For the whole server, not just n8n, a versioned and deduplicated backup, such as restic's, is the next step up.&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>n8n</category>
      <category>backup</category>
      <category>selfhosted</category>
      <category>devops</category>
    </item>
    <item>
      <title>How to install Evolution API on a VPS (Docker, step by step)</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Thu, 19 Nov 2026 11:26:21 +0000</pubDate>
      <link>https://dev.to/nuvits/how-to-install-evolution-api-on-a-vps-docker-step-by-step-2p8a</link>
      <guid>https://dev.to/nuvits/how-to-install-evolution-api-on-a-vps-docker-step-by-step-2p8a</guid>
      <description>&lt;p&gt;This guide runs Evolution API on an Ubuntu 24.04 VPS: the API, PostgreSQL 15, Redis and Caddy in front, with HTTPS. The Compose file starts from the official one and drops the external Dokploy network, which only exists on that panel and would make &lt;code&gt;docker compose up&lt;/code&gt; fail on a plain VPS.&lt;/p&gt;

&lt;h2&gt;
  
  
  What you need
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;An Ubuntu 24.04 64-bit VPS and SSH as a user with &lt;code&gt;sudo&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;A domain where you can create a DNS record. The examples use &lt;code&gt;api.example.com&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;An e-mail address for the certificate's ACME account.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Evolution API's documentation asks for PostgreSQL or MySQL and recommends Redis. This guide uses both. Treat 2 vCPU and 4 GB of RAM as the floor for the API, the database and the cache together. With 4 vCPU and 8 GB there is room for more instances and for the database to grow.&lt;/p&gt;

&lt;p&gt;At Nuvits you can also order the VPS with Docker already installed. Evolution API itself stays with you: the steps below are the path with a domain and HTTPS.&lt;/p&gt;

&lt;h2&gt;
  
  
  Prepare the server
&lt;/h2&gt;

&lt;p&gt;If the VPS arrives with &lt;code&gt;root&lt;/code&gt; access, create a &lt;code&gt;sudo&lt;/code&gt; user and copy your SSH key:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;adduser deploy
usermod -aG sudo deploy
install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
install -m 600 -o deploy -g deploy ~/.ssh/authorized_keys /home/deploy/.ssh/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Open another session as &lt;code&gt;deploy&lt;/code&gt; and confirm the login before closing the &lt;code&gt;root&lt;/code&gt; one. Then allow SSH, HTTP and HTTPS:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443
sudo ufw &lt;span class="nb"&gt;enable&lt;/span&gt;
sudo ufw status
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;ufw enable&lt;/code&gt; asks for confirmation because it can drop SSH. With the port 22 rule already in place, answer &lt;code&gt;y&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Docker bypasses ufw.&lt;/strong&gt; A port published with &lt;code&gt;ports:&lt;/code&gt; is reachable from outside even without a firewall rule. Only Caddy publishes 80 and 443. The API, Postgres and Redis stay on the Compose network, and the API listens on &lt;code&gt;127.0.0.1&lt;/code&gt; only.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Install Docker
&lt;/h2&gt;

&lt;p&gt;At Nuvits you can order the VPS with Docker already installed. In that case, skip to &lt;code&gt;docker compose version&lt;/code&gt; at the end of this section.&lt;/p&gt;

&lt;p&gt;The path Docker's documentation recommends for servers is the official &lt;code&gt;apt&lt;/code&gt; repository:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: &lt;span class="nv"&gt;$(&lt;/span&gt;. /etc/os-release &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"${UBUNTU_CODENAME:-$VERSION_CODENAME}"&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt;
Components: stable
Architectures: &lt;span class="nv"&gt;$(&lt;/span&gt;dpkg --print-architecture&lt;span class="o"&gt;)&lt;/span&gt;
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run hello-world
docker compose version
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The commands use &lt;code&gt;sudo docker&lt;/code&gt;. The &lt;code&gt;docker&lt;/code&gt; group skips &lt;code&gt;sudo&lt;/code&gt;, but Docker's documentation warns that it is equivalent to root.&lt;/p&gt;

&lt;h2&gt;
  
  
  Configure Evolution API
&lt;/h2&gt;

&lt;p&gt;Create the project directory. Its name becomes the volume prefix:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/evolution &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd&lt;/span&gt; ~/evolution
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Generate the global API key. Do not reuse the sample that ships in the repository's &lt;code&gt;.env.example&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;openssl rand -hex 16
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Create the &lt;code&gt;.env&lt;/code&gt; with the key, the public address and the database. &lt;code&gt;SERVER_URL&lt;/code&gt;, &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;, &lt;code&gt;DATABASE_PROVIDER&lt;/code&gt;, &lt;code&gt;DATABASE_CONNECTION_URI&lt;/code&gt;, &lt;code&gt;CACHE_REDIS_ENABLED&lt;/code&gt; and &lt;code&gt;CACHE_REDIS_URI&lt;/code&gt; are in the current &lt;code&gt;.env.example&lt;/code&gt;. &lt;code&gt;POSTGRES_*&lt;/code&gt; feeds the official PostgreSQL image:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ini"&gt;&lt;code&gt;&lt;span class="na"&gt;SERVER_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//api.example.com&lt;/span&gt;
&lt;span class="na"&gt;AUTHENTICATION_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;paste&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;the&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;key&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;here&lt;/span&gt;

&lt;span class="na"&gt;DATABASE_PROVIDER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;postgresql&lt;/span&gt;
&lt;span class="na"&gt;DATABASE_CONNECTION_URI&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;postgresql&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//evolution:paste-the-password@evolution-postgres:5432/evolution_db?schema=evolution_api&lt;/span&gt;
&lt;span class="na"&gt;DATABASE_CONNECTION_CLIENT_NAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;

&lt;span class="na"&gt;CACHE_REDIS_ENABLED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="na"&gt;CACHE_REDIS_URI&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//evolution-redis:6379/6&lt;/span&gt;
&lt;span class="na"&gt;CACHE_REDIS_PREFIX_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;

&lt;span class="na"&gt;POSTGRES_DATABASE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution_db&lt;/span&gt;
&lt;span class="na"&gt;POSTGRES_USERNAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;
&lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;paste&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;the&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;password&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The password in &lt;code&gt;DATABASE_CONNECTION_URI&lt;/code&gt; and &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; must match. If the password contains &lt;code&gt;@&lt;/code&gt;, &lt;code&gt;:&lt;/code&gt;, &lt;code&gt;/&lt;/code&gt; or &lt;code&gt;#&lt;/code&gt;, percent-encode those characters in the URI, or the client reads the address wrong.&lt;/p&gt;

&lt;p&gt;Point &lt;code&gt;api.example.com&lt;/code&gt; at the VPS IPv4 before starting Caddy. Without that, the certificate is not issued.&lt;/p&gt;

&lt;h3&gt;
  
  
  Compose
&lt;/h3&gt;

&lt;p&gt;The file below uses the same images as the &lt;a href="https://github.com/evolution-foundation/evolution-api/blob/main/docker-compose.yaml" rel="noopener noreferrer"&gt;official docker-compose.yaml&lt;/a&gt;: &lt;code&gt;evoapicloud/evolution-api:latest&lt;/code&gt;, &lt;code&gt;postgres:15&lt;/code&gt; and &lt;code&gt;redis:latest&lt;/code&gt;. The &lt;code&gt;dokploy-network&lt;/code&gt; is left out, because it is external and does not exist on a new VPS. The &lt;code&gt;latest&lt;/code&gt; tag is the one the official file uses; to pin a release, replace it with a tag published in the repository before you start.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;container_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evolution_api&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evoapicloud/evolution-api:latest&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;redis&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-postgres&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"127.0.0.1:8080:8080"&lt;/span&gt;
    &lt;span class="na"&gt;env_file&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;.env&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution_instances:/evolution/instances&lt;/span&gt;
    &lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-net&lt;/span&gt;

  &lt;span class="na"&gt;redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;container_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evolution_redis&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;redis:latest&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;redis-server --port 6379 --appendonly yes&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution_redis:/data&lt;/span&gt;
    &lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;evolution-net&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;aliases&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-redis&lt;/span&gt;

  &lt;span class="na"&gt;evolution-postgres&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;container_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evolution_postgres&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:15&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_DATABASE}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_USER&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_USERNAME}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_PASSWORD}&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"postgres"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-c"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"max_connections=1000"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;postgres_data:/var/lib/postgresql/data&lt;/span&gt;
    &lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-net&lt;/span&gt;

  &lt;span class="na"&gt;caddy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;caddy:2.10&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"80:80"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"443:443"&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;./Caddyfile:/etc/caddy/Caddyfile:ro&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;caddy_data:/data&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;caddy_config:/config&lt;/span&gt;
    &lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-net&lt;/span&gt;

&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution_instances&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution_redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;postgres_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;caddy_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;caddy_config&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;

&lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution-net&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evolution-net&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Caddy issues and renews the certificate. Replace the domain and the e-mail:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;api.example.com {
    reverse_proxy evolution_api:8080
    tls you@example.com
}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Start the stack and follow the API until it answers:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f api
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The API container applies the Prisma migrations on startup, according to &lt;code&gt;DATABASE_PROVIDER&lt;/code&gt;. If the certificate is not issued, check DNS and ports 80 and 443, then run &lt;code&gt;sudo docker compose restart caddy&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;From outside the VPS:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -fsS https://api.example.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The response does not have to be an HTML page. What matters is valid TLS and the API being up. Calls use the &lt;code&gt;apikey&lt;/code&gt; header with the value of &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;, as the API documentation describes.&lt;/p&gt;

&lt;h2&gt;
  
  
  Create the first instance
&lt;/h2&gt;

&lt;p&gt;Evolution API connects through WhatsApp Web, using the Baileys library, or through Meta's official API. Its own documentation warns that the WhatsApp Web connection may have limitations compared with the official API.&lt;/p&gt;

&lt;p&gt;With the API up, create the instance through the documented endpoint (&lt;code&gt;POST /instance/create&lt;/code&gt;) and read the QR code from &lt;code&gt;GET /instance/connect/{instance}&lt;/code&gt;. Open WhatsApp on the phone, under Linked devices, and scan the code. &lt;code&gt;SERVER_URL&lt;/code&gt; has to be the public &lt;code&gt;https&lt;/code&gt; address, or webhooks point at &lt;code&gt;localhost&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The repository also publishes &lt;code&gt;evoapicloud/evolution-manager&lt;/code&gt;, a web panel. It is not in this Compose file: publish it on &lt;code&gt;127.0.0.1&lt;/code&gt; only and add another Caddy site if you want it. Without that, port 3000 from the official example is open to the internet.&lt;/p&gt;

&lt;h2&gt;
  
  
  Update and back up
&lt;/h2&gt;

&lt;p&gt;Stop the API, dump the database and the instances directory, and copy both off the VPS:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/evolution
sudo docker compose stop api
sudo docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T evolution-postgres pg_dump -U evolution evolution_db &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; evolution-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql
sudo docker run --rm -v evolution_evolution_instances:/from -v &lt;span class="s2"&gt;"$PWD"&lt;/span&gt;:/backup ubuntu:24.04 tar czf /backup/evolution-instances-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.tar.gz -C /from .
sudo docker compose start api
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The volume name gets the project directory as a prefix (&lt;code&gt;evolution_&lt;/code&gt;). Check &lt;code&gt;sudo docker volume ls&lt;/code&gt; if &lt;code&gt;tar&lt;/code&gt; says the volume does not exist. Copy the &lt;code&gt;.sql&lt;/code&gt;, the archive and the &lt;code&gt;.env&lt;/code&gt; to your own machine. A copy that stays only on the VPS disk is lost with it.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Never run &lt;code&gt;docker compose down -v&lt;/code&gt; in this directory.&lt;/strong&gt; &lt;code&gt;-v&lt;/code&gt; deletes the volumes, including the WhatsApp sessions and the database.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;To update, change the image tag if you pinned one, or pull &lt;code&gt;latest&lt;/code&gt;, and recreate only the API:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose pull api
sudo docker compose up -d api
sudo docker compose logs -f api
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Read the release notes in the repository first. Pulling &lt;code&gt;latest&lt;/code&gt; does not tell you when a change needs a manual database step.&lt;/p&gt;

&lt;h2&gt;
  
  
  Next step
&lt;/h2&gt;

&lt;p&gt;The VPS, the domain and the certificate stay with you. If you do not have the server yet, see the plans at &lt;a href="https://nuvits.net/en/evolution-api-vps" rel="noopener noreferrer"&gt;VPS for Evolution API&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;Originally published at &lt;a href="https://nuvits.net/en/blog/install-evolution-api-docker-vps" rel="noopener noreferrer"&gt;https://nuvits.net/en/blog/install-evolution-api-docker-vps&lt;/a&gt;&lt;/p&gt;

</description>
      <category>whatsapp</category>
      <category>docker</category>
      <category>selfhosted</category>
      <category>api</category>
    </item>
    <item>
      <title>Como instalar a Evolution API em uma VPS (passo a passo com Docker)</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Thu, 19 Nov 2026 11:25:34 +0000</pubDate>
      <link>https://dev.to/nuvits/como-instalar-a-evolution-api-em-uma-vps-passo-a-passo-com-docker-2dnd</link>
      <guid>https://dev.to/nuvits/como-instalar-a-evolution-api-em-uma-vps-passo-a-passo-com-docker-2dnd</guid>
      <description>&lt;p&gt;Este guia sobe a Evolution API numa VPS Ubuntu 24.04: a API, o PostgreSQL 15, o Redis e o Caddy na frente, com HTTPS. O Compose parte do arquivo oficial e tira a rede externa do Dokploy, que só existe nesse painel e faria o &lt;code&gt;docker compose up&lt;/code&gt; falhar numa VPS comum.&lt;/p&gt;

&lt;h2&gt;
  
  
  O que você vai precisar
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Uma VPS com Ubuntu 24.04 de 64 bits e SSH com um usuário que tenha &lt;code&gt;sudo&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Um domínio em que você consiga criar um registro DNS. Os exemplos usam &lt;code&gt;api.example.com&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Um e-mail para a conta ACME do certificado.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A documentação da Evolution API pede PostgreSQL ou MySQL e recomenda o Redis. Este guia usa os dois. Trate 2 vCPU e 4 GB de RAM como piso para a API, o banco e o cache juntos. Com 4 vCPU e 8 GB sobra espaço para mais instâncias e para o banco crescer.&lt;/p&gt;

&lt;p&gt;Se você só quer experimentar, a Nuvits também entrega a VPS com o Docker já instalado na contratação. A Evolution API em si continua por sua conta: o passo a passo abaixo é o caminho com domínio e HTTPS.&lt;/p&gt;

&lt;h2&gt;
  
  
  Preparar o servidor
&lt;/h2&gt;

&lt;p&gt;Se a VPS chega com acesso de &lt;code&gt;root&lt;/code&gt;, crie um usuário com &lt;code&gt;sudo&lt;/code&gt; e copie a sua chave SSH:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;adduser deploy
usermod -aG sudo deploy
install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
install -m 600 -o deploy -g deploy ~/.ssh/authorized_keys /home/deploy/.ssh/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Abra outra sessão como &lt;code&gt;deploy&lt;/code&gt; e confira o login antes de fechar a de &lt;code&gt;root&lt;/code&gt;. Depois libere SSH, HTTP e HTTPS:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443
sudo ufw &lt;span class="nb"&gt;enable&lt;/span&gt;
sudo ufw status
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;ufw enable&lt;/code&gt; pede confirmação porque pode derrubar o SSH. Com a regra da porta 22 já criada, responda &lt;code&gt;y&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;O Docker passa por cima do ufw.&lt;/strong&gt; Uma porta publicada com &lt;code&gt;ports:&lt;/code&gt; fica acessível de fora mesmo sem regra no firewall. Por isso só o Caddy publica 80 e 443. A API, o Postgres e o Redis ficam na rede interna do Compose, e a API só escuta em &lt;code&gt;127.0.0.1&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Instalar o Docker
&lt;/h2&gt;

&lt;p&gt;Na Nuvits, dá para pedir a VPS com o Docker já instalado. Nesse caso, pule para o &lt;code&gt;docker compose version&lt;/code&gt; no fim desta seção.&lt;/p&gt;

&lt;p&gt;O caminho que a documentação do Docker indica para servidores é o repositório &lt;code&gt;apt&lt;/code&gt; oficial:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: &lt;span class="nv"&gt;$(&lt;/span&gt;. /etc/os-release &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"${UBUNTU_CODENAME:-$VERSION_CODENAME}"&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt;
Components: stable
Architectures: &lt;span class="nv"&gt;$(&lt;/span&gt;dpkg --print-architecture&lt;span class="o"&gt;)&lt;/span&gt;
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run hello-world
docker compose version
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Os comandos usam &lt;code&gt;sudo docker&lt;/code&gt;. O grupo &lt;code&gt;docker&lt;/code&gt; dispensa o &lt;code&gt;sudo&lt;/code&gt;, mas a documentação do Docker avisa que ele equivale a root.&lt;/p&gt;

&lt;h2&gt;
  
  
  Configurar a Evolution API
&lt;/h2&gt;

&lt;p&gt;Crie a pasta do projeto. O nome dela vira prefixo dos volumes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/evolution &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd&lt;/span&gt; ~/evolution
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Gere a chave global da API. Não reutilize o exemplo que vem no &lt;code&gt;.env.example&lt;/code&gt; do repositório:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;openssl rand -hex 16
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Crie o &lt;code&gt;.env&lt;/code&gt; com a chave, o endereço público e o banco. Os nomes &lt;code&gt;SERVER_URL&lt;/code&gt;, &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;, &lt;code&gt;DATABASE_PROVIDER&lt;/code&gt;, &lt;code&gt;DATABASE_CONNECTION_URI&lt;/code&gt;, &lt;code&gt;CACHE_REDIS_ENABLED&lt;/code&gt; e &lt;code&gt;CACHE_REDIS_URI&lt;/code&gt; estão no &lt;code&gt;.env.example&lt;/code&gt; atual do repositório. &lt;code&gt;POSTGRES_*&lt;/code&gt; alimenta a imagem oficial do PostgreSQL:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ini"&gt;&lt;code&gt;&lt;span class="na"&gt;SERVER_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//api.example.com&lt;/span&gt;
&lt;span class="na"&gt;AUTHENTICATION_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;cole&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;aqui&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;chave&lt;/span&gt;

&lt;span class="na"&gt;DATABASE_PROVIDER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;postgresql&lt;/span&gt;
&lt;span class="na"&gt;DATABASE_CONNECTION_URI&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;postgresql&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//evolution:cole-a-senha@evolution-postgres:5432/evolution_db?schema=evolution_api&lt;/span&gt;
&lt;span class="na"&gt;DATABASE_CONNECTION_CLIENT_NAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;

&lt;span class="na"&gt;CACHE_REDIS_ENABLED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="na"&gt;CACHE_REDIS_URI&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//evolution-redis:6379/6&lt;/span&gt;
&lt;span class="na"&gt;CACHE_REDIS_PREFIX_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;

&lt;span class="na"&gt;POSTGRES_DATABASE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution_db&lt;/span&gt;
&lt;span class="na"&gt;POSTGRES_USERNAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;
&lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;cole&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;senha&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A senha do &lt;code&gt;DATABASE_CONNECTION_URI&lt;/code&gt; e a de &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; precisam ser a mesma. Se a senha tiver &lt;code&gt;@&lt;/code&gt;, &lt;code&gt;:&lt;/code&gt;, &lt;code&gt;/&lt;/code&gt; ou &lt;code&gt;#&lt;/code&gt;, troque esses caracteres pelo código percentual na URI, senão o cliente lê o endereço errado.&lt;/p&gt;

&lt;p&gt;Aponte &lt;code&gt;api.example.com&lt;/code&gt; para o IPv4 da VPS antes de subir o Caddy. Sem isso o certificado não sai.&lt;/p&gt;

&lt;h3&gt;
  
  
  Compose
&lt;/h3&gt;

&lt;p&gt;O arquivo abaixo usa as mesmas imagens do &lt;a href="https://github.com/evolution-foundation/evolution-api/blob/main/docker-compose.yaml" rel="noopener noreferrer"&gt;docker-compose.yaml oficial&lt;/a&gt;: &lt;code&gt;evoapicloud/evolution-api:latest&lt;/code&gt;, &lt;code&gt;postgres:15&lt;/code&gt; e &lt;code&gt;redis:latest&lt;/code&gt;. A rede &lt;code&gt;dokploy-network&lt;/code&gt; ficou de fora, porque ela é externa e não existe numa VPS recém-criada. A tag &lt;code&gt;latest&lt;/code&gt; é a que o arquivo oficial usa; para travar uma versão, troque pela tag publicada no repositório antes de subir.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;container_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evolution_api&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evoapicloud/evolution-api:latest&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;redis&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-postgres&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"127.0.0.1:8080:8080"&lt;/span&gt;
    &lt;span class="na"&gt;env_file&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;.env&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution_instances:/evolution/instances&lt;/span&gt;
    &lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-net&lt;/span&gt;

  &lt;span class="na"&gt;redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;container_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evolution_redis&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;redis:latest&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;redis-server --port 6379 --appendonly yes&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution_redis:/data&lt;/span&gt;
    &lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;evolution-net&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;aliases&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-redis&lt;/span&gt;

  &lt;span class="na"&gt;evolution-postgres&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;container_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evolution_postgres&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:15&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_DATABASE}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_USER&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_USERNAME}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_PASSWORD}&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"postgres"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-c"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"max_connections=1000"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;postgres_data:/var/lib/postgresql/data&lt;/span&gt;
    &lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-net&lt;/span&gt;

  &lt;span class="na"&gt;caddy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;caddy:2.10&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"80:80"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"443:443"&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;./Caddyfile:/etc/caddy/Caddyfile:ro&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;caddy_data:/data&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;caddy_config:/config&lt;/span&gt;
    &lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-net&lt;/span&gt;

&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution_instances&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution_redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;postgres_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;caddy_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;caddy_config&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;

&lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution-net&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evolution-net&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O Caddy emite e renova o certificado. Troque o domínio e o e-mail:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;api.example.com {
    reverse_proxy evolution_api:8080
    tls voce@example.com
}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Suba a stack e acompanhe a API até ela responder:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f api
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O contêiner da API aplica as migrações do Prisma na subida, conforme o &lt;code&gt;DATABASE_PROVIDER&lt;/code&gt;. Se o certificado não sair, confira o DNS e as portas 80 e 443 e rode &lt;code&gt;sudo docker compose restart caddy&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;De fora da VPS:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -fsS https://api.example.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A resposta não precisa ser uma página HTML. O que importa é o TLS válido e a API no ar. As chamadas usam o cabeçalho &lt;code&gt;apikey&lt;/code&gt; com o valor de &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;, como a documentação da API descreve.&lt;/p&gt;

&lt;h2&gt;
  
  
  Criar a primeira instância
&lt;/h2&gt;

&lt;p&gt;A Evolution API conecta pelo WhatsApp Web, com a biblioteca Baileys, ou pela API oficial da Meta. A própria documentação avisa que a conexão pelo WhatsApp Web pode ter limitações em relação à API oficial.&lt;/p&gt;

&lt;p&gt;Com a API no ar, crie a instância pelo endpoint documentado (&lt;code&gt;POST /instance/create&lt;/code&gt;) e leia o QR Code em &lt;code&gt;GET /instance/connect/{instancia}&lt;/code&gt;. Abra o WhatsApp no celular, em Aparelhos conectados, e escaneie o código. O &lt;code&gt;SERVER_URL&lt;/code&gt; precisa ser o endereço público com &lt;code&gt;https&lt;/code&gt;, senão os webhooks saem apontando para &lt;code&gt;localhost&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;O repositório também publica a imagem &lt;code&gt;evoapicloud/evolution-manager&lt;/code&gt;, um painel web. Ela não entra neste Compose: publique só em &lt;code&gt;127.0.0.1&lt;/code&gt; e ponha outro site no Caddy se quiser usá-la. Sem isso, a porta 3000 do exemplo oficial fica aberta na internet.&lt;/p&gt;

&lt;h2&gt;
  
  
  Atualizar e fazer backup
&lt;/h2&gt;

&lt;p&gt;Pare a API, grave o banco e a pasta de instâncias, e copie os dois para fora da VPS:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/evolution
sudo docker compose stop api
sudo docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T evolution-postgres pg_dump -U evolution evolution_db &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; evolution-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql
sudo docker run --rm -v evolution_evolution_instances:/from -v &lt;span class="s2"&gt;"$PWD"&lt;/span&gt;:/backup ubuntu:24.04 tar czf /backup/evolution-instances-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.tar.gz -C /from .
sudo docker compose start api
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O nome do volume ganha o prefixo da pasta do projeto (&lt;code&gt;evolution_&lt;/code&gt;). Confira com &lt;code&gt;sudo docker volume ls&lt;/code&gt; se o &lt;code&gt;tar&lt;/code&gt; reclamar que o volume não existe. Copie o &lt;code&gt;.sql&lt;/code&gt;, o arquivo e o &lt;code&gt;.env&lt;/code&gt; para a sua máquina. Uma cópia que fica só no disco da VPS se perde junto com ela.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Nunca rode &lt;code&gt;docker compose down -v&lt;/code&gt; nesta pasta.&lt;/strong&gt; O &lt;code&gt;-v&lt;/code&gt; apaga os volumes, inclusive as sessões do WhatsApp e o banco.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Para atualizar, troque a tag da imagem se você tiver travado uma versão, ou rode o pull da &lt;code&gt;latest&lt;/code&gt;, e recrie só a API:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose pull api
sudo docker compose up -d api
sudo docker compose logs -f api
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Leia as notas da versão no repositório antes. O pull da &lt;code&gt;latest&lt;/code&gt; não avisa quando uma mudança exige um passo manual no banco.&lt;/p&gt;

&lt;h2&gt;
  
  
  Próximo passo
&lt;/h2&gt;

&lt;p&gt;A VPS, o domínio e o certificado ficam com você. Se ainda não tem o servidor, veja os planos em &lt;a href="https://nuvits.net/vps-para-evolution-api" rel="noopener noreferrer"&gt;VPS para Evolution API&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;Publicado originalmente em &lt;a href="https://nuvits.net/blog/como-instalar-evolution-api-docker-vps" rel="noopener noreferrer"&gt;https://nuvits.net/blog/como-instalar-evolution-api-docker-vps&lt;/a&gt;&lt;/p&gt;

</description>
      <category>braziliandevs</category>
      <category>portugues</category>
      <category>whatsapp</category>
      <category>docker</category>
    </item>
    <item>
      <title>The Docker port stays open with ufw</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Thu, 19 Nov 2026 11:24:26 +0000</pubDate>
      <link>https://dev.to/nuvits/the-docker-port-stays-open-with-ufw-328</link>
      <guid>https://dev.to/nuvits/the-docker-port-stays-open-with-ufw-328</guid>
      <description>&lt;p&gt;A port published with &lt;code&gt;docker run -p&lt;/code&gt; stays reachable from outside even with ufw active and a &lt;code&gt;deny&lt;/code&gt; rule on that port. The test below ran on 18 November 2026 on Ubuntu 24.04.5 LTS, with Docker Engine 29.10.0 and ufw 0.36.2. The request came from another network namespace, with source 203.0.113.10, which is not in the private ranges.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://docs.docker.com/engine/network/packet-filtering-firewalls/#docker-and-ufw" rel="noopener noreferrer"&gt;Docker docs&lt;/a&gt; describe why: Docker diverts the packet in the &lt;code&gt;nat&lt;/code&gt; table before the &lt;code&gt;INPUT&lt;/code&gt; and &lt;code&gt;OUTPUT&lt;/code&gt; chains, which are the ones ufw uses. The &lt;a href="https://coolify.io/docs/knowledge-base/server/firewall" rel="noopener noreferrer"&gt;Coolify firewall docs&lt;/a&gt; repeat the warning and point at &lt;code&gt;ufw-docker&lt;/code&gt; when the VPS has no firewall at the provider.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the test published
&lt;/h2&gt;

&lt;p&gt;The container is the official Apache, tag &lt;code&gt;httpd:2.4-alpine&lt;/code&gt;, digest &lt;code&gt;sha256:32bd0639bcc4917ef1fd9363a1d9dd2dd9c498565118b062a10d51e43a5c3a24&lt;/code&gt;. Port 80 in the container is on port 8088 of the server:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker pull httpd:2.4-alpine
sudo docker run -d --name porta-teste -p 8088:80 httpd:2.4-alpine
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;ufw was left like this, with 8088 explicitly denied. The forwarding policy was deny as well:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw allow 22/tcp
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw --force &lt;span class="nb"&gt;enable&lt;/span&gt;
sudo ufw deny 8088/tcp
sudo ufw status verbose
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), deny (routed)

     To                         Action      From
     --                         ------      ----
[ 1] 22/tcp                     ALLOW IN    Anywhere
[ 2] 8088/tcp                   DENY IN     Anywhere
[ 3] 22/tcp (v6)                ALLOW IN    Anywhere (v6)
[ 4] 8088/tcp (v6)              DENY IN     Anywhere (v6)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  The request that should not have passed
&lt;/h2&gt;

&lt;p&gt;You cannot see this hole with &lt;code&gt;curl&lt;/code&gt; to &lt;code&gt;127.0.0.1&lt;/code&gt; on the server itself. The request has to arrive from outside. In the lab, a &lt;code&gt;wan&lt;/code&gt; namespace played that part. The address 203.0.113.0/24 is from the documentation range, and the ping between the two sides answered.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ip netns add wan
sudo ip link add veth-wan &lt;span class="nb"&gt;type&lt;/span&gt; veth peer name veth-host
sudo ip link &lt;span class="nb"&gt;set&lt;/span&gt; veth-wan netns wan
sudo ip addr add 203.0.113.1/24 dev veth-host
sudo ip link &lt;span class="nb"&gt;set&lt;/span&gt; veth-host up
sudo ip netns &lt;span class="nb"&gt;exec&lt;/span&gt; wan ip link &lt;span class="nb"&gt;set&lt;/span&gt; lo up
sudo ip netns &lt;span class="nb"&gt;exec&lt;/span&gt; wan ip addr add 203.0.113.10/24 dev veth-wan
sudo ip netns &lt;span class="nb"&gt;exec&lt;/span&gt; wan ip link &lt;span class="nb"&gt;set&lt;/span&gt; veth-wan up
sudo ip netns &lt;span class="nb"&gt;exec&lt;/span&gt; wan ip route add default via 203.0.113.1
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The request, leaving from 203.0.113.10:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ip netns &lt;span class="nb"&gt;exec&lt;/span&gt; wan curl -sS -D - -o /dev/null --max-time 8 http://203.0.113.1:8088/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The response, with ufw active and the &lt;code&gt;DENY&lt;/code&gt; rule on 8088:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;HTTP/1.1 200 OK
Server: Apache/2.4.71 (Unix)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On your VPS, the equivalent is to run the same &lt;code&gt;curl&lt;/code&gt; from another computer on the internet, replacing &lt;code&gt;203.0.113.1&lt;/code&gt; with the public IPv4.&lt;/p&gt;

&lt;h2&gt;
  
  
  The fix
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;ufw-docker&lt;/code&gt; writes rules in the &lt;code&gt;DOCKER-USER&lt;/code&gt; chain, which Docker consults before it accepts the forward. The tested copy is commit &lt;code&gt;020a8699f95592561f254d8d4ad1bb40d401dfc7&lt;/code&gt;. The script's SHA-256 was &lt;code&gt;643e56b080567c567b4aa28650196849b2a2da5dd0473fd3e5216b0886035ab0&lt;/code&gt;. The project README points at &lt;code&gt;master&lt;/code&gt;; the command below pins the file this test ran.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo curl -fsSL -o /usr/local/bin/ufw-docker \
  https://raw.githubusercontent.com/chaifeng/ufw-docker/020a8699f95592561f254d8d4ad1bb40d401dfc7/ufw-docker
sudo chmod 755 /usr/local/bin/ufw-docker
sha256sum /usr/local/bin/ufw-docker
sudo ufw-docker install
sudo ufw reload
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;install&lt;/code&gt; showed the diff of &lt;code&gt;/etc/ufw/after.rules&lt;/code&gt; and of &lt;code&gt;/etc/ufw/after6.rules&lt;/code&gt;, kept a copy of each file and asked for &lt;code&gt;sudo systemctl restart ufw&lt;/code&gt;. &lt;code&gt;sudo ufw reload&lt;/code&gt; was enough for the block to apply. The same &lt;code&gt;curl&lt;/code&gt; from outside then failed:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;curl: (28) Connection timed out after 8002 milliseconds
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;From the server itself, &lt;code&gt;curl http://127.0.0.1:8088/&lt;/code&gt; kept answering &lt;code&gt;HTTP/1.1 200 OK&lt;/code&gt;. The service did not go down. What closed was new access coming from outside.&lt;/p&gt;

&lt;p&gt;The rules written by &lt;code&gt;install&lt;/code&gt; return early for traffic sourced from &lt;code&gt;10.0.0.0/8&lt;/code&gt;, &lt;code&gt;172.16.0.0/12&lt;/code&gt; and &lt;code&gt;192.168.0.0/16&lt;/code&gt;. A &lt;code&gt;curl&lt;/code&gt; made from an address in those ranges, or from the server itself, does not show whether the internet was blocked. The timeout in this test came from 203.0.113.10, outside them.&lt;/p&gt;

&lt;p&gt;To open on purpose, the rule uses the container port. Here Apache listens on 80, and the host shows 8088. The rule is on 80:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw route allow proto tcp from any to any port 80
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;ufw status numbered&lt;/code&gt; then had &lt;code&gt;80/tcp ALLOW FWD&lt;/code&gt; and kept &lt;code&gt;8088/tcp DENY IN&lt;/code&gt;. Even so, the outside &lt;code&gt;curl&lt;/code&gt; to port 8088 again received &lt;code&gt;HTTP/1.1 200 OK&lt;/code&gt; with &lt;code&gt;Server: Apache/2.4.71 (Unix)&lt;/code&gt;. The &lt;code&gt;DENY IN&lt;/code&gt; on the host port is not what decides.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;ufw allow 8088/tcp&lt;/code&gt; is not the container's rule.&lt;/strong&gt; That rule goes into the host's input chain. The packet Docker published does not pass through it. What opens the port is &lt;code&gt;ufw route allow&lt;/code&gt; on the port the process listens on inside the container.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  On Coolify
&lt;/h2&gt;

&lt;p&gt;The same hole shows up on the panel. With ufw active and no rule for port 8000, &lt;code&gt;http://203.0.113.1:8000/&lt;/code&gt; still answered &lt;code&gt;HTTP/1.1 302 Found&lt;/code&gt; to &lt;code&gt;/login&lt;/code&gt;. After &lt;code&gt;ufw-docker&lt;/code&gt; and &lt;code&gt;ufw reload&lt;/code&gt;, that request started timing out, the same as Apache.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;docker ps&lt;/code&gt; shows &lt;code&gt;0.0.0.0:8000-&amp;gt;8080/tcp&lt;/code&gt; on the Coolify container. The rule that reopened the panel was on 8080, not on 8000:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw route allow proto tcp from any to any port 8080
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The response went back to &lt;code&gt;HTTP/1.1 302 Found&lt;/code&gt; to &lt;code&gt;/login&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Ports 80 and 443 of the proxy and ports 6001 and 6002 follow the same rule: the port in &lt;code&gt;route allow&lt;/code&gt; is the container's. The list this test opened, and what each one answered, is in &lt;a href="https://nuvits.net/en/blog/install-coolify-ubuntu-vps" rel="noopener noreferrer"&gt;How to install Coolify on an Ubuntu VPS&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;If the VPS has a firewall in the provider's panel, use that firewall and keep ufw as a second layer. It drops the packet before Docker. The n8n install guide avoids the problem another way: only Caddy publishes a port, and the rest stays on Compose's internal network. The steps are &lt;a href="https://nuvits.net/en/blog/install-n8n-docker-vps" rel="noopener noreferrer"&gt;How to install n8n with Docker on a VPS&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What to check
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;From another computer, the published port stops connecting after &lt;code&gt;ufw reload&lt;/code&gt;. A timeout is a block. &lt;code&gt;200&lt;/code&gt; is an open port.&lt;/li&gt;
&lt;li&gt;On the server itself, &lt;code&gt;curl http://127.0.0.1:PORT/&lt;/code&gt; can still answer 200. That does not prove the internet can reach the port, and it does not prove it stopped reaching it.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;ufw status&lt;/code&gt; shows &lt;code&gt;ALLOW FWD&lt;/code&gt; on the container port when the opening is the &lt;code&gt;ufw-docker&lt;/code&gt; one. A &lt;code&gt;DENY IN&lt;/code&gt; on the host port can stay in the list and not change the result.&lt;/li&gt;
&lt;li&gt;Keep SSH open in a session that is already connected until you confirm access from another session. The &lt;code&gt;ufw allow 22/tcp&lt;/code&gt; rule in this test stayed in place, and the session continued.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The plan beside this article covers a VPS where this Docker runs. If you are still choosing the machine, start at &lt;a href="https://nuvits.net/en/docker-vps" rel="noopener noreferrer"&gt;Docker VPS&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;Originally published at &lt;a href="https://nuvits.net/en/blog/docker-port-still-open-with-ufw" rel="noopener noreferrer"&gt;https://nuvits.net/en/blog/docker-port-still-open-with-ufw&lt;/a&gt;&lt;/p&gt;

</description>
      <category>docker</category>
      <category>security</category>
      <category>linux</category>
      <category>devops</category>
    </item>
    <item>
      <title>A porta do Docker continua aberta com o ufw</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Thu, 19 Nov 2026 11:24:13 +0000</pubDate>
      <link>https://dev.to/nuvits/a-porta-do-docker-continua-aberta-com-o-ufw-41pe</link>
      <guid>https://dev.to/nuvits/a-porta-do-docker-continua-aberta-com-o-ufw-41pe</guid>
      <description>&lt;p&gt;Uma porta publicada com &lt;code&gt;docker run -p&lt;/code&gt; continua acessível de fora mesmo com o ufw ativo e uma regra &lt;code&gt;deny&lt;/code&gt; nessa porta. O teste abaixo foi feito em 18/11/2026 no Ubuntu 24.04.5 LTS, com o Docker Engine 29.10.0 e o ufw 0.36.2. O pedido veio de outro namespace de rede, com origem 203.0.113.10, que não está nas faixas privadas.&lt;/p&gt;

&lt;p&gt;A &lt;a href="https://docs.docker.com/engine/network/packet-filtering-firewalls/#docker-and-ufw" rel="noopener noreferrer"&gt;documentação do Docker&lt;/a&gt; descreve o motivo: o Docker desvia o pacote na tabela &lt;code&gt;nat&lt;/code&gt; antes das cadeias &lt;code&gt;INPUT&lt;/code&gt; e &lt;code&gt;OUTPUT&lt;/code&gt;, que são as que o ufw usa. A &lt;a href="https://coolify.io/docs/knowledge-base/server/firewall" rel="noopener noreferrer"&gt;documentação de firewall do Coolify&lt;/a&gt; repete o aviso e aponta o &lt;code&gt;ufw-docker&lt;/code&gt; quando a VPS não tem firewall no provedor.&lt;/p&gt;

&lt;h2&gt;
  
  
  O que o teste publicou
&lt;/h2&gt;

&lt;p&gt;O contêiner é o Apache oficial, tag &lt;code&gt;httpd:2.4-alpine&lt;/code&gt;, digest &lt;code&gt;sha256:32bd0639bcc4917ef1fd9363a1d9dd2dd9c498565118b062a10d51e43a5c3a24&lt;/code&gt;. A porta 80 do contêiner fica na porta 8088 do servidor:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker pull httpd:2.4-alpine
sudo docker run -d --name porta-teste -p 8088:80 httpd:2.4-alpine
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O ufw ficou assim, com a 8088 explicitamente negada. A política de encaminhamento também era deny:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw allow 22/tcp
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw --force &lt;span class="nb"&gt;enable&lt;/span&gt;
sudo ufw deny 8088/tcp
sudo ufw status verbose
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), deny (routed)

     To                         Action      From
     --                         ------      ----
[ 1] 22/tcp                     ALLOW IN    Anywhere
[ 2] 8088/tcp                   DENY IN     Anywhere
[ 3] 22/tcp (v6)                ALLOW IN    Anywhere (v6)
[ 4] 8088/tcp (v6)              DENY IN     Anywhere (v6)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  O pedido que não deveria passar
&lt;/h2&gt;

&lt;p&gt;Não dá para ver esse furo com &lt;code&gt;curl&lt;/code&gt; em &lt;code&gt;127.0.0.1&lt;/code&gt; no próprio servidor. O pedido precisa chegar de fora. No laboratório, um namespace &lt;code&gt;wan&lt;/code&gt; fez esse papel. O endereço 203.0.113.0/24 é da faixa de documentação, e o ping entre os dois lados respondeu.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ip netns add wan
sudo ip link add veth-wan &lt;span class="nb"&gt;type&lt;/span&gt; veth peer name veth-host
sudo ip link &lt;span class="nb"&gt;set&lt;/span&gt; veth-wan netns wan
sudo ip addr add 203.0.113.1/24 dev veth-host
sudo ip link &lt;span class="nb"&gt;set&lt;/span&gt; veth-host up
sudo ip netns &lt;span class="nb"&gt;exec&lt;/span&gt; wan ip link &lt;span class="nb"&gt;set&lt;/span&gt; lo up
sudo ip netns &lt;span class="nb"&gt;exec&lt;/span&gt; wan ip addr add 203.0.113.10/24 dev veth-wan
sudo ip netns &lt;span class="nb"&gt;exec&lt;/span&gt; wan ip link &lt;span class="nb"&gt;set&lt;/span&gt; veth-wan up
sudo ip netns &lt;span class="nb"&gt;exec&lt;/span&gt; wan ip route add default via 203.0.113.1
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O pedido, saindo de 203.0.113.10:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ip netns &lt;span class="nb"&gt;exec&lt;/span&gt; wan curl -sS -D - -o /dev/null --max-time 8 http://203.0.113.1:8088/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A resposta, com o ufw ativo e a regra &lt;code&gt;DENY&lt;/code&gt; na 8088:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;HTTP/1.1 200 OK
Server: Apache/2.4.71 (Unix)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Na sua VPS, o equivalente é rodar o mesmo &lt;code&gt;curl&lt;/code&gt; de outro computador na internet, trocando &lt;code&gt;203.0.113.1&lt;/code&gt; pelo IPv4 público.&lt;/p&gt;

&lt;h2&gt;
  
  
  A correção
&lt;/h2&gt;

&lt;p&gt;O &lt;code&gt;ufw-docker&lt;/code&gt; grava regras na cadeia &lt;code&gt;DOCKER-USER&lt;/code&gt;, que o Docker consulta antes de aceitar o encaminhamento. A cópia testada é o commit &lt;code&gt;020a8699f95592561f254d8d4ad1bb40d401dfc7&lt;/code&gt;. O SHA-256 do script foi &lt;code&gt;643e56b080567c567b4aa28650196849b2a2da5dd0473fd3e5216b0886035ab0&lt;/code&gt;. O README do projeto aponta para &lt;code&gt;master&lt;/code&gt;; o comando abaixo trava o arquivo que este teste executou.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo curl -fsSL -o /usr/local/bin/ufw-docker \
  https://raw.githubusercontent.com/chaifeng/ufw-docker/020a8699f95592561f254d8d4ad1bb40d401dfc7/ufw-docker
sudo chmod 755 /usr/local/bin/ufw-docker
sha256sum /usr/local/bin/ufw-docker
sudo ufw-docker install
sudo ufw reload
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;install&lt;/code&gt; mostrou o diff de &lt;code&gt;/etc/ufw/after.rules&lt;/code&gt; e de &lt;code&gt;/etc/ufw/after6.rules&lt;/code&gt;, guardou uma cópia de cada arquivo e pediu &lt;code&gt;sudo systemctl restart ufw&lt;/code&gt;. O &lt;code&gt;sudo ufw reload&lt;/code&gt; bastou para o bloqueio valer. O mesmo &lt;code&gt;curl&lt;/code&gt; de fora passou a falhar:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;curl: (28) Connection timed out after 8002 milliseconds
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Do próprio servidor, &lt;code&gt;curl http://127.0.0.1:8088/&lt;/code&gt; continuou respondendo &lt;code&gt;HTTP/1.1 200 OK&lt;/code&gt;. O serviço não caiu. O que fechou foi o acesso novo vindo de fora.&lt;/p&gt;

&lt;p&gt;As regras gravadas pelo &lt;code&gt;install&lt;/code&gt; devolvem cedo o tráfego com origem em &lt;code&gt;10.0.0.0/8&lt;/code&gt;, &lt;code&gt;172.16.0.0/12&lt;/code&gt; e &lt;code&gt;192.168.0.0/16&lt;/code&gt;. Um &lt;code&gt;curl&lt;/code&gt; feito de um endereço dessas faixas, ou do próprio servidor, não mostra se a internet foi bloqueada. O timeout deste teste saiu de 203.0.113.10, fora delas.&lt;/p&gt;

&lt;p&gt;Para abrir de propósito, a regra usa a porta do contêiner. Aqui o Apache escuta 80, e o host mostra 8088. A regra é na 80:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw route allow proto tcp from any to any port 80
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;ufw status numbered&lt;/code&gt; passou a ter &lt;code&gt;80/tcp ALLOW FWD&lt;/code&gt; e manteve &lt;code&gt;8088/tcp DENY IN&lt;/code&gt;. Mesmo assim o &lt;code&gt;curl&lt;/code&gt; de fora para a porta 8088 voltou a receber &lt;code&gt;HTTP/1.1 200 OK&lt;/code&gt; com &lt;code&gt;Server: Apache/2.4.71 (Unix)&lt;/code&gt;. O &lt;code&gt;DENY IN&lt;/code&gt; na porta do host não é o que decide.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;ufw allow 8088/tcp&lt;/code&gt; não é a regra do contêiner.&lt;/strong&gt; Essa regra entra na cadeia de entrada do host. O pacote publicado pelo Docker não passa por ela. O que libera é &lt;code&gt;ufw route allow&lt;/code&gt; na porta que o processo escuta dentro do contêiner.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  No Coolify
&lt;/h2&gt;

&lt;p&gt;O mesmo furo aparece no painel. Com o ufw ativo e sem regra para a porta 8000, &lt;code&gt;http://203.0.113.1:8000/&lt;/code&gt; ainda respondia &lt;code&gt;HTTP/1.1 302 Found&lt;/code&gt; para &lt;code&gt;/login&lt;/code&gt;. Depois do &lt;code&gt;ufw-docker&lt;/code&gt; e do &lt;code&gt;ufw reload&lt;/code&gt;, esse pedido passou a estourar o tempo, igual ao Apache.&lt;/p&gt;

&lt;p&gt;O &lt;code&gt;docker ps&lt;/code&gt; mostra &lt;code&gt;0.0.0.0:8000-&amp;gt;8080/tcp&lt;/code&gt; no contêiner do Coolify. A regra que reabriu o painel foi na 8080, não na 8000:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw route allow proto tcp from any to any port 8080
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A resposta voltou a ser &lt;code&gt;HTTP/1.1 302 Found&lt;/code&gt; para &lt;code&gt;/login&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;As portas 80 e 443 do proxy e as portas 6001 e 6002 seguem o mesmo critério: a porta do &lt;code&gt;route allow&lt;/code&gt; é a do contêiner. A lista que este teste abriu, e o que cada uma respondeu, está em &lt;a href="https://nuvits.net/blog/como-instalar-coolify-vps-ubuntu" rel="noopener noreferrer"&gt;Como instalar o Coolify numa VPS Ubuntu&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Se a VPS tem firewall no painel do provedor, use esse firewall e deixe o ufw como segunda camada. Ele descarta o pacote antes do Docker. O guia de instalação do n8n evita o problema de outro jeito: só o Caddy publica porta, e o resto fica na rede interna do Compose. O passo a passo é &lt;a href="https://nuvits.net/blog/como-instalar-n8n-docker-vps" rel="noopener noreferrer"&gt;Como instalar o n8n com Docker numa VPS&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  O que conferir
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;De outro computador, a porta publicada deixa de conectar depois do &lt;code&gt;ufw reload&lt;/code&gt;. Timeout é bloqueio. &lt;code&gt;200&lt;/code&gt; é porta aberta.&lt;/li&gt;
&lt;li&gt;No próprio servidor, &lt;code&gt;curl http://127.0.0.1:PORTA/&lt;/code&gt; ainda pode responder 200. Isso não prova que a internet alcança a porta, nem que deixou de alcançar.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;ufw status&lt;/code&gt; mostra &lt;code&gt;ALLOW FWD&lt;/code&gt; na porta do contêiner quando a liberação é a do &lt;code&gt;ufw-docker&lt;/code&gt;. Um &lt;code&gt;DENY IN&lt;/code&gt; na porta do host pode continuar na lista e não mudar o resultado.&lt;/li&gt;
&lt;li&gt;Mantenha o SSH aberto numa sessão já conectada até confirmar o acesso por outra sessão. A regra &lt;code&gt;ufw allow 22/tcp&lt;/code&gt; deste teste ficou no lugar, e a sessão seguiu.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;O plano ao lado cobre uma VPS em que esse Docker roda. Se você ainda vai escolher a máquina, comece por &lt;a href="https://nuvits.net/vps-docker" rel="noopener noreferrer"&gt;VPS com Docker&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;Publicado originalmente em &lt;a href="https://nuvits.net/blog/porta-do-docker-aberta-com-ufw" rel="noopener noreferrer"&gt;https://nuvits.net/blog/porta-do-docker-aberta-com-ufw&lt;/a&gt;&lt;/p&gt;

</description>
      <category>braziliandevs</category>
      <category>portugues</category>
      <category>docker</category>
      <category>security</category>
    </item>
    <item>
      <title>How to install Coolify on a VPS securely</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Thu, 19 Nov 2026 11:23:07 +0000</pubDate>
      <link>https://dev.to/nuvits/how-to-install-coolify-on-an-ubuntu-vps-312f</link>
      <guid>https://dev.to/nuvits/how-to-install-coolify-on-an-ubuntu-vps-312f</guid>
      <description>&lt;p&gt;This guide installs Coolify 4.7 on an Ubuntu 24.04 VPS without exposing the dashboard at any point. The dashboard ports are bound to &lt;code&gt;localhost&lt;/code&gt; before the install, the installer itself creates the admin account, and the first visit goes through an SSH tunnel. Then the dashboard moves to a domain with HTTPS, and the guide ends with updates and backups.&lt;/p&gt;

&lt;h2&gt;
  
  
  What you need
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;A VPS running 64-bit Ubuntu 24.04, with SSH key access.&lt;/li&gt;
&lt;li&gt;A domain where you can create DNS records. The examples use &lt;code&gt;coolify.example.com&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;An email address on a real domain for the admin account. Coolify checks the DNS of the email's domain.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The &lt;a href="https://coolify.io/docs/start-with-self-hosted" rel="noopener noreferrer"&gt;Coolify docs&lt;/a&gt; ask for at least 2 cores, 2 GB of RAM and 10 GB of free disk, but the installer warns when there are fewer than 20 GB free. That minimum covers Coolify alone: at rest, its six containers use about 750 MB of RAM, and every application, database or build you deploy adds to that. With 4 vCPUs and 8 GB you have room for a few projects and for builds that don't freeze the dashboard.&lt;/p&gt;

&lt;p&gt;If you just want to try it, &lt;a href="https://nuvits.net/en" rel="noopener noreferrer"&gt;Nuvits&lt;/a&gt; can also deliver the VPS with Coolify preinstalled when you order it. In that option, the dashboard ports come blocked from the internet and the first visit goes through an SSH tunnel, as in this guide.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why install it carefully
&lt;/h2&gt;

&lt;p&gt;The default one-command install leaves three gaps:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The first visitor becomes the admin.&lt;/strong&gt; After each start, Coolify accepts the first user's sign-up for 10 minutes, and its own docs warn that whoever reaches the registration page first gets root access to the server.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The dashboard opens over HTTP.&lt;/strong&gt; Until you set up a domain, the login at &lt;code&gt;http://IP:8000&lt;/code&gt; travels unencrypted.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;ufw doesn't close Docker's ports.&lt;/strong&gt; The dashboard runs in a container, and a port published by Docker is reachable from outside even without a ufw rule. The &lt;a href="https://coolify.io/docs/core/infrastructure/servers/firewall" rel="noopener noreferrer"&gt;Coolify firewall page&lt;/a&gt; warns not to rely on ufw alone.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The steps below close all three.&lt;/p&gt;

&lt;h2&gt;
  
  
  Prepare the server
&lt;/h2&gt;

&lt;p&gt;If your provider hands you the VPS with &lt;code&gt;root&lt;/code&gt; access, create a user with &lt;code&gt;sudo&lt;/code&gt; and copy your SSH key over:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;adduser deploy
usermod -aG sudo deploy
install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
install -m 600 -o deploy -g deploy ~/.ssh/authorized_keys /home/deploy/.ssh/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Open another session as &lt;code&gt;deploy&lt;/code&gt; and check that the login works before you go on. From here on, the commands run as &lt;code&gt;deploy&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Key-only SSH
&lt;/h3&gt;

&lt;p&gt;Coolify manages its own VPS by logging in over SSH as &lt;code&gt;root&lt;/code&gt;, with a key it generates during the install. The docs ask for &lt;code&gt;PermitRootLogin prohibit-password&lt;/code&gt;, which only lets root in with a key. You can go a bit further: block root logins from the internet and allow them only from Docker's internal networks, which is where Coolify connects from. Create the file:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo nano /etc/ssh/sshd_config.d/10-coolify.conf
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no

Match Address 10.0.0.0/8,172.16.0.0/12
    PermitRootLogin prohibit-password
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The name starts with &lt;code&gt;10-&lt;/code&gt; on purpose: SSH keeps the first value it reads, and some cloud images ship a &lt;code&gt;50-cloudimg-settings.conf&lt;/code&gt; that turns passwords on. The &lt;code&gt;10.0.0.0/8&lt;/code&gt; and &lt;code&gt;172.16.0.0/12&lt;/code&gt; ranges cover the networks Docker creates. Test and apply:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo sshd -t
sudo systemctl restart ssh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;sshd -t&lt;/code&gt; prints nothing when the file is valid. Before you close the current session, open another one as &lt;code&gt;deploy&lt;/code&gt; to confirm you can still get in.&lt;/p&gt;

&lt;h3&gt;
  
  
  Firewall
&lt;/h3&gt;

&lt;p&gt;Allow SSH, HTTP and HTTPS in ufw and turn the firewall on:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443
sudo ufw &lt;span class="nb"&gt;enable&lt;/span&gt;
sudo ufw status
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;ufw enable&lt;/code&gt; asks for confirmation because it may drop your SSH connection; with the port 22 rule already in place, answer &lt;code&gt;y&lt;/code&gt;. The &lt;code&gt;443&lt;/code&gt; rule without a protocol also opens UDP, which the Coolify proxy uses for HTTP/3. Ports 8000, 6001 and 6002 stay out, but, as noted above, ufw isn't enough for them. The next step takes care of that. If your provider has a network firewall in its dashboard, open the same three ports there.&lt;/p&gt;

&lt;h2&gt;
  
  
  Close the dashboard before installing
&lt;/h2&gt;

&lt;p&gt;Coolify publishes three ports: 8000 (dashboard), 6001 (real-time updates) and 6002 (web terminal). It also reads an optional &lt;code&gt;docker-compose.custom.yml&lt;/code&gt; file that updates never overwrite. The docs use that file to bind the ports to &lt;code&gt;localhost&lt;/code&gt;, and nothing stops you from creating it before the install:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo mkdir -p /data/coolify/source
sudo nano /data/coolify/source/docker-compose.custom.yml
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;coolify&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;!override&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"127.0.0.1:8000:8080"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"127.0.0.1:6001:6001"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"127.0.0.1:6002:6002"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;!override&lt;/code&gt; replaces the port list from the original file instead of adding to it. With this, the dashboard only answers inside the VPS, and you reach it through an SSH tunnel.&lt;/p&gt;

&lt;h2&gt;
  
  
  Install Coolify
&lt;/h2&gt;

&lt;p&gt;Download the official installer and read it before you run it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o coolify-install.sh
less coolify-install.sh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The script installs the packages it needs and Docker (through the &lt;code&gt;get.docker.com&lt;/code&gt; script), then generates an SSH key for Coolify and adds it to &lt;code&gt;/root/.ssh/authorized_keys&lt;/code&gt;. If you'd rather have Docker from the official &lt;code&gt;apt&lt;/code&gt; repository, install it first, as in the &lt;a href="https://nuvits.net/en/blog/install-n8n-docker-vps#install-docker" rel="noopener noreferrer"&gt;n8n guide&lt;/a&gt;; the installer uses whatever Docker it finds.&lt;/p&gt;

&lt;p&gt;Now run the installer with three variables that create the admin account right away. That way, the registration page is never open. &lt;code&gt;read -s&lt;/code&gt; keeps the password off the screen and out of your shell history:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;read&lt;/span&gt; -rp &lt;span class="s1"&gt;'Admin email: '&lt;/span&gt; COOLIFY_EMAIL
&lt;span class="nb"&gt;read&lt;/span&gt; -rsp &lt;span class="s1"&gt;'Admin password: '&lt;/span&gt; COOLIFY_PASSWORD&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt;

sudo env &lt;span class="nv"&gt;ROOT_USERNAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;admin &lt;span class="nv"&gt;ROOT_USER_EMAIL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$COOLIFY_EMAIL"&lt;/span&gt; &lt;span class="nv"&gt;ROOT_USER_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$COOLIFY_PASSWORD"&lt;/span&gt; &lt;span class="nv"&gt;AUTOUPDATE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt; bash coolify-install.sh 4.7.5

&lt;span class="kd"&gt;unset&lt;/span&gt; COOLIFY_PASSWORD
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;What each part does:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;4.7.5&lt;/code&gt; pins the version. It was the stable release when this was written. Check the current one in the &lt;a href="https://github.com/coollabsio/coolify/releases" rel="noopener noreferrer"&gt;Coolify releases&lt;/a&gt; or in the &lt;code&gt;stable&lt;/code&gt; field of &lt;a href="https://cdn.coollabs.io/coolify/versions.json" rel="noopener noreferrer"&gt;versions.json&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;The password needs at least 8 characters, with uppercase and lowercase letters, numbers and symbols, and it can't show up in known breaches. Generate one in your password manager.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;AUTOUPDATE=false&lt;/code&gt; turns off automatic updates, which are on by default and run every day at midnight. The update section explains why.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The install takes a few minutes. At the end, the script prints addresses like &lt;code&gt;http://IP:8000&lt;/code&gt; that won't open from outside: that's expected. It also warns that &lt;code&gt;PermitRootLogin&lt;/code&gt; is disabled, because it only reads the global SSH rule, not the &lt;code&gt;Match&lt;/code&gt; block.&lt;/p&gt;

&lt;p&gt;Check that the admin account was created:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker logs coolify 2&lt;span class="o"&gt;&amp;gt;&amp;amp;&lt;/span&gt;1 &lt;span class="o"&gt;|&lt;/span&gt; grep -i &lt;span class="s2"&gt;"root user"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The output should include &lt;code&gt;Root user created successfully&lt;/code&gt;. If you see &lt;code&gt;Invalid Root User Environment Variables&lt;/code&gt;, the email or the password failed validation. In that case the registration page stays open for 10 minutes, but only through the tunnel in the next section: create the account there, and if time runs out, &lt;code&gt;sudo docker restart coolify&lt;/code&gt; opens the window again.&lt;/p&gt;

&lt;p&gt;With the account created, delete the password the installer wrote to Coolify's &lt;code&gt;.env&lt;/code&gt;, along with the downloaded installer:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo sed -i &lt;span class="s1"&gt;'/^ROOT_USER_PASSWORD=/d'&lt;/span&gt; /data/coolify/source/.env
rm coolify-install.sh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The container that is already running keeps the password in its environment variables, readable only by root, until the next update recreates it.&lt;/p&gt;

&lt;p&gt;Finally, confirm that the dashboard ports listen only on &lt;code&gt;localhost&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ss -ltn &lt;span class="o"&gt;|&lt;/span&gt; grep -E &lt;span class="s1"&gt;':(8000|6001|6002) '&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;All three lines should start with &lt;code&gt;127.0.0.1&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Open the dashboard through an SSH tunnel
&lt;/h2&gt;

&lt;p&gt;On your machine, open a tunnel with the three ports:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;ssh -N -L 8000:localhost:8000 -L 6001:localhost:6001 -L 6002:localhost:6002 deploy@YOUR_VPS_IP
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The command sits there while the tunnel is open. Go to &lt;code&gt;http://localhost:8000&lt;/code&gt; in your browser and sign in with the admin email and password. The setup wizard offers &lt;strong&gt;This machine&lt;/strong&gt; to use the VPS itself as a server; pick it and Coolify validates its SSH connection to root.&lt;/p&gt;

&lt;p&gt;Before you deploy anything, turn on two-factor authentication in &lt;strong&gt;Profile &amp;gt; Two-factor Authentication&lt;/strong&gt; and keep the recovery codes outside Coolify. It's worth the effort: Coolify's web terminal opens a root shell on the VPS.&lt;/p&gt;

&lt;p&gt;In &lt;strong&gt;Settings &amp;gt; Advanced&lt;/strong&gt;, check that &lt;strong&gt;Registration&lt;/strong&gt; is set to &lt;strong&gt;Registration disabled&lt;/strong&gt;. The installer leaves it that way when it creates the admin. On the same screen, API access and the MCP server come turned off; only enable them if you need them.&lt;/p&gt;

&lt;h2&gt;
  
  
  Put the dashboard on a domain with HTTPS
&lt;/h2&gt;

&lt;p&gt;In your domain's DNS panel, create an &lt;code&gt;A&lt;/code&gt; record named &lt;code&gt;coolify&lt;/code&gt; (or the subdomain you chose) pointing to the VPS's IPv4 address. Check that it already resolves:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dig +short coolify.example.com A
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With DNS in place, open &lt;strong&gt;Settings &amp;gt; General&lt;/strong&gt;, set &lt;strong&gt;URL&lt;/strong&gt; to &lt;code&gt;https://coolify.example.com&lt;/code&gt; and save. Coolify's proxy, Traefik, which already serves ports 80 and 443, starts answering on that domain and requests the certificate from Let's Encrypt on its own. The HTTP address redirects to HTTPS, and the real-time updates and the web terminal also go through port 443.&lt;/p&gt;

&lt;p&gt;Test from outside the VPS:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -I https://coolify.example.com/login
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The response should be &lt;code&gt;HTTP/2 200&lt;/code&gt;. If the certificate doesn't come through, check DNS and whether ports 80 and 443 are also open in your provider's firewall, if it has one.&lt;/p&gt;

&lt;p&gt;From now on, use the dashboard through the domain. Leave &lt;code&gt;docker-compose.custom.yml&lt;/code&gt; as it is: ports 8000, 6001 and 6002 stay closed to the internet, and the SSH tunnel keeps working as emergency access if the domain or the proxy fails.&lt;/p&gt;

&lt;h2&gt;
  
  
  Update and back up
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Backup
&lt;/h3&gt;

&lt;p&gt;Coolify keeps everything in its own PostgreSQL, the &lt;code&gt;coolify-db&lt;/code&gt; container. Passwords and keys saved in the dashboard are encrypted with the &lt;code&gt;APP_KEY&lt;/code&gt; from &lt;code&gt;/data/coolify/source/.env&lt;/code&gt;, and the database dump doesn't include that file. A backup needs both:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~
&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;umask&lt;/span&gt; 077
 sudo docker &lt;span class="nb"&gt;exec&lt;/span&gt; coolify-db pg_dump --format=custom --no-acl --no-owner --username=coolify coolify &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; coolify-db-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.dmp
 sudo cat /data/coolify/source/.env &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; coolify-env-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt;
ls -l coolify-db-* coolify-env-*
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;umask 077&lt;/code&gt; makes both files readable only by your user. Then copy them off the VPS, from your machine:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p coolify-backups
scp &lt;span class="s1"&gt;'deploy@YOUR_VPS_IP:coolify-db-*'&lt;/span&gt; &lt;span class="s1"&gt;'deploy@YOUR_VPS_IP:coolify-env-*'&lt;/span&gt; ./coolify-backups/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Also keep the &lt;code&gt;APP_KEY=&lt;/code&gt; line in a password manager. Without it, a restored database opens, but the saved credentials can't be read. For scheduled backups, Coolify has &lt;strong&gt;Settings &amp;gt; Backup&lt;/strong&gt;, which can send the dump to S3 storage. Restoring, including to another VPS, is covered in &lt;a href="https://coolify.io/docs/core/backup-and-recovery/instance-restore" rel="noopener noreferrer"&gt;Restore a Coolify instance&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;This backs up Coolify itself. The databases and volumes of the applications you deploy have their own backups, set up on each resource.&lt;/p&gt;

&lt;h3&gt;
  
  
  Update
&lt;/h3&gt;

&lt;p&gt;Coolify ships several releases a week: 4.7.0 through 4.7.5 were six releases in two days. With automatic updates on, a new version lands overnight without you seeing it, and every update restarts Coolify's containers. That's why this guide turned them off. In exchange, you need to follow the &lt;a href="https://github.com/coollabsio/coolify/releases" rel="noopener noreferrer"&gt;releases&lt;/a&gt; and update often, because security fixes arrive in new versions.&lt;/p&gt;

&lt;p&gt;The routine:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Take the backup above.&lt;/li&gt;
&lt;li&gt;Read the release notes for the new version.&lt;/li&gt;
&lt;li&gt;Run the upgrade script with the version:
&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh &lt;span class="o"&gt;|&lt;/span&gt; sudo bash -s 4.7.6
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Replace &lt;code&gt;4.7.6&lt;/code&gt; with the version you want. The script pulls the images and restarts Coolify in the background. Wait a minute and check:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker ps --format &lt;span class="s1"&gt;'{{.Names}}\t{{.Image}}\t{{.Ports}}'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; grep -w coolify
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The image should show the new version, and the ports, &lt;code&gt;127.0.0.1&lt;/code&gt;. &lt;code&gt;docker-compose.custom.yml&lt;/code&gt; still applies after the update.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Don't use &lt;code&gt;install.sh&lt;/code&gt; to update.&lt;/strong&gt; The docs warn that, on an existing install, it resets owners and permissions under &lt;code&gt;/data/coolify&lt;/code&gt;, including service data. To update, always use &lt;code&gt;upgrade.sh&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;If you'd rather have automatic updates, drop &lt;code&gt;AUTOUPDATE=false&lt;/code&gt; from the install command. With that variable in &lt;code&gt;.env&lt;/code&gt;, the option is locked in &lt;strong&gt;Settings &amp;gt; Updates&lt;/strong&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Next steps
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Set up a notification channel under &lt;strong&gt;Notifications&lt;/strong&gt; so you hear about failed deployments and backups.&lt;/li&gt;
&lt;li&gt;Point a &lt;code&gt;*.example.com&lt;/code&gt; record at the VPS and fill in &lt;strong&gt;Wildcard domain&lt;/strong&gt; on the server, so each application gets an HTTPS subdomain without touching DNS.&lt;/li&gt;
&lt;li&gt;Expose applications through domains, via the proxy, and avoid mapping their ports to the internet: ufw doesn't close those ports either.&lt;/li&gt;
&lt;li&gt;Read Coolify's &lt;a href="https://coolify.io/docs/core/security-model" rel="noopener noreferrer"&gt;security model&lt;/a&gt; before giving other people access to the dashboard.&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>coolify</category>
      <category>docker</category>
      <category>selfhosted</category>
      <category>devops</category>
    </item>
    <item>
      <title>Como instalar o Coolify numa VPS com segurança</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Thu, 19 Nov 2026 11:22:57 +0000</pubDate>
      <link>https://dev.to/nuvits/como-instalar-o-coolify-numa-vps-ubuntu-3p8i</link>
      <guid>https://dev.to/nuvits/como-instalar-o-coolify-numa-vps-ubuntu-3p8i</guid>
      <description>&lt;p&gt;Este guia instala o Coolify 4.7 numa VPS Ubuntu 24.04 sem deixar o painel exposto em nenhum momento. As portas do painel ficam presas ao &lt;code&gt;localhost&lt;/code&gt; antes da instalação, o administrador é criado pelo próprio instalador e o primeiro acesso é por um túnel SSH. Depois, o painel passa para um domínio com HTTPS, e o guia termina com atualização e backup.&lt;/p&gt;

&lt;h2&gt;
  
  
  O que você vai precisar
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Uma VPS com Ubuntu 24.04 de 64 bits e acesso SSH por chave.&lt;/li&gt;
&lt;li&gt;Um domínio em que você consiga criar registros DNS. Os exemplos usam &lt;code&gt;coolify.example.com&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Um e-mail de domínio real para a conta de administrador. O Coolify confere o DNS do domínio do e-mail.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A &lt;a href="https://coolify.io/docs/start-with-self-hosted" rel="noopener noreferrer"&gt;documentação do Coolify&lt;/a&gt; pede no mínimo 2 núcleos, 2 GB de RAM e 10 GB de disco livre, mas o instalador avisa quando o disco tem menos de 20 GB livres. Esse mínimo é só para o Coolify: em repouso, os seis contêineres dele usam perto de 750 MB de RAM, e cada aplicação, banco ou build que você publicar soma a isso. Com 4 vCPU e 8 GB, sobra espaço para alguns projetos e para builds sem travar o painel.&lt;/p&gt;

&lt;p&gt;Se você quer só experimentar, a &lt;a href="https://nuvits.net" rel="noopener noreferrer"&gt;Nuvits&lt;/a&gt; também entrega a VPS com o Coolify pré-instalado na contratação. Nessa opção, as portas do painel já vêm bloqueadas para a internet e o primeiro acesso é por túnel SSH, como neste guia.&lt;/p&gt;

&lt;h2&gt;
  
  
  Por que instalar com cuidado
&lt;/h2&gt;

&lt;p&gt;A instalação padrão, com um comando só, deixa três brechas:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;O primeiro visitante vira administrador.&lt;/strong&gt; Depois de cada início, o Coolify aceita o cadastro do primeiro usuário por 10 minutos, e a própria documentação avisa que quem chegar primeiro à página de registro ganha acesso root ao servidor.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;O painel abre em HTTP.&lt;/strong&gt; Até você configurar um domínio, o login em &lt;code&gt;http://IP:8000&lt;/code&gt; trafega sem criptografia.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;O ufw não fecha as portas do Docker.&lt;/strong&gt; O painel roda num contêiner, e uma porta publicada pelo Docker fica acessível de fora mesmo sem regra no ufw. A &lt;a href="https://coolify.io/docs/core/infrastructure/servers/firewall" rel="noopener noreferrer"&gt;página de firewall do Coolify&lt;/a&gt; avisa para não depender só do ufw.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;O roteiro abaixo fecha as três.&lt;/p&gt;

&lt;h2&gt;
  
  
  Preparar o servidor
&lt;/h2&gt;

&lt;p&gt;Se o provedor entrega a VPS com acesso como &lt;code&gt;root&lt;/code&gt;, crie um usuário com &lt;code&gt;sudo&lt;/code&gt; e copie a sua chave SSH para ele:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;adduser deploy
usermod -aG sudo deploy
install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
install -m 600 -o deploy -g deploy ~/.ssh/authorized_keys /home/deploy/.ssh/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Abra outra sessão como &lt;code&gt;deploy&lt;/code&gt; e confira que o login funciona antes de seguir. Daqui em diante, os comandos rodam como &lt;code&gt;deploy&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  SSH só com chave
&lt;/h3&gt;

&lt;p&gt;O Coolify administra a própria VPS entrando por SSH como &lt;code&gt;root&lt;/code&gt;, com uma chave que ele gera na instalação. A documentação pede &lt;code&gt;PermitRootLogin prohibit-password&lt;/code&gt;, que aceita o root só com chave. Dá para ir um pouco além: bloquear o root vindo da internet e liberar só para as redes internas do Docker, de onde o Coolify se conecta. Crie o arquivo:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo nano /etc/ssh/sshd_config.d/10-coolify.conf
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no

Match Address 10.0.0.0/8,172.16.0.0/12
    PermitRootLogin prohibit-password
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O nome começa com &lt;code&gt;10-&lt;/code&gt; de propósito: o SSH fica com o primeiro valor que lê, e algumas imagens de nuvem trazem um &lt;code&gt;50-cloudimg-settings.conf&lt;/code&gt; que liga a senha. As faixas &lt;code&gt;10.0.0.0/8&lt;/code&gt; e &lt;code&gt;172.16.0.0/12&lt;/code&gt; cobrem as redes que o Docker cria. Teste e aplique:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo sshd -t
sudo systemctl restart ssh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;sshd -t&lt;/code&gt; não imprime nada quando o arquivo está certo. Antes de fechar a sessão atual, abra outra como &lt;code&gt;deploy&lt;/code&gt; para confirmar que o acesso continua.&lt;/p&gt;

&lt;h3&gt;
  
  
  Firewall
&lt;/h3&gt;

&lt;p&gt;Libere SSH, HTTP e HTTPS no ufw e ative o firewall:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443
sudo ufw &lt;span class="nb"&gt;enable&lt;/span&gt;
sudo ufw status
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;ufw enable&lt;/code&gt; pede confirmação porque pode derrubar a conexão SSH; com a regra da porta 22 já criada, responda &lt;code&gt;y&lt;/code&gt;. A regra &lt;code&gt;443&lt;/code&gt; sem protocolo libera também o UDP, usado pelo HTTP/3 do proxy do Coolify. As portas 8000, 6001 e 6002 ficam de fora, mas, como dito acima, o ufw não basta para elas. O próximo passo resolve isso. Se o seu provedor tiver um firewall de rede no painel, libere nele as mesmas três portas.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fechar o painel antes de instalar
&lt;/h2&gt;

&lt;p&gt;O Coolify publica três portas: 8000 (painel), 6001 (atualizações em tempo real) e 6002 (terminal web). Ele também lê um arquivo opcional, &lt;code&gt;docker-compose.custom.yml&lt;/code&gt;, que as atualizações não sobrescrevem. A documentação usa esse arquivo para prender as portas ao &lt;code&gt;localhost&lt;/code&gt;, e nada impede de criá-lo antes da instalação:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo mkdir -p /data/coolify/source
sudo nano /data/coolify/source/docker-compose.custom.yml
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;coolify&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;!override&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"127.0.0.1:8000:8080"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"127.0.0.1:6001:6001"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"127.0.0.1:6002:6002"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;!override&lt;/code&gt; substitui a lista de portas do arquivo original, em vez de somar a ela. Com isso, o painel só responde dentro da VPS, e você chega até ele por um túnel SSH.&lt;/p&gt;

&lt;h2&gt;
  
  
  Instalar o Coolify
&lt;/h2&gt;

&lt;p&gt;Baixe o instalador oficial e leia antes de rodar:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o coolify-install.sh
less coolify-install.sh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O script instala os pacotes de que precisa, o Docker (pelo script &lt;code&gt;get.docker.com&lt;/code&gt;), gera uma chave SSH para o Coolify e a acrescenta ao &lt;code&gt;/root/.ssh/authorized_keys&lt;/code&gt;. Se você prefere o Docker do repositório &lt;code&gt;apt&lt;/code&gt; oficial, instale-o antes, como no &lt;a href="https://nuvits.net/blog/como-instalar-n8n-docker-vps#instalar-o-docker" rel="noopener noreferrer"&gt;guia do n8n&lt;/a&gt;; o instalador usa o Docker que encontrar.&lt;/p&gt;

&lt;p&gt;Agora rode o instalador com três variáveis que criam o administrador na hora. Assim, a página de registro nunca fica aberta. O &lt;code&gt;read -s&lt;/code&gt; evita que a senha apareça na tela ou no histórico do shell:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;read&lt;/span&gt; -rp &lt;span class="s1"&gt;'E-mail do admin: '&lt;/span&gt; COOLIFY_EMAIL
&lt;span class="nb"&gt;read&lt;/span&gt; -rsp &lt;span class="s1"&gt;'Senha do admin: '&lt;/span&gt; COOLIFY_PASSWORD&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt;

sudo env &lt;span class="nv"&gt;ROOT_USERNAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;admin &lt;span class="nv"&gt;ROOT_USER_EMAIL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$COOLIFY_EMAIL"&lt;/span&gt; &lt;span class="nv"&gt;ROOT_USER_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$COOLIFY_PASSWORD"&lt;/span&gt; &lt;span class="nv"&gt;AUTOUPDATE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt; bash coolify-install.sh 4.7.5

&lt;span class="kd"&gt;unset&lt;/span&gt; COOLIFY_PASSWORD
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O que cada parte faz:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;4.7.5&lt;/code&gt; fixa a versão. Era a estável quando este texto foi escrito. Confira a atual nas &lt;a href="https://github.com/coollabsio/coolify/releases" rel="noopener noreferrer"&gt;releases do Coolify&lt;/a&gt; ou no campo &lt;code&gt;stable&lt;/code&gt; de &lt;a href="https://cdn.coollabs.io/coolify/versions.json" rel="noopener noreferrer"&gt;versions.json&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;A senha precisa de no mínimo 8 caracteres, com maiúsculas, minúsculas, números e símbolos, e não pode aparecer em vazamentos conhecidos. Gere uma no seu gerenciador de senhas.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;AUTOUPDATE=false&lt;/code&gt; desliga a atualização automática, que vem ligada e roda todo dia à meia-noite. A seção de atualização explica por quê.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A instalação leva alguns minutos. No fim, o script mostra endereços como &lt;code&gt;http://IP:8000&lt;/code&gt;, que não vão abrir de fora: é o resultado esperado. Ele tamb��m avisa que &lt;code&gt;PermitRootLogin&lt;/code&gt; está desligado, porque lê só a regra geral do SSH, não o bloco &lt;code&gt;Match&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Confira se o administrador foi criado:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker logs coolify 2&lt;span class="o"&gt;&amp;gt;&amp;amp;&lt;/span&gt;1 &lt;span class="o"&gt;|&lt;/span&gt; grep -i &lt;span class="s2"&gt;"root user"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A saída precisa trazer &lt;code&gt;Root user created successfully&lt;/code&gt;. Se aparecer &lt;code&gt;Invalid Root User Environment Variables&lt;/code&gt;, o e-mail ou a senha não passaram na validação. Nesse caso, a página de registro fica aberta por 10 minutos, mas só pelo túnel da próxima seção: crie a conta por ela, e, se o prazo passar, &lt;code&gt;sudo docker restart coolify&lt;/code&gt; reabre a janela.&lt;/p&gt;

&lt;p&gt;Com a conta criada, apague a senha que o instalador gravou no &lt;code&gt;.env&lt;/code&gt; do Coolify e o instalador baixado:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo sed -i &lt;span class="s1"&gt;'/^ROOT_USER_PASSWORD=/d'&lt;/span&gt; /data/coolify/source/.env
rm coolify-install.sh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O contêiner que já está rodando guarda a senha nas variáveis de ambiente, visíveis só para o root, até a próxima atualização recriá-lo.&lt;/p&gt;

&lt;p&gt;Por fim, confirme que as portas do painel escutam só no &lt;code&gt;localhost&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ss -ltn &lt;span class="o"&gt;|&lt;/span&gt; grep -E &lt;span class="s1"&gt;':(8000|6001|6002) '&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;As três linhas precisam começar com &lt;code&gt;127.0.0.1&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Abrir o painel pelo túnel SSH
&lt;/h2&gt;

&lt;p&gt;Na sua máquina, abra um túnel com as três portas:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;ssh -N -L 8000:localhost:8000 -L 6001:localhost:6001 -L 6002:localhost:6002 deploy@IP_DA_VPS
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O comando fica parado enquanto o túnel estiver aberto. Acesse &lt;code&gt;http://localhost:8000&lt;/code&gt; no navegador e entre com o e-mail e a senha do administrador. O assistente inicial oferece &lt;strong&gt;This machine&lt;/strong&gt; para usar a própria VPS como servidor; escolha essa opção e o Coolify valida a conexão SSH com o root.&lt;/p&gt;

&lt;p&gt;Antes de publicar qualquer coisa, ative a autenticação em dois fatores em &lt;strong&gt;Profile &amp;gt; Two-factor Authentication&lt;/strong&gt; e guarde os códigos de recuperação fora do Coolify. Vale o cuidado: o terminal web do Coolify abre um shell como root na VPS.&lt;/p&gt;

&lt;p&gt;Em &lt;strong&gt;Settings &amp;gt; Advanced&lt;/strong&gt;, confira que &lt;strong&gt;Registration&lt;/strong&gt; está em &lt;strong&gt;Registration disabled&lt;/strong&gt;. O instalador já deixa assim quando cria o administrador. Na mesma tela, o acesso à API e o servidor MCP vêm desligados; ligue só se for usar.&lt;/p&gt;

&lt;h2&gt;
  
  
  Colocar o painel num domínio com HTTPS
&lt;/h2&gt;

&lt;p&gt;No painel DNS do seu domínio, crie um registro &lt;code&gt;A&lt;/code&gt; com o nome &lt;code&gt;coolify&lt;/code&gt; (ou o subdomínio escolhido) apontando para o IPv4 da VPS. Confira se ele já resolve:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dig +short coolify.example.com A
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Com o DNS certo, abra &lt;strong&gt;Settings &amp;gt; General&lt;/strong&gt;, preencha &lt;strong&gt;URL&lt;/strong&gt; com &lt;code&gt;https://coolify.example.com&lt;/code&gt; e salve. O proxy do Coolify, o Traefik, que já atende as portas 80 e 443, passa a responder por esse domínio e pede o certificado ao Let's Encrypt sozinho. O endereço HTTP redireciona para o HTTPS, e as atualizações em tempo real e o terminal web também passam pela porta 443.&lt;/p&gt;

&lt;p&gt;Teste de fora da VPS:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -I https://coolify.example.com/login
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A resposta precisa ser &lt;code&gt;HTTP/2 200&lt;/code&gt;. Se o certificado não sair, confira o DNS e se as portas 80 e 443 estão abertas também no firewall do provedor, quando houver um.&lt;/p&gt;

&lt;p&gt;A partir daqui, use o painel pelo domínio. Deixe o &lt;code&gt;docker-compose.custom.yml&lt;/code&gt; como está: as portas 8000, 6001 e 6002 continuam fechadas para a internet, e o túnel SSH segue funcionando como acesso de emergência se o domínio ou o proxy falharem.&lt;/p&gt;

&lt;h2&gt;
  
  
  Atualizar e fazer backup
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Backup
&lt;/h3&gt;

&lt;p&gt;O Coolify guarda tudo num PostgreSQL próprio, o contêiner &lt;code&gt;coolify-db&lt;/code&gt;. As senhas e chaves salvas no painel ficam criptografadas com o &lt;code&gt;APP_KEY&lt;/code&gt; do arquivo &lt;code&gt;/data/coolify/source/.env&lt;/code&gt;, e o dump do banco não inclui esse arquivo. Um backup precisa das duas coisas:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~
&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;umask&lt;/span&gt; 077
 sudo docker &lt;span class="nb"&gt;exec&lt;/span&gt; coolify-db pg_dump --format=custom --no-acl --no-owner --username=coolify coolify &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; coolify-db-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.dmp
 sudo cat /data/coolify/source/.env &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; coolify-env-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt;
ls -l coolify-db-* coolify-env-*
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;umask 077&lt;/code&gt; cria os dois arquivos legíveis só pelo seu usuário. Depois, copie-os para fora da VPS, a partir da sua máquina:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p backups-coolify
scp &lt;span class="s1"&gt;'deploy@IP_DA_VPS:coolify-db-*'&lt;/span&gt; &lt;span class="s1"&gt;'deploy@IP_DA_VPS:coolify-env-*'&lt;/span&gt; ./backups-coolify/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Guarde também a linha &lt;code&gt;APP_KEY=&lt;/code&gt; num gerenciador de senhas. Sem ela, um banco restaurado abre, mas as credenciais salvas não podem ser lidas. Para backups agendados, o Coolify tem &lt;strong&gt;Settings &amp;gt; Backup&lt;/strong&gt;, que pode enviar o dump para um storage S3. A restauração, inclusive para outra VPS, está em &lt;a href="https://coolify.io/docs/core/backup-and-recovery/instance-restore" rel="noopener noreferrer"&gt;Restore a Coolify instance&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Este é o backup do Coolify em si. Os bancos e volumes das aplicações que você publicar têm backup próprio, configurado em cada recurso.&lt;/p&gt;

&lt;h3&gt;
  
  
  Atualizar
&lt;/h3&gt;

&lt;p&gt;O Coolify lança várias versões por semana: da 4.7.0 à 4.7.5 foram seis em dois dias. Com a atualização automática ligada, uma versão nova entra de madrugada sem você ver, e cada atualização reinicia os contêineres do Coolify. Por isso o guia a desligou. Em troca, você precisa acompanhar as &lt;a href="https://github.com/coollabsio/coolify/releases" rel="noopener noreferrer"&gt;releases&lt;/a&gt; e atualizar com frequência, porque correções de segurança chegam pelas versões novas.&lt;/p&gt;

&lt;p&gt;O roteiro:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Faça o backup acima.&lt;/li&gt;
&lt;li&gt;Leia as notas da versão nova.&lt;/li&gt;
&lt;li&gt;Rode o script de atualização com a versão:
&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh &lt;span class="o"&gt;|&lt;/span&gt; sudo bash -s 4.7.6
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Troque &lt;code&gt;4.7.6&lt;/code&gt; pela versão desejada. O script baixa as imagens e reinicia o Coolify em segundo plano. Espere um minuto e confira:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker ps --format &lt;span class="s1"&gt;'{{.Names}}\t{{.Image}}\t{{.Ports}}'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; grep -w coolify
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A imagem deve mostrar a versão nova, e as portas, &lt;code&gt;127.0.0.1&lt;/code&gt;. O &lt;code&gt;docker-compose.custom.yml&lt;/code&gt; continua valendo depois da atualização.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Não use o &lt;code&gt;install.sh&lt;/code&gt; para atualizar.&lt;/strong&gt; A documentação avisa que, numa instalação existente, ele refaz donos e permissões em &lt;code&gt;/data/coolify&lt;/code&gt;, incluindo os dados dos serviços. Para atualizar, use sempre o &lt;code&gt;upgrade.sh&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Se preferir a atualização automática, tire o &lt;code&gt;AUTOUPDATE=false&lt;/code&gt; do comando de instalação. Com essa variável no &lt;code&gt;.env&lt;/code&gt;, a opção fica travada em &lt;strong&gt;Settings &amp;gt; Updates&lt;/strong&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Próximos passos
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Configure um canal de notificação em &lt;strong&gt;Notifications&lt;/strong&gt; para saber de falhas de deploy e de backup.&lt;/li&gt;
&lt;li&gt;Aponte um registro &lt;code&gt;*.example.com&lt;/code&gt; para a VPS e preencha &lt;strong&gt;Wildcard domain&lt;/strong&gt; no servidor, para cada aplicação ganhar um subdomínio com HTTPS sem mexer no DNS.&lt;/li&gt;
&lt;li&gt;Publique as aplicações por domínio, pelo proxy, e evite mapear portas delas para a internet: o ufw também não fecha essas portas.&lt;/li&gt;
&lt;li&gt;Leia o &lt;a href="https://coolify.io/docs/core/security-model" rel="noopener noreferrer"&gt;modelo de segurança&lt;/a&gt; do Coolify antes de dar acesso ao painel a outras pessoas.&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>braziliandevs</category>
      <category>portugues</category>
      <category>coolify</category>
      <category>docker</category>
    </item>
    <item>
      <title>The n8n webhook shows localhost:5678</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Thu, 19 Nov 2026 11:21:51 +0000</pubDate>
      <link>https://dev.to/nuvits/the-n8n-webhook-shows-localhost5678-3j86</link>
      <guid>https://dev.to/nuvits/the-n8n-webhook-shows-localhost5678-3j86</guid>
      <description>&lt;p&gt;n8n's Webhook node, behind a proxy, shows the production URL as &lt;code&gt;http://localhost:5678/webhook/...&lt;/code&gt;. An outside service that receives that address calls its own machine, where &lt;code&gt;localhost:5678&lt;/code&gt; is not your n8n, and the event never arrives.&lt;/p&gt;

&lt;p&gt;The test ran on 19 November 2026 with n8n &lt;code&gt;2.48.6&lt;/code&gt; (&lt;code&gt;docker.n8n.io/n8nio/n8n:2.48.6&lt;/code&gt;) and Caddy &lt;code&gt;2.11.9&lt;/code&gt; in front, on Ubuntu 24.04. n8n used PostgreSQL &lt;code&gt;18.7&lt;/code&gt; and the runner &lt;code&gt;n8nio/runners:2.48.6&lt;/code&gt;. The proxy was the same one as in &lt;a href="https://nuvits.net/en/blog/n8n-evolution-api-same-vps" rel="noopener noreferrer"&gt;n8n and Evolution API on the same VPS&lt;/a&gt;. Each block below is a separate start, with the rest of the Compose file unchanged.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the editor shows
&lt;/h2&gt;

&lt;p&gt;Without &lt;code&gt;N8N_HOST&lt;/code&gt;, &lt;code&gt;N8N_PROTOCOL&lt;/code&gt;, &lt;code&gt;N8N_WEBHOOK_URL&lt;/code&gt; and &lt;code&gt;N8N_PROXY_HOPS&lt;/code&gt;, the startup log was:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Editor is now accessible via:
http://localhost:5678
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;After the owner account existed, &lt;code&gt;GET /rest/settings&lt;/code&gt; returned &lt;code&gt;urlBaseWebhook&lt;/code&gt; and &lt;code&gt;urlBaseEditor&lt;/code&gt; as &lt;code&gt;http://localhost:5678/&lt;/code&gt;. The Webhook node, published with the path &lt;code&gt;whatsapp&lt;/code&gt;, showed the production URL &lt;code&gt;http://localhost:5678/webhook/whatsapp&lt;/code&gt;:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fy8inuvorl8s3i7vc6g2l.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fy8inuvorl8s3i7vc6g2l.webp" alt="n8n Webhook node showing the production URL http://localhost:5678/webhook/whatsapp" width="800" height="611"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The site itself opened at &lt;code&gt;https://n8n.example.com&lt;/code&gt;. The proxy was fine. The URL n8n builds for the webhook is a separate calculation, made from variables, not from the address the browser used.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why port 5678 lands in the URL
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/configuration-examples/configure-webhook-urls-with-reverse-proxy" rel="noopener noreferrer"&gt;n8n docs&lt;/a&gt; describe how the URL is built: without a webhook URL set, n8n joins &lt;code&gt;N8N_PROTOCOL&lt;/code&gt;, &lt;code&gt;N8N_HOST&lt;/code&gt; and &lt;code&gt;N8N_PORT&lt;/code&gt;. The defaults are &lt;code&gt;http&lt;/code&gt;, &lt;code&gt;localhost&lt;/code&gt; and &lt;code&gt;5678&lt;/code&gt;. The proxy publishes 443. The process keeps listening on 5678. The two ends do not match.&lt;/p&gt;

&lt;p&gt;On n8n 2.48.6, measuring one variable at a time gave this. The value is the authenticated &lt;code&gt;urlBaseWebhook&lt;/code&gt;:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variables&lt;/th&gt;
&lt;th&gt;urlBaseWebhook&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;none&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http://localhost:5678/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;N8N_HOST=n8n.example.com&lt;/code&gt; and &lt;code&gt;N8N_PROTOCOL=https&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://n8n.example.com:5678/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;those two plus &lt;code&gt;N8N_WEBHOOK_URL=https://n8n.example.com/&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://n8n.example.com/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;those three plus &lt;code&gt;N8N_PROXY_HOPS=1&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://n8n.example.com/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;code&gt;N8N_HOST&lt;/code&gt; and &lt;code&gt;N8N_PROTOCOL&lt;/code&gt; change the name and the scheme, and port 5678 stays. &lt;code&gt;N8N_WEBHOOK_URL&lt;/code&gt; is what removes the port. The trailing slash matters: the tested value was &lt;code&gt;https://n8n.example.com/&lt;/code&gt;, and the node URL became &lt;code&gt;https://n8n.example.com/webhook/whatsapp&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;N8N_PROXY_HOPS&lt;/code&gt; does not change that string. It turns on Express &lt;code&gt;trust proxy&lt;/code&gt; for that many proxies. With Caddy sending &lt;code&gt;X-Forwarded-For&lt;/code&gt; and hops left at zero, the n8n 2.48.6 log was:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;ValidationError: The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false (default). This could indicate a misconfiguration which would prevent express-rate-limit from accurately identifying users.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With &lt;code&gt;N8N_PROXY_HOPS=1&lt;/code&gt;, the same request through Caddy did not produce that line. The webhook execution then recorded &lt;code&gt;x-forwarded-proto&lt;/code&gt; as &lt;code&gt;https&lt;/code&gt;. One proxy means the value is 1. Two proxies in a row means the value is 2, which this test did not build.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;N8N_WEBHOOK_URL&lt;/code&gt; has existed since n8n 2.30.0. The old variable &lt;code&gt;WEBHOOK_URL&lt;/code&gt; still works on 2.48.6 and also produces &lt;code&gt;https://n8n.example.com/&lt;/code&gt;, but startup warns:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;WEBHOOK_URL -&amp;gt; Use N8N_WEBHOOK_URL instead, which sets the base URL for both test and production webhooks.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The docs mark &lt;code&gt;WEBHOOK_URL&lt;/code&gt; deprecated from 2.35.0. Use the new name.&lt;/p&gt;

&lt;h2&gt;
  
  
  The fix
&lt;/h2&gt;

&lt;p&gt;On the &lt;code&gt;n8n&lt;/code&gt; service in Compose, the four lines that were tested:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;n8n&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_HOST=${N8N_DOMAIN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_PROTOCOL=https&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_WEBHOOK_URL=https://${N8N_DOMAIN}/&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_PROXY_HOPS=1&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;N8N_DOMAIN&lt;/code&gt; in &lt;code&gt;.env&lt;/code&gt; is only the host, &lt;code&gt;n8n.example.com&lt;/code&gt;, with no scheme and no port. Recreate the container. A process that is already running does not pick up new environment variables:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/whatsapp
sudo docker compose up -d n8n
sudo docker compose logs n8n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The log then says:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Editor is now accessible via:
https://n8n.example.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Caddy in this test used an internal certificate. &lt;code&gt;curl&lt;/code&gt; trusts the root Caddy wrote:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt
curl --cacert ./caddy-root.crt -fsS https://n8n.example.com/healthz
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With a public certificate, drop &lt;code&gt;--cacert ./caddy-root.crt&lt;/code&gt;. Health answers &lt;code&gt;{"status":"ok"}&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  How to check
&lt;/h2&gt;

&lt;p&gt;In the editor, open the Webhook node and the Production URL tab. The address starts with &lt;code&gt;https://&lt;/code&gt; and the domain, and it has no &lt;code&gt;:5678&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Through the API, after login, &lt;code&gt;GET /rest/settings&lt;/code&gt; returns &lt;code&gt;urlBaseWebhook&lt;/code&gt; equal to &lt;code&gt;https://n8n.example.com/&lt;/code&gt;. That is the field used in the table above.&lt;/p&gt;

&lt;p&gt;Publish the workflow and call the production URL through the proxy. In the test, with the path &lt;code&gt;whatsapp&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -fsS -X POST https://n8n.example.com/webhook/whatsapp \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"event":"messages.upsert","data":{"message":{"conversation":"oi do teste"}}}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The response was &lt;code&gt;{"message":"Workflow was started"}&lt;/code&gt;. In the execution, &lt;code&gt;webhookUrl&lt;/code&gt; was &lt;code&gt;https://n8n.example.com/webhook/whatsapp&lt;/code&gt;. If the response is 404 saying the webhook is not registered, the workflow is not published. The right URL with the workflow still a draft still receives nothing.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;The test URL does not replace the production one.&lt;/strong&gt; The Test URL tab uses &lt;code&gt;/webhook-test/&lt;/code&gt; and only answers while the editor is listening. A service that calls n8n all the time uses &lt;code&gt;/webhook/&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The same symptom, with the right variable already in Compose, is handled in &lt;a href="https://nuvits.net/en/blog/n8n-evolution-api-same-vps" rel="noopener noreferrer"&gt;n8n and Evolution API on the same VPS&lt;/a&gt;. A from-scratch install, with Postgres and the runner, is in &lt;a href="https://nuvits.net/en/blog/install-n8n-docker-vps" rel="noopener noreferrer"&gt;How to install n8n with Docker on a VPS&lt;/a&gt;. The VPS that n8n runs on is at &lt;a href="https://nuvits.net/en/n8n-vps" rel="noopener noreferrer"&gt;VPS for n8n&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;Originally published at &lt;a href="https://nuvits.net/en/blog/n8n-webhook-localhost-5678" rel="noopener noreferrer"&gt;https://nuvits.net/en/blog/n8n-webhook-localhost-5678&lt;/a&gt;&lt;/p&gt;

</description>
      <category>n8n</category>
      <category>webhooks</category>
      <category>docker</category>
      <category>selfhosted</category>
    </item>
    <item>
      <title>O webhook do n8n mostra localhost:5678</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Thu, 19 Nov 2026 11:21:22 +0000</pubDate>
      <link>https://dev.to/nuvits/o-webhook-do-n8n-mostra-localhost5678-3c5l</link>
      <guid>https://dev.to/nuvits/o-webhook-do-n8n-mostra-localhost5678-3c5l</guid>
      <description>&lt;p&gt;O nó Webhook do n8n, atrás de um proxy, mostra a URL de produção como &lt;code&gt;http://localhost:5678/webhook/...&lt;/code&gt;. O serviço externo que receber esse endereço chama a própria máquina dele, onde &lt;code&gt;localhost:5678&lt;/code&gt; não é o seu n8n, e o evento não chega.&lt;/p&gt;

&lt;p&gt;O teste foi feito em 19/11/2026 com o n8n &lt;code&gt;2.48.6&lt;/code&gt; (&lt;code&gt;docker.n8n.io/n8nio/n8n:2.48.6&lt;/code&gt;) e o Caddy &lt;code&gt;2.11.9&lt;/code&gt; na frente, no Ubuntu 24.04. O n8n usava PostgreSQL &lt;code&gt;18.7&lt;/code&gt; e o runner &lt;code&gt;n8nio/runners:2.48.6&lt;/code&gt;. O proxy era o mesmo do guia &lt;a href="https://nuvits.net/blog/n8n-evolution-api-mesma-vps" rel="noopener noreferrer"&gt;n8n e Evolution API na mesma VPS&lt;/a&gt;. Cada bloco abaixo é uma subida separada, com o resto do Compose igual.&lt;/p&gt;

&lt;h2&gt;
  
  
  O que o editor mostra
&lt;/h2&gt;

&lt;p&gt;Sem &lt;code&gt;N8N_HOST&lt;/code&gt;, &lt;code&gt;N8N_PROTOCOL&lt;/code&gt;, &lt;code&gt;N8N_WEBHOOK_URL&lt;/code&gt; e &lt;code&gt;N8N_PROXY_HOPS&lt;/code&gt;, o log de inicialização foi:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Editor is now accessible via:
http://localhost:5678
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Depois da conta de owner, &lt;code&gt;GET /rest/settings&lt;/code&gt; devolveu &lt;code&gt;urlBaseWebhook&lt;/code&gt; e &lt;code&gt;urlBaseEditor&lt;/code&gt; como &lt;code&gt;http://localhost:5678/&lt;/code&gt;. O nó Webhook, publicado com o caminho &lt;code&gt;whatsapp&lt;/code&gt;, mostrou a URL de produção &lt;code&gt;http://localhost:5678/webhook/whatsapp&lt;/code&gt;:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F26etlt9e0ylefhmd5oxq.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F26etlt9e0ylefhmd5oxq.webp" alt="Nó Webhook do n8n com a URL de produção em http://localhost:5678/webhook/whatsapp" width="800" height="611"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;O site em si abria em &lt;code&gt;https://n8n.example.com&lt;/code&gt;. O proxy estava certo. A URL que o n8n monta para o webhook é outra conta, feita com variáveis, não com o endereço que o navegador usou.&lt;/p&gt;

&lt;h2&gt;
  
  
  Por que a porta 5678 entra na URL
&lt;/h2&gt;

&lt;p&gt;A &lt;a href="https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/configuration-examples/configure-webhook-urls-with-reverse-proxy" rel="noopener noreferrer"&gt;documentação do n8n&lt;/a&gt; descreve a montagem: sem uma URL de webhook definida, o n8n junta &lt;code&gt;N8N_PROTOCOL&lt;/code&gt;, &lt;code&gt;N8N_HOST&lt;/code&gt; e &lt;code&gt;N8N_PORT&lt;/code&gt;. O padrão é &lt;code&gt;http&lt;/code&gt;, &lt;code&gt;localhost&lt;/code&gt; e &lt;code&gt;5678&lt;/code&gt;. O proxy publica 443. O processo continua em 5678. As duas pontas não coincidem.&lt;/p&gt;

&lt;p&gt;No n8n 2.48.6, medir uma variável de cada vez deu isto. O valor é o &lt;code&gt;urlBaseWebhook&lt;/code&gt; autenticado:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variáveis&lt;/th&gt;
&lt;th&gt;urlBaseWebhook&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;nenhuma&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http://localhost:5678/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;N8N_HOST=n8n.example.com&lt;/code&gt; e &lt;code&gt;N8N_PROTOCOL=https&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://n8n.example.com:5678/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;as duas acima e &lt;code&gt;N8N_WEBHOOK_URL=https://n8n.example.com/&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://n8n.example.com/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;as três acima e &lt;code&gt;N8N_PROXY_HOPS=1&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://n8n.example.com/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;code&gt;N8N_HOST&lt;/code&gt; e &lt;code&gt;N8N_PROTOCOL&lt;/code&gt; trocam o nome e o esquema, e a porta 5678 continua. Quem tira a porta é &lt;code&gt;N8N_WEBHOOK_URL&lt;/code&gt;. A barra no final importa: o valor testado foi &lt;code&gt;https://n8n.example.com/&lt;/code&gt;, e a URL do nó ficou &lt;code&gt;https://n8n.example.com/webhook/whatsapp&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;N8N_PROXY_HOPS&lt;/code&gt; não muda essa string. Ele liga o &lt;code&gt;trust proxy&lt;/code&gt; do Express na quantidade de proxies. Com o Caddy mandando &lt;code&gt;X-Forwarded-For&lt;/code&gt; e o hops em zero, o log do n8n 2.48.6 foi:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;ValidationError: The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false (default). This could indicate a misconfiguration which would prevent express-rate-limit from accurately identifying users.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Com &lt;code&gt;N8N_PROXY_HOPS=1&lt;/code&gt;, o mesmo pedido através do Caddy não gerou essa linha. A execução do webhook passou a registrar &lt;code&gt;x-forwarded-proto&lt;/code&gt; como &lt;code&gt;https&lt;/code&gt;. Um proxy só: o valor é 1. Dois proxies em série: o valor é 2, que este teste não montou.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;N8N_WEBHOOK_URL&lt;/code&gt; existe desde o n8n 2.30.0. A variável antiga &lt;code&gt;WEBHOOK_URL&lt;/code&gt; ainda funciona no 2.48.6 e também produz &lt;code&gt;https://n8n.example.com/&lt;/code&gt;, mas a inicialização avisa:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;WEBHOOK_URL -&amp;gt; Use N8N_WEBHOOK_URL instead, which sets the base URL for both test and production webhooks.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A documentação marca &lt;code&gt;WEBHOOK_URL&lt;/code&gt; como obsoleta a partir do 2.35.0. Use o nome novo.&lt;/p&gt;

&lt;h2&gt;
  
  
  A correção
&lt;/h2&gt;

&lt;p&gt;No serviço &lt;code&gt;n8n&lt;/code&gt; do Compose, as quatro linhas testadas:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;n8n&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_HOST=${N8N_DOMAIN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_PROTOCOL=https&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_WEBHOOK_URL=https://${N8N_DOMAIN}/&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_PROXY_HOPS=1&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;N8N_DOMAIN&lt;/code&gt; no &lt;code&gt;.env&lt;/code&gt; é só o host, &lt;code&gt;n8n.example.com&lt;/code&gt;, sem esquema e sem porta. Recrie o contêiner. O processo que já está rodando não lê as variáveis novas:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/whatsapp
sudo docker compose up -d n8n
sudo docker compose logs n8n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O log passa a dizer:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Editor is now accessible via:
https://n8n.example.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O Caddy deste teste usava certificado interno. O &lt;code&gt;curl&lt;/code&gt; confia na raiz que o Caddy gravou:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt
curl --cacert ./caddy-root.crt -fsS https://n8n.example.com/healthz
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Com certificado público, apague o &lt;code&gt;--cacert ./caddy-root.crt&lt;/code&gt;. O health responde &lt;code&gt;{"status":"ok"}&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Como conferir
&lt;/h2&gt;

&lt;p&gt;Entre no editor, abra o nó Webhook e a aba Production URL. O endereço começa com &lt;code&gt;https://&lt;/code&gt; e com o domínio, e não tem &lt;code&gt;:5678&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Pela API, depois do login, &lt;code&gt;GET /rest/settings&lt;/code&gt; traz &lt;code&gt;urlBaseWebhook&lt;/code&gt; igual a &lt;code&gt;https://n8n.example.com/&lt;/code&gt;. Foi o campo usado na tabela acima.&lt;/p&gt;

&lt;p&gt;Publique o workflow e chame a URL de produção pelo proxy. No teste, com o caminho &lt;code&gt;whatsapp&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -fsS -X POST https://n8n.example.com/webhook/whatsapp \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"event":"messages.upsert","data":{"message":{"conversation":"oi do teste"}}}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A resposta foi &lt;code&gt;{"message":"Workflow was started"}&lt;/code&gt;. Na execução, &lt;code&gt;webhookUrl&lt;/code&gt; ficou &lt;code&gt;https://n8n.example.com/webhook/whatsapp&lt;/code&gt;. Se a resposta for 404 dizendo que o webhook não está registrado, o workflow não está publicado. A URL certa com o workflow em rascunho continua sem receber evento.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;A URL de teste não substitui a de produção.&lt;/strong&gt; A aba Test URL usa &lt;code&gt;/webhook-test/&lt;/code&gt; e só responde enquanto o editor está escutando. Um serviço que chama o n8n o tempo todo usa &lt;code&gt;/webhook/&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;O mesmo sintoma, com a variável certa já no Compose, está resolvido no guia &lt;a href="https://nuvits.net/blog/n8n-evolution-api-mesma-vps" rel="noopener noreferrer"&gt;n8n e Evolution API na mesma VPS&lt;/a&gt;. A instalação do zero, com Postgres e runner, está em &lt;a href="https://nuvits.net/blog/como-instalar-n8n-docker-vps" rel="noopener noreferrer"&gt;Como instalar o n8n com Docker numa VPS&lt;/a&gt;. A VPS em que esse n8n roda está em &lt;a href="https://nuvits.net/vps-para-n8n" rel="noopener noreferrer"&gt;VPS para n8n&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;Publicado originalmente em &lt;a href="https://nuvits.net/blog/webhook-n8n-localhost-5678" rel="noopener noreferrer"&gt;https://nuvits.net/blog/webhook-n8n-localhost-5678&lt;/a&gt;&lt;/p&gt;

</description>
      <category>braziliandevs</category>
      <category>portugues</category>
      <category>n8n</category>
      <category>webhooks</category>
    </item>
    <item>
      <title>n8n and Evolution API on the same VPS</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Thu, 19 Nov 2026 11:21:12 +0000</pubDate>
      <link>https://dev.to/nuvits/n8n-and-evolution-api-on-the-same-vps-2j4i</link>
      <guid>https://dev.to/nuvits/n8n-and-evolution-api-on-the-same-vps-2j4i</guid>
      <description>&lt;p&gt;This guide runs n8n and Evolution API on the same Ubuntu 24.04 VPS. Both stay on the internal Docker Compose network. Only Caddy publishes a port, with HTTPS. Evolution API delivers the WhatsApp event to n8n's webhook, and n8n calls the API's text endpoint back.&lt;/p&gt;

&lt;p&gt;The test ran on 19 November 2026 on Ubuntu 24.04, with Docker Engine 29.10.0 and Compose v5.8.0. The images were pinned: n8n and the runner at &lt;code&gt;2.48.6&lt;/code&gt;, Evolution API at &lt;code&gt;v2.3.7&lt;/code&gt;, PostgreSQL at &lt;code&gt;18.7&lt;/code&gt; and &lt;code&gt;15.20&lt;/code&gt;, Redis at &lt;code&gt;7.4.12&lt;/code&gt; and Caddy at &lt;code&gt;2.11.9&lt;/code&gt;. There was no public domain, so the certificate was Caddy's internal one. The domain section names the line you remove when the name is real. No phone was paired: a QR code was generated, the &lt;code&gt;qrcode.updated&lt;/code&gt; and &lt;code&gt;connection.update&lt;/code&gt; events reached n8n, and sending a text returned the error of an instance that is not connected yet.&lt;/p&gt;

&lt;p&gt;If n8n or Evolution API is already running in its own directory, &lt;a href="https://nuvits.net/en/blog/install-n8n-docker-vps" rel="noopener noreferrer"&gt;How to install n8n with Docker on a VPS&lt;/a&gt; and &lt;a href="https://nuvits.net/en/blog/install-evolution-api-docker-vps" rel="noopener noreferrer"&gt;How to install Evolution API on a VPS&lt;/a&gt; still apply. This guide puts the two of them behind one proxy.&lt;/p&gt;

&lt;h2&gt;
  
  
  What you need
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;An Ubuntu 24.04 64-bit VPS and SSH as a user with &lt;code&gt;sudo&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Two names where you can create DNS records, once you want a public certificate. The examples are &lt;code&gt;n8n.example.com&lt;/code&gt; and &lt;code&gt;api.example.com&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;An email address for the ACME account, on the day the certificate stops being internal.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;There are seven containers: Caddy, n8n, the runner, n8n's PostgreSQL, Evolution API, the API's PostgreSQL and Redis. The n8n guide on its own treats 2 vCPU and 4 GB as the floor, and the Evolution API guide asks for the same for the API with its database and cache. Together, treat 4 vCPU and 8 GB as a tight floor. The card beside this article points at a plan above that. Add up whatever else will run on the machine before you choose.&lt;/p&gt;

&lt;p&gt;If Docker is not installed yet, use Docker's official &lt;code&gt;apt&lt;/code&gt; repository. The tested steps are in &lt;a href="https://nuvits.net/en/blog/install-n8n-docker-vps" rel="noopener noreferrer"&gt;How to install n8n with Docker on a VPS&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  The two addresses
&lt;/h2&gt;

&lt;p&gt;n8n listens on 5678 only on the Compose network. Evolution API listens on 8080 on the same network. Caddy is what talks to the internet, on ports 80 and 443.&lt;/p&gt;

&lt;p&gt;That splits two URLs that are not the same thing:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The URL the n8n editor shows, &lt;code&gt;https://n8n.example.com/webhook/whatsapp&lt;/code&gt;, is the public one. A service outside the VPS uses it.&lt;/li&gt;
&lt;li&gt;The URL Evolution API calls from the same Compose project is &lt;code&gt;http://n8n:5678/webhook/whatsapp&lt;/code&gt;. The name &lt;code&gt;n8n&lt;/code&gt; is the service. The traffic does not leave the host and does not depend on a public certificate already existing.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The path, &lt;code&gt;whatsapp&lt;/code&gt;, has to match on both sides. The host is what changes.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Docker bypasses ufw.&lt;/strong&gt; Only Caddy publishes a port. n8n, the API and the databases have no &lt;code&gt;ports:&lt;/code&gt;. The reason and the test are in &lt;a href="https://nuvits.net/en/blog/docker-port-still-open-with-ufw" rel="noopener noreferrer"&gt;Docker's published port stays open with ufw&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  The files
&lt;/h2&gt;

&lt;p&gt;Create the directory. Its name becomes the volume prefix:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/whatsapp &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd&lt;/span&gt; ~/whatsapp
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Secrets
&lt;/h3&gt;

&lt;p&gt;Generate n8n's encryption key and the runner token with 32 bytes, and the passwords and the API key with 16:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;openssl rand -hex 32
openssl rand -hex 16
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Run the first command twice. Run the second three times: the n8n Postgres password, the Evolution API Postgres password and &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;. Do not reuse the sample &lt;code&gt;429683C4C977415CAAFCCE10F7D57E11&lt;/code&gt; that ships in Evolution API's &lt;code&gt;.env.example&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ini"&gt;&lt;code&gt;&lt;span class="na"&gt;N8N_VERSION&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mf"&gt;2.48&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mi"&gt;6&lt;/span&gt;
&lt;span class="na"&gt;N8N_DOMAIN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;
&lt;span class="na"&gt;EVOLUTION_DOMAIN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;
&lt;span class="na"&gt;ACME_EMAIL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;you&lt;/span&gt;@&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;
&lt;span class="na"&gt;GENERIC_TIMEZONE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nc"&gt;America&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="nc"&gt;Sao_Paulo&lt;/span&gt;

&lt;span class="na"&gt;N8N_ENCRYPTION_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;paste&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;the&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;32&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="kt"&gt;byte&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;key&lt;/span&gt;
&lt;span class="na"&gt;N8N_RUNNERS_AUTH_TOKEN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;paste&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;the&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;32&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="kt"&gt;byte&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;token&lt;/span&gt;
&lt;span class="na"&gt;N8N_POSTGRES_USER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;
&lt;span class="na"&gt;N8N_POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;paste&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;the&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;password&lt;/span&gt;
&lt;span class="na"&gt;N8N_POSTGRES_DB&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;

&lt;span class="na"&gt;SERVER_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//api.example.com&lt;/span&gt;
&lt;span class="na"&gt;AUTHENTICATION_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;paste&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;the&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;key&lt;/span&gt;
&lt;span class="na"&gt;DATABASE_PROVIDER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;postgresql&lt;/span&gt;
&lt;span class="na"&gt;DATABASE_CONNECTION_URI&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;postgresql&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//evolution:paste-the-api-password@evolution-postgres:5432/evolution_db?schema=evolution_api&lt;/span&gt;
&lt;span class="na"&gt;DATABASE_CONNECTION_CLIENT_NAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;
&lt;span class="na"&gt;CACHE_REDIS_ENABLED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="na"&gt;CACHE_REDIS_URI&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//evolution-redis:6379/6&lt;/span&gt;
&lt;span class="na"&gt;CACHE_REDIS_PREFIX_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;
&lt;span class="na"&gt;TELEMETRY_ENABLED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;
&lt;span class="na"&gt;LOG_LEVEL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="no"&gt;ERROR&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="no"&gt;WARN&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="no"&gt;INFO&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="no"&gt;LOG&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="no"&gt;WEBHOOKS&lt;/span&gt;
&lt;span class="na"&gt;LANGUAGE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;en&lt;/span&gt;

&lt;span class="na"&gt;POSTGRES_DATABASE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution_db&lt;/span&gt;
&lt;span class="na"&gt;POSTGRES_USERNAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;
&lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;paste&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;the&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;password&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;chmod 600 .env
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The password inside &lt;code&gt;DATABASE_CONNECTION_URI&lt;/code&gt; and &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; are the same one. If it contains &lt;code&gt;@&lt;/code&gt;, &lt;code&gt;:&lt;/code&gt;, &lt;code&gt;/&lt;/code&gt; or &lt;code&gt;#&lt;/code&gt;, percent-encode those characters in the URI. &lt;code&gt;N8N_VERSION&lt;/code&gt; pins n8n and the runner, which have to be the same version. &lt;code&gt;2.48.6&lt;/code&gt; was the &lt;code&gt;stable&lt;/code&gt; release on 19 November 2026 on &lt;a href="https://github.com/n8n-io/n8n/releases" rel="noopener noreferrer"&gt;n8n's releases&lt;/a&gt;. The Evolution API tag is &lt;code&gt;v2.3.7&lt;/code&gt;, which is the version in the repository &lt;code&gt;package.json&lt;/code&gt; and the published tag in place of &lt;code&gt;latest&lt;/code&gt;. Set &lt;code&gt;GENERIC_TIMEZONE&lt;/code&gt; to your IANA time zone if it is not São Paulo. The lab used &lt;code&gt;America/Sao_Paulo&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;SERVER_URL&lt;/code&gt;, &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;, &lt;code&gt;DATABASE_PROVIDER&lt;/code&gt;, &lt;code&gt;DATABASE_CONNECTION_URI&lt;/code&gt;, &lt;code&gt;CACHE_REDIS_ENABLED&lt;/code&gt; and &lt;code&gt;CACHE_REDIS_URI&lt;/code&gt; are in the current &lt;code&gt;.env.example&lt;/code&gt;. &lt;code&gt;TELEMETRY_ENABLED=false&lt;/code&gt; turns off the reporting the sample leaves on.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Keep a copy of .env off the VPS.&lt;/strong&gt; n8n cannot read a restored credential without &lt;code&gt;N8N_ENCRYPTION_KEY&lt;/code&gt;. Evolution API will not authenticate a call without &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3&gt;
  
  
  Caddyfile
&lt;/h3&gt;

&lt;p&gt;The lab had no public domain. &lt;code&gt;local_certs&lt;/code&gt; makes Caddy issue a certificate from its internal authority for both names. This is the file that actually started:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;{
    email {$ACME_EMAIL}
    local_certs
}

{$N8N_DOMAIN} {
    reverse_proxy n8n:5678 {
        flush_interval -1
    }
}

{$EVOLUTION_DOMAIN} {
    reverse_proxy evolution-api:8080
}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;flush_interval -1&lt;/code&gt; comes from n8n's Caddy example: it turns off response buffering. &lt;code&gt;reverse_proxy&lt;/code&gt; sends &lt;code&gt;X-Forwarded-For&lt;/code&gt;, &lt;code&gt;X-Forwarded-Proto&lt;/code&gt; and &lt;code&gt;X-Forwarded-Host&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;With a public domain, delete the &lt;code&gt;local_certs&lt;/code&gt; line and leave the rest. &lt;code&gt;caddy validate&lt;/code&gt; accepted that file without &lt;code&gt;local_certs&lt;/code&gt;. Caddy then requests the public certificate on its own, as long as both names point at the VPS IPv4 and ports 80 and 443 are reachable. The internal certificate from this test lasts a few hours and the issuer is &lt;code&gt;Caddy Local Authority&lt;/code&gt;. Do not use it in place of the public certificate.&lt;/p&gt;

&lt;h3&gt;
  
  
  Compose
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;caddy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;caddy:2.11.9&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;unless-stopped&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"80:80"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"443:443"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"443:443/udp"&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_DOMAIN=${N8N_DOMAIN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;EVOLUTION_DOMAIN=${EVOLUTION_DOMAIN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;ACME_EMAIL=${ACME_EMAIL}&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;./Caddyfile:/etc/caddy/Caddyfile:ro&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;caddy_data:/data&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;caddy_config:/config&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;n8n&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-api&lt;/span&gt;

  &lt;span class="na"&gt;n8n-postgres&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:18.7&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;POSTGRES_USER=${N8N_POSTGRES_USER}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;POSTGRES_PASSWORD=${N8N_POSTGRES_PASSWORD}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;POSTGRES_DB=${N8N_POSTGRES_DB}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;PGDATA=/var/lib/postgresql/data&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;n8n_db:/var/lib/postgresql/data&lt;/span&gt;
    &lt;span class="na"&gt;healthcheck&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;test&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"CMD-SHELL"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"pg_isready -h localhost -U ${N8N_POSTGRES_USER} -d ${N8N_POSTGRES_DB}"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
      &lt;span class="na"&gt;interval&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;retries&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;

  &lt;span class="na"&gt;n8n&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;docker.n8n.io/n8nio/n8n:${N8N_VERSION}&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_HOST=${N8N_DOMAIN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_PORT=5678&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_PROTOCOL=https&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_WEBHOOK_URL=https://${N8N_DOMAIN}/&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_PROXY_HOPS=1&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;GENERIC_TIMEZONE=${GENERIC_TIMEZONE}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;TZ=${GENERIC_TIMEZONE}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_TYPE=postgresdb&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_POSTGRESDB_HOST=n8n-postgres&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_POSTGRESDB_PORT=5432&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_POSTGRESDB_DATABASE=${N8N_POSTGRES_DB}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_POSTGRESDB_USER=${N8N_POSTGRES_USER}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_POSTGRESDB_PASSWORD=${N8N_POSTGRES_PASSWORD}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_RUNNERS_MODE=external&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_RUNNERS_AUTH_TOKEN=${N8N_RUNNERS_AUTH_TOKEN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;n8n_data:/home/node/.n8n&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;n8n-postgres&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_healthy&lt;/span&gt;

  &lt;span class="na"&gt;n8n-runner&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;n8nio/runners:${N8N_VERSION}&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_RUNNERS_AUTH_TOKEN=${N8N_RUNNERS_AUTH_TOKEN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_RUNNERS_TASK_BROKER_URI=http://n8n:5679&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;n8n&lt;/span&gt;

  &lt;span class="na"&gt;evolution-api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evoapicloud/evolution-api:v2.3.7&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;env_file&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;.env&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution_instances:/evolution/instances&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-redis&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-postgres&lt;/span&gt;

  &lt;span class="na"&gt;evolution-redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;redis:7.4.12&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;redis-server --port 6379 --appendonly yes&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution_redis:/data&lt;/span&gt;
    &lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;default&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;aliases&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-redis&lt;/span&gt;

  &lt;span class="na"&gt;evolution-postgres&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:15.20&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_DATABASE}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_USER&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_USERNAME}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_PASSWORD}&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"postgres"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-c"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"max_connections=1000"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution_postgres:/var/lib/postgresql/data&lt;/span&gt;

&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;caddy_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;caddy_config&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;n8n_db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;n8n_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution_instances&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution_redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution_postgres&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;What this file does, and what the test saw:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;N8N_WEBHOOK_URL&lt;/code&gt; is the webhook base URL from n8n 2.30.0 on. Without it, the editor builds &lt;code&gt;http://localhost:5678/&lt;/code&gt;. &lt;code&gt;N8N_PROXY_HOPS=1&lt;/code&gt; makes n8n trust the single proxy in front. &lt;a href="https://nuvits.net/en/blog/n8n-webhook-localhost-5678" rel="noopener noreferrer"&gt;The n8n webhook shows localhost:5678&lt;/a&gt; measures both variables.&lt;/li&gt;
&lt;li&gt;The external runner is the mode the n8n docs recommend for production. The image &lt;code&gt;n8nio/runners:2.48.6&lt;/code&gt; uses the same version as n8n.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;PGDATA=/var/lib/postgresql/data&lt;/code&gt; on Postgres 18.7 keeps the database inside the volume. Do not delete that line.&lt;/li&gt;
&lt;li&gt;Evolution API starts from the official &lt;code&gt;docker-compose.yaml&lt;/code&gt; and drops the &lt;code&gt;dokploy-network&lt;/code&gt;, which does not exist on a new VPS. The image is &lt;code&gt;v2.3.7&lt;/code&gt; instead of &lt;code&gt;latest&lt;/code&gt;. Postgres is &lt;code&gt;15.20&lt;/code&gt; and Redis is &lt;code&gt;7.4.12&lt;/code&gt;, instead of the floating tags in the official file.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;env_file&lt;/code&gt; hands the whole &lt;code&gt;.env&lt;/code&gt; to the API. It ignores n8n's keys. The two Postgres passwords have different names on purpose: a single &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; in the same file would be read by both services.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Start
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/whatsapp
sudo docker compose up -d
sudo docker compose ps
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;n8n waits until Postgres is healthy. Evolution API applies the Prisma migrations on startup and only then listens. Follow the logs until these two lines:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose logs n8n
sudo docker compose logs evolution-api
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For n8n, the useful ending is &lt;code&gt;Editor is now accessible via:&lt;/code&gt; followed by &lt;code&gt;https://n8n.example.com&lt;/code&gt;. For the API, &lt;code&gt;HTTP - ON: 8080&lt;/code&gt; and version &lt;code&gt;v2.3.7&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The internal certificate lives at &lt;code&gt;caddy/pki/authorities/local/root.crt&lt;/code&gt; in Caddy's volume. For this lab's &lt;code&gt;curl&lt;/code&gt; to trust it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt
curl --cacert ./caddy-root.crt -fsS https://n8n.example.com/healthz
curl --cacert ./caddy-root.crt -fsS https://api.example.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The first answers &lt;code&gt;{"status":"ok"}&lt;/code&gt;. The second answers JSON with &lt;code&gt;"version":"2.3.7"&lt;/code&gt; and &lt;code&gt;"message":"Welcome to the Evolution API, it is working!"&lt;/code&gt;. With a public certificate, drop &lt;code&gt;--cacert ./caddy-root.crt&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;In the lab, &lt;code&gt;n8n.example.com&lt;/code&gt; and &lt;code&gt;api.example.com&lt;/code&gt; pointed at &lt;code&gt;127.0.0.1&lt;/code&gt; in the machine's own &lt;code&gt;/etc/hosts&lt;/code&gt;. On your VPS, with a public domain, they point at the IPv4 address in DNS.&lt;/p&gt;

&lt;h2&gt;
  
  
  The instance and the webhook
&lt;/h2&gt;

&lt;p&gt;Evolution API v2.3.7 creates the instance at &lt;code&gt;POST /instance/create&lt;/code&gt;. The body requires &lt;code&gt;instanceName&lt;/code&gt; and &lt;code&gt;integration&lt;/code&gt;. &lt;code&gt;WHATSAPP-BAILEYS&lt;/code&gt; is the WhatsApp Web connection. The API's own documentation warns that it can have limitations compared with Meta's official API.&lt;/p&gt;

&lt;p&gt;Load the key and create the &lt;code&gt;atendimento&lt;/code&gt; instance:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;set&lt;/span&gt; -a &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; . ./.env &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;set&lt;/span&gt; +a
curl --cacert ./caddy-root.crt -fsS -X POST https://api.example.com/instance/create \
  -H &lt;span class="s2"&gt;"apikey: $AUTHENTICATION_API_KEY"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"instanceName":"atendimento","integration":"WHATSAPP-BAILEYS","qrcode":false}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The response is 201. Keep the &lt;code&gt;instanceId&lt;/code&gt;. The &lt;code&gt;hash&lt;/code&gt; is an instance token: do not paste it into a chat or a repository.&lt;/p&gt;

&lt;p&gt;The v2.3.7 webhook is not a flat list of fields. The body has a &lt;code&gt;webhook&lt;/code&gt; object, which is what the repository schema requires (&lt;code&gt;enabled&lt;/code&gt; and &lt;code&gt;url&lt;/code&gt; are mandatory):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -fsS -X POST https://api.example.com/webhook/set/atendimento \
  -H &lt;span class="s2"&gt;"apikey: $AUTHENTICATION_API_KEY"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"webhook":{"enabled":true,"url":"http://n8n:5678/webhook/whatsapp","byEvents":false,"base64":false,"events":["MESSAGES_UPSERT","QRCODE_UPDATED","CONNECTION_UPDATE"]}}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The response is 201 and returns the same URL. Check it with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -fsS https://api.example.com/webhook/find/atendimento \
  -H &lt;span class="s2"&gt;"apikey: $AUTHENTICATION_API_KEY"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;MESSAGES_UPSERT&lt;/code&gt; is the new-message event. &lt;code&gt;QRCODE_UPDATED&lt;/code&gt; and &lt;code&gt;CONNECTION_UPDATE&lt;/code&gt; show the connection before any message exists. &lt;code&gt;byEvents: false&lt;/code&gt; sends everything to the same URL. With &lt;code&gt;true&lt;/code&gt;, the API appends the event name to the path and n8n no longer finds the webhook.&lt;/p&gt;

&lt;p&gt;The QR code, to scan on the phone under Linked devices:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -fsS https://api.example.com/instance/connect/atendimento \
  -H &lt;span class="s2"&gt;"apikey: $AUTHENTICATION_API_KEY"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The response carries &lt;code&gt;base64&lt;/code&gt; (the QR image) and &lt;code&gt;count&lt;/code&gt;. In this test &lt;code&gt;count&lt;/code&gt; reached 1 and the API log recorded &lt;code&gt;qrcode.updated&lt;/code&gt; and &lt;code&gt;connection.update&lt;/code&gt; with &lt;code&gt;state: connecting&lt;/code&gt;, both aimed at &lt;code&gt;http://n8n:5678/webhook/whatsapp&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  The workflow in n8n
&lt;/h2&gt;

&lt;p&gt;Open &lt;code&gt;https://n8n.example.com&lt;/code&gt;, create the owner account and a workflow with two nodes.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;A Webhook node, POST method, path &lt;code&gt;whatsapp&lt;/code&gt;, immediate response. Publish the workflow. The production URL becomes &lt;code&gt;https://n8n.example.com/webhook/whatsapp&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;An HTTP Request node, POST method, URL &lt;code&gt;http://evolution-api:8080/message/sendText/atendimento&lt;/code&gt;. An &lt;code&gt;apikey&lt;/code&gt; header with the value of &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;. A JSON body with &lt;code&gt;number&lt;/code&gt; (country code and area code, digits only) and &lt;code&gt;text&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Connect the Webhook output to the HTTP Request input. Publish again. In the test, the panel showed this production URL, with Authentication set to None:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fc9xo7uzedxcix4z7mukj.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fc9xo7uzedxcix4z7mukj.webp" alt="n8n production webhook URL https://n8n.example.com/webhook/whatsapp on the workflow that calls Evolution API" width="800" height="611"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;A workflow published on a public name accepts a POST from anyone. Evolution API in this stack calls &lt;code&gt;http://n8n:5678&lt;/code&gt; from inside and does not need that public URL to deliver the event. In the test, &lt;code&gt;qrcode.updated&lt;/code&gt; and &lt;code&gt;connection.update&lt;/code&gt; also ran the HTTP Request node and got the same 500. Those events are not messages: &lt;code&gt;sendText&lt;/code&gt; only makes sense when the event is &lt;code&gt;MESSAGES_UPSERT&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The production webhook exists only while the workflow is published. Before that, &lt;code&gt;POST /webhook/whatsapp&lt;/code&gt; answers 404 and the body says the workflow has to be active.&lt;/p&gt;

&lt;p&gt;A POST from outside, through Caddy, confirms the public path. With the workflow published:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -fsS -X POST https://n8n.example.com/webhook/whatsapp \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"event":"messages.upsert","data":{"message":{"conversation":"oi do teste"}}}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The response is &lt;code&gt;{"message":"Workflow was started"}&lt;/code&gt;. In the execution, n8n records &lt;code&gt;webhookUrl&lt;/code&gt; as &lt;code&gt;https://n8n.example.com/webhook/whatsapp&lt;/code&gt; and &lt;code&gt;x-forwarded-proto&lt;/code&gt; as &lt;code&gt;https&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Evolution API, from its own container, uses the internal URL. In the test, each &lt;code&gt;qrcode.updated&lt;/code&gt; became an execution with status success in n8n. It is the same webhook. It is not a second workflow.&lt;/p&gt;

&lt;h2&gt;
  
  
  Before you scan the QR code
&lt;/h2&gt;

&lt;p&gt;Without the phone paired, the send does not leave. The command, at both moments, was this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -sS -o /tmp/send-text.json -w &lt;span class="s1"&gt;'%{http_code}\n'&lt;/span&gt; \
  -X POST https://api.example.com/message/sendText/atendimento \
  -H &lt;span class="s2"&gt;"apikey: $AUTHENTICATION_API_KEY"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"number":"5511999999999","text":"teste de envio antes do pareamento"}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The status was 500 both times. Right after create, before &lt;code&gt;connect&lt;/code&gt;, the inner message was &lt;code&gt;Cannot read properties of undefined (reading 'onWhatsApp')&lt;/code&gt;. After &lt;code&gt;connect&lt;/code&gt;, with the instance at &lt;code&gt;connecting&lt;/code&gt;, the body was:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;500&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"error"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Internal Server Error"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"response"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"message"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Cannot read properties of undefined (reading 'find')"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The same 500 showed up in the n8n execution when the HTTP Request node called &lt;code&gt;http://evolution-api:8080/message/sendText/atendimento&lt;/code&gt;. The workflow was marked successful because the node was set to continue on error. The execution item stored the text &lt;code&gt;500 - "{\"status\":500,...}"&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;That is not a message delivered on WhatsApp. It is the API answering before a session exists. After the phone accepts the QR code, the same &lt;code&gt;POST&lt;/code&gt; is the send. This lab stopped before that acceptance: there was no phone, so no message left for a real number.&lt;/p&gt;

&lt;p&gt;The &lt;code&gt;sendText&lt;/code&gt; body on v2.3.7 is the repository's &lt;code&gt;SendTextDto&lt;/code&gt;: &lt;code&gt;number&lt;/code&gt; and &lt;code&gt;text&lt;/code&gt;. The header is &lt;code&gt;apikey&lt;/code&gt;, not &lt;code&gt;Authorization&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What survives a restart
&lt;/h2&gt;

&lt;p&gt;With the instance and the webhook stored, restart only the API:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose restart evolution-api
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Wait for &lt;code&gt;HTTP - ON: 8080&lt;/code&gt; again and repeat &lt;code&gt;GET /instance/fetchInstances&lt;/code&gt; and &lt;code&gt;GET /webhook/find/atendimento&lt;/code&gt;. In the test, &lt;code&gt;atendimento&lt;/code&gt; was still in the list and the webhook URL was still &lt;code&gt;http://n8n:5678/webhook/whatsapp&lt;/code&gt;. The WhatsApp session, once it exists, lives in the &lt;code&gt;evolution_instances&lt;/code&gt; volume.&lt;/p&gt;

&lt;p&gt;Recreate n8n without deleting the volume:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose up -d --force-recreate n8n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the test, the owner login answered 200 again and &lt;code&gt;urlBaseWebhook&lt;/code&gt; was still &lt;code&gt;https://n8n.example.com/&lt;/code&gt;. The account lives in Postgres 18.7 and the key lives in the &lt;code&gt;n8n_data&lt;/code&gt; volume.&lt;/p&gt;

&lt;p&gt;The backup this test wrote:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/whatsapp
&lt;span class="nb"&gt;set&lt;/span&gt; -a &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; . ./.env &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;set&lt;/span&gt; +a
sudo docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T n8n-postgres pg_dumpall -U &lt;span class="s2"&gt;"$N8N_POSTGRES_USER"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; n8n-db-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql
grep -c &lt;span class="s2"&gt;"PostgreSQL database cluster dump complete"&lt;/span&gt; n8n-db-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql
sudo docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T evolution-postgres pg_dump -U &lt;span class="s2"&gt;"$POSTGRES_USERNAME"&lt;/span&gt; &lt;span class="s2"&gt;"$POSTGRES_DATABASE"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; evolution-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql
grep -c &lt;span class="s2"&gt;"PostgreSQL database dump complete"&lt;/span&gt; evolution-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql
sudo docker run --rm --volumes-from &lt;span class="s2"&gt;"$(sudo docker compose ps -q n8n)"&lt;/span&gt; -v &lt;span class="s2"&gt;"$PWD"&lt;/span&gt;:/backup ubuntu:24.04 tar czf /backup/n8n-data-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.tar.gz /home/node/.n8n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Both &lt;code&gt;grep&lt;/code&gt; commands printed &lt;code&gt;1&lt;/code&gt;. Copy the &lt;code&gt;.sql&lt;/code&gt; files, the &lt;code&gt;.tar.gz&lt;/code&gt; and &lt;code&gt;.env&lt;/code&gt; to another machine. A copy that stays only on this disk is lost with the VPS. The n8n guide walks through the restore.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Never run &lt;code&gt;docker compose down -v&lt;/code&gt; in this directory.&lt;/strong&gt; &lt;code&gt;-v&lt;/code&gt; deletes the volumes: n8n's database, the key, Evolution API's database and the WhatsApp sessions.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Update
&lt;/h2&gt;

&lt;p&gt;The tags in this guide do not float. Updating means changing the number in &lt;code&gt;.env&lt;/code&gt; or in Compose, reading the release note and recreating.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/whatsapp
sudo docker compose pull
sudo docker compose up -d
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the test, &lt;code&gt;pull&lt;/code&gt; of the seven pinned images reported they were already downloaded, and &lt;code&gt;up -d&lt;/code&gt; left the containers in place. Changing &lt;code&gt;N8N_VERSION&lt;/code&gt; pulls n8n and the runner together. n8n applies migrations on startup, and switching the tag back does not undo a migration: the dump comes first. Evolution API &lt;code&gt;v2.3.7&lt;/code&gt; does not tell you on its own when a version jump needs a manual database step. Read the note in the repository before you change the tag.&lt;/p&gt;

&lt;p&gt;Moving Postgres off 18.7 to another major version, or the API's 15.20, is a dump and restore, not a tag change.&lt;/p&gt;

&lt;h2&gt;
  
  
  Next step
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;A webhook that still shows &lt;code&gt;localhost:5678&lt;/code&gt; is covered in &lt;a href="https://nuvits.net/en/blog/n8n-webhook-localhost-5678" rel="noopener noreferrer"&gt;The n8n webhook shows localhost:5678&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;A VPS for one service is at &lt;a href="https://nuvits.net/en/n8n-vps" rel="noopener noreferrer"&gt;VPS for n8n&lt;/a&gt; and &lt;a href="https://nuvits.net/en/evolution-api-vps" rel="noopener noreferrer"&gt;VPS for Evolution API&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;If Docker itself is still to be installed, the path is &lt;a href="https://nuvits.net/en/docker-vps" rel="noopener noreferrer"&gt;Docker VPS&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;Originally published at &lt;a href="https://nuvits.net/en/blog/n8n-evolution-api-same-vps" rel="noopener noreferrer"&gt;https://nuvits.net/en/blog/n8n-evolution-api-same-vps&lt;/a&gt;&lt;/p&gt;

</description>
      <category>n8n</category>
      <category>whatsapp</category>
      <category>docker</category>
      <category>selfhosted</category>
    </item>
    <item>
      <title>n8n e Evolution API na mesma VPS</title>
      <dc:creator>Fernando Chagas</dc:creator>
      <pubDate>Thu, 19 Nov 2026 11:20:50 +0000</pubDate>
      <link>https://dev.to/nuvits/n8n-e-evolution-api-na-mesma-vps-4g2o</link>
      <guid>https://dev.to/nuvits/n8n-e-evolution-api-na-mesma-vps-4g2o</guid>
      <description>&lt;p&gt;Este guia sobe o n8n e a Evolution API na mesma VPS Ubuntu 24.04. Os dois ficam numa rede interna do Docker Compose. Só o Caddy publica porta, com HTTPS. A Evolution API entrega o evento do WhatsApp no webhook do n8n, e o n8n chama de volta o endpoint de texto da API.&lt;/p&gt;

&lt;p&gt;O teste foi feito em 19/11/2026 no Ubuntu 24.04, com Docker Engine 29.10.0 e Compose v5.8.0. As imagens estavam fixadas: n8n e runner &lt;code&gt;2.48.6&lt;/code&gt;, Evolution API &lt;code&gt;v2.3.7&lt;/code&gt;, PostgreSQL &lt;code&gt;18.7&lt;/code&gt; e &lt;code&gt;15.20&lt;/code&gt;, Redis &lt;code&gt;7.4.12&lt;/code&gt; e Caddy &lt;code&gt;2.11.9&lt;/code&gt;. Não havia um domínio público, então o certificado foi o interno do Caddy. A seção do domínio diz a linha que sai quando o nome é de verdade. O celular não foi pareado: o QR chegou a ser gerado, os eventos &lt;code&gt;qrcode.updated&lt;/code&gt; e &lt;code&gt;connection.update&lt;/code&gt; entraram no n8n, e o envio de texto respondeu o erro de instância ainda não conectada.&lt;/p&gt;

&lt;p&gt;Se o n8n ou a Evolution API já estão no ar em pastas separadas, os guias &lt;a href="https://nuvits.net/blog/como-instalar-n8n-docker-vps" rel="noopener noreferrer"&gt;Como instalar o n8n com Docker numa VPS&lt;/a&gt; e &lt;a href="https://nuvits.net/blog/como-instalar-evolution-api-docker-vps" rel="noopener noreferrer"&gt;Como instalar a Evolution API em uma VPS&lt;/a&gt; continuam valendo. Este aqui junta os dois atrás do mesmo proxy.&lt;/p&gt;

&lt;h2&gt;
  
  
  O que você vai precisar
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Uma VPS com Ubuntu 24.04 de 64 bits e SSH com um usuário que tenha &lt;code&gt;sudo&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Dois nomes em que você consiga criar registros DNS, quando for usar certificado público. Os exemplos são &lt;code&gt;n8n.example.com&lt;/code&gt; e &lt;code&gt;api.example.com&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Um e-mail para a conta ACME, no dia em que o certificado deixar de ser interno.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;São sete contêineres: Caddy, n8n, runner, PostgreSQL do n8n, Evolution API, PostgreSQL da API e Redis. O guia do n8n sozinho trata 2 vCPU e 4 GB como piso, e o da Evolution API pede o mesmo para a API com banco e cache. Juntos, trate 4 vCPU e 8 GB como o piso apertado. O cartão ao lado aponta um plano acima disso. Some o que mais for rodar na mesma máquina antes de escolher.&lt;/p&gt;

&lt;p&gt;O Docker, se ainda não estiver instalado, segue o repositório &lt;code&gt;apt&lt;/code&gt; oficial. O passo a passo testado está em &lt;a href="https://nuvits.net/blog/como-instalar-n8n-docker-vps" rel="noopener noreferrer"&gt;Como instalar o n8n com Docker numa VPS&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Os dois endereços
&lt;/h2&gt;

&lt;p&gt;O n8n escuta 5678 só na rede do Compose. A Evolution API escuta 8080 na mesma rede. Quem fala com a internet é o Caddy, nas portas 80 e 443.&lt;/p&gt;

&lt;p&gt;Isso separa duas URLs que não são a mesma coisa:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A URL que o editor do n8n mostra, &lt;code&gt;https://n8n.example.com/webhook/whatsapp&lt;/code&gt;, é a pública. Um serviço fora da VPS usa essa.&lt;/li&gt;
&lt;li&gt;A URL que a Evolution API, no mesmo Compose, chama é &lt;code&gt;http://n8n:5678/webhook/whatsapp&lt;/code&gt;. O nome &lt;code&gt;n8n&lt;/code&gt; é o serviço. O tráfego não sai para a internet e não depende de o certificado público já existir.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;O caminho, &lt;code&gt;whatsapp&lt;/code&gt;, tem de ser o mesmo nos dois lados. O que muda é o host.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;O Docker passa por cima do ufw.&lt;/strong&gt; Só o Caddy publica porta. O n8n, a API e os bancos ficam sem &lt;code&gt;ports:&lt;/code&gt;. O motivo e o teste estão em &lt;a href="https://nuvits.net/blog/porta-do-docker-aberta-com-ufw" rel="noopener noreferrer"&gt;A porta do Docker continua aberta com o ufw&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Os arquivos
&lt;/h2&gt;

&lt;p&gt;Crie a pasta. O nome dela vira prefixo dos volumes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/whatsapp &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd&lt;/span&gt; ~/whatsapp
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Segredos
&lt;/h3&gt;

&lt;p&gt;Gere a chave de criptografia do n8n e o token do runner com 32 bytes, e as senhas e a chave da API com 16:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;openssl rand -hex 32
openssl rand -hex 16
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Rode o primeiro comando duas vezes e o segundo, três: senha do Postgres do n8n, senha do Postgres da Evolution API e &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;. Não reutilize o exemplo &lt;code&gt;429683C4C977415CAAFCCE10F7D57E11&lt;/code&gt; que vem no &lt;code&gt;.env.example&lt;/code&gt; da Evolution API.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ini"&gt;&lt;code&gt;&lt;span class="na"&gt;N8N_VERSION&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mf"&gt;2.48&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mi"&gt;6&lt;/span&gt;
&lt;span class="na"&gt;N8N_DOMAIN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;
&lt;span class="na"&gt;EVOLUTION_DOMAIN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;
&lt;span class="na"&gt;ACME_EMAIL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;voce&lt;/span&gt;@&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;
&lt;span class="na"&gt;GENERIC_TIMEZONE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nc"&gt;America&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="nc"&gt;Sao_Paulo&lt;/span&gt;

&lt;span class="na"&gt;N8N_ENCRYPTION_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;cole&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;chave&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;de&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;32&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;bytes&lt;/span&gt;
&lt;span class="na"&gt;N8N_RUNNERS_AUTH_TOKEN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;cole&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;de&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;32&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;bytes&lt;/span&gt;
&lt;span class="na"&gt;N8N_POSTGRES_USER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;
&lt;span class="na"&gt;N8N_POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;cole&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;senha&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;do&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;
&lt;span class="na"&gt;N8N_POSTGRES_DB&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;

&lt;span class="na"&gt;SERVER_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//api.example.com&lt;/span&gt;
&lt;span class="na"&gt;AUTHENTICATION_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;cole&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;chave&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;da&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;
&lt;span class="na"&gt;DATABASE_PROVIDER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;postgresql&lt;/span&gt;
&lt;span class="na"&gt;DATABASE_CONNECTION_URI&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;postgresql&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//evolution:cole-a-senha-da-api@evolution-postgres:5432/evolution_db?schema=evolution_api&lt;/span&gt;
&lt;span class="na"&gt;DATABASE_CONNECTION_CLIENT_NAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;
&lt;span class="na"&gt;CACHE_REDIS_ENABLED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="na"&gt;CACHE_REDIS_URI&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//evolution-redis:6379/6&lt;/span&gt;
&lt;span class="na"&gt;CACHE_REDIS_PREFIX_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;
&lt;span class="na"&gt;TELEMETRY_ENABLED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;
&lt;span class="na"&gt;LOG_LEVEL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="no"&gt;ERROR&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="no"&gt;WARN&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="no"&gt;INFO&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="no"&gt;LOG&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="no"&gt;WEBHOOKS&lt;/span&gt;
&lt;span class="na"&gt;LANGUAGE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;en&lt;/span&gt;

&lt;span class="na"&gt;POSTGRES_DATABASE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution_db&lt;/span&gt;
&lt;span class="na"&gt;POSTGRES_USERNAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;evolution&lt;/span&gt;
&lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;cole&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;senha&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;da&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;chmod 600 .env
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A senha dentro de &lt;code&gt;DATABASE_CONNECTION_URI&lt;/code&gt; e a de &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; são a mesma. Se ela tiver &lt;code&gt;@&lt;/code&gt;, &lt;code&gt;:&lt;/code&gt;, &lt;code&gt;/&lt;/code&gt; ou &lt;code&gt;#&lt;/code&gt;, troque esses caracteres pelo código percentual na URI. &lt;code&gt;N8N_VERSION&lt;/code&gt; fixa o n8n e o runner, que precisam da mesma versão. &lt;code&gt;2.48.6&lt;/code&gt; era a &lt;code&gt;stable&lt;/code&gt; em 19/11/2026 nas &lt;a href="https://github.com/n8n-io/n8n/releases" rel="noopener noreferrer"&gt;releases do n8n&lt;/a&gt;. A tag da Evolution API é a &lt;code&gt;v2.3.7&lt;/code&gt;, que é a versão do &lt;code&gt;package.json&lt;/code&gt; do repositório e a tag publicada no lugar de &lt;code&gt;latest&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;SERVER_URL&lt;/code&gt;, &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;, &lt;code&gt;DATABASE_PROVIDER&lt;/code&gt;, &lt;code&gt;DATABASE_CONNECTION_URI&lt;/code&gt;, &lt;code&gt;CACHE_REDIS_ENABLED&lt;/code&gt; e &lt;code&gt;CACHE_REDIS_URI&lt;/code&gt; estão no &lt;code&gt;.env.example&lt;/code&gt; atual. &lt;code&gt;TELEMETRY_ENABLED=false&lt;/code&gt; desliga o envio que o exemplo deixa ligado.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Guarde o .env fora da VPS.&lt;/strong&gt; O n8n não lê credencial restaurada sem &lt;code&gt;N8N_ENCRYPTION_KEY&lt;/code&gt;. A Evolution API não autentica chamada sem &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3&gt;
  
  
  Caddyfile
&lt;/h3&gt;

&lt;p&gt;O laboratório não tinha domínio público. O &lt;code&gt;local_certs&lt;/code&gt; faz o Caddy emitir um certificado da autoridade interna dele para os dois nomes. Foi esse arquivo que subiu:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;{
    email {$ACME_EMAIL}
    local_certs
}

{$N8N_DOMAIN} {
    reverse_proxy n8n:5678 {
        flush_interval -1
    }
}

{$EVOLUTION_DOMAIN} {
    reverse_proxy evolution-api:8080
}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O &lt;code&gt;flush_interval -1&lt;/code&gt; é o do exemplo de Caddy do n8n: desliga o buffer da resposta. O &lt;code&gt;reverse_proxy&lt;/code&gt; manda &lt;code&gt;X-Forwarded-For&lt;/code&gt;, &lt;code&gt;X-Forwarded-Proto&lt;/code&gt; e &lt;code&gt;X-Forwarded-Host&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Com um domínio público, apague a linha &lt;code&gt;local_certs&lt;/code&gt; e deixe o restante. O &lt;code&gt;caddy validate&lt;/code&gt; aceitou esse arquivo sem o &lt;code&gt;local_certs&lt;/code&gt;. O Caddy então pede o certificado público sozinho, desde que os dois nomes apontem para o IPv4 da VPS e as portas 80 e 443 estejam alcançáveis. O certificado interno deste teste vale poucas horas e o emissor é &lt;code&gt;Caddy Local Authority&lt;/code&gt;. Não use esse certificado no lugar do público.&lt;/p&gt;

&lt;h3&gt;
  
  
  Compose
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;caddy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;caddy:2.11.9&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;unless-stopped&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"80:80"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"443:443"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"443:443/udp"&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_DOMAIN=${N8N_DOMAIN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;EVOLUTION_DOMAIN=${EVOLUTION_DOMAIN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;ACME_EMAIL=${ACME_EMAIL}&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;./Caddyfile:/etc/caddy/Caddyfile:ro&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;caddy_data:/data&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;caddy_config:/config&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;n8n&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-api&lt;/span&gt;

  &lt;span class="na"&gt;n8n-postgres&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:18.7&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;POSTGRES_USER=${N8N_POSTGRES_USER}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;POSTGRES_PASSWORD=${N8N_POSTGRES_PASSWORD}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;POSTGRES_DB=${N8N_POSTGRES_DB}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;PGDATA=/var/lib/postgresql/data&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;n8n_db:/var/lib/postgresql/data&lt;/span&gt;
    &lt;span class="na"&gt;healthcheck&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;test&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"CMD-SHELL"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"pg_isready -h localhost -U ${N8N_POSTGRES_USER} -d ${N8N_POSTGRES_DB}"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
      &lt;span class="na"&gt;interval&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;retries&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;

  &lt;span class="na"&gt;n8n&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;docker.n8n.io/n8nio/n8n:${N8N_VERSION}&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_HOST=${N8N_DOMAIN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_PORT=5678&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_PROTOCOL=https&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_WEBHOOK_URL=https://${N8N_DOMAIN}/&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_PROXY_HOPS=1&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;GENERIC_TIMEZONE=${GENERIC_TIMEZONE}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;TZ=${GENERIC_TIMEZONE}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_TYPE=postgresdb&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_POSTGRESDB_HOST=n8n-postgres&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_POSTGRESDB_PORT=5432&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_POSTGRESDB_DATABASE=${N8N_POSTGRES_DB}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_POSTGRESDB_USER=${N8N_POSTGRES_USER}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;DB_POSTGRESDB_PASSWORD=${N8N_POSTGRES_PASSWORD}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_RUNNERS_MODE=external&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_RUNNERS_AUTH_TOKEN=${N8N_RUNNERS_AUTH_TOKEN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;n8n_data:/home/node/.n8n&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;n8n-postgres&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_healthy&lt;/span&gt;

  &lt;span class="na"&gt;n8n-runner&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;n8nio/runners:${N8N_VERSION}&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_RUNNERS_AUTH_TOKEN=${N8N_RUNNERS_AUTH_TOKEN}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;N8N_RUNNERS_TASK_BROKER_URI=http://n8n:5679&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;n8n&lt;/span&gt;

  &lt;span class="na"&gt;evolution-api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;evoapicloud/evolution-api:v2.3.7&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;env_file&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;.env&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution_instances:/evolution/instances&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-redis&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-postgres&lt;/span&gt;

  &lt;span class="na"&gt;evolution-redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;redis:7.4.12&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;redis-server --port 6379 --appendonly yes&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution_redis:/data&lt;/span&gt;
    &lt;span class="na"&gt;networks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;default&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;aliases&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution-redis&lt;/span&gt;

  &lt;span class="na"&gt;evolution-postgres&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:15.20&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_DATABASE}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_USER&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_USERNAME}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_PASSWORD}&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"postgres"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-c"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"max_connections=1000"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;evolution_postgres:/var/lib/postgresql/data&lt;/span&gt;

&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;caddy_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;caddy_config&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;n8n_db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;n8n_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution_instances&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution_redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;evolution_postgres&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O que esse arquivo faz, e o que o teste viu:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;N8N_WEBHOOK_URL&lt;/code&gt; é a URL base do webhook desde o n8n 2.30.0. Sem ela, o editor monta &lt;code&gt;http://localhost:5678/&lt;/code&gt;. &lt;code&gt;N8N_PROXY_HOPS=1&lt;/code&gt; faz o n8n confiar no único proxy da frente. O guia &lt;a href="https://nuvits.net/blog/webhook-n8n-localhost-5678" rel="noopener noreferrer"&gt;O webhook do n8n mostra localhost:5678&lt;/a&gt; mede as duas variáveis.&lt;/li&gt;
&lt;li&gt;O runner externo é o modo que a documentação do n8n recomenda em produção. A imagem &lt;code&gt;n8nio/runners:2.48.6&lt;/code&gt; usa a mesma versão do n8n.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;PGDATA=/var/lib/postgresql/data&lt;/code&gt; no Postgres 18.7 mantém o banco dentro do volume. Não apague essa linha.&lt;/li&gt;
&lt;li&gt;A Evolution API usa o &lt;code&gt;docker-compose.yaml&lt;/code&gt; oficial como base e larga a rede &lt;code&gt;dokploy-network&lt;/code&gt;, que não existe numa VPS nova. A imagem deixa de ser &lt;code&gt;latest&lt;/code&gt; e passa a ser &lt;code&gt;v2.3.7&lt;/code&gt;. O Postgres fica em &lt;code&gt;15.20&lt;/code&gt; e o Redis em &lt;code&gt;7.4.12&lt;/code&gt;, no lugar das tags flutuantes do arquivo oficial.&lt;/li&gt;
&lt;li&gt;O &lt;code&gt;env_file&lt;/code&gt; entrega o &lt;code&gt;.env&lt;/code&gt; inteiro para a API. Ela ignora as chaves do n8n. As senhas dos dois Postgres têm nomes diferentes de propósito: um único &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; no mesmo arquivo seria lido pelos dois serviços.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Subir
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/whatsapp
sudo docker compose up -d
sudo docker compose ps
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O n8n espera o Postgres ficar saudável. A Evolution API aplica as migrações do Prisma na subida e só então escuta. Acompanhe até as duas linhas:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose logs n8n
sudo docker compose logs evolution-api
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;No n8n, o fim útil é &lt;code&gt;Editor is now accessible via:&lt;/code&gt; seguido de &lt;code&gt;https://n8n.example.com&lt;/code&gt;. Na API, &lt;code&gt;HTTP - ON: 8080&lt;/code&gt; e a versão &lt;code&gt;v2.3.7&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;O certificado interno fica em &lt;code&gt;caddy/pki/authorities/local/root.crt&lt;/code&gt; no volume do Caddy. Para o &lt;code&gt;curl&lt;/code&gt; deste laboratório confiar nele:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt
curl --cacert ./caddy-root.crt -fsS https://n8n.example.com/healthz
curl --cacert ./caddy-root.crt -fsS https://api.example.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O primeiro responde &lt;code&gt;{"status":"ok"}&lt;/code&gt;. O segundo responde JSON com &lt;code&gt;"version":"2.3.7"&lt;/code&gt; e &lt;code&gt;"message":"Welcome to the Evolution API, it is working!"&lt;/code&gt;. Com certificado público, apague o &lt;code&gt;--cacert ./caddy-root.crt&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;No laboratório os nomes &lt;code&gt;n8n.example.com&lt;/code&gt; e &lt;code&gt;api.example.com&lt;/code&gt; apontavam para &lt;code&gt;127.0.0.1&lt;/code&gt; no &lt;code&gt;/etc/hosts&lt;/code&gt; da própria máquina. Na sua VPS, com domínio público, eles apontam para o IPv4 no DNS.&lt;/p&gt;

&lt;h2&gt;
  
  
  A instância e o webhook
&lt;/h2&gt;

&lt;p&gt;A Evolution API v2.3.7 cria a instância em &lt;code&gt;POST /instance/create&lt;/code&gt;. O corpo pede &lt;code&gt;instanceName&lt;/code&gt; e &lt;code&gt;integration&lt;/code&gt;. &lt;code&gt;WHATSAPP-BAILEYS&lt;/code&gt; é a conexão pelo WhatsApp Web. A documentação da API avisa que ela pode ter limitações em relação à API oficial da Meta.&lt;/p&gt;

&lt;p&gt;Carregue a chave e crie a instância &lt;code&gt;atendimento&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;set&lt;/span&gt; -a &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; . ./.env &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;set&lt;/span&gt; +a
curl --cacert ./caddy-root.crt -fsS -X POST https://api.example.com/instance/create \
  -H &lt;span class="s2"&gt;"apikey: $AUTHENTICATION_API_KEY"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"instanceName":"atendimento","integration":"WHATSAPP-BAILEYS","qrcode":false}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A resposta é 201. Guarde o &lt;code&gt;instanceId&lt;/code&gt;. O &lt;code&gt;hash&lt;/code&gt; é um token da instância: não cole em chat nem em repositório.&lt;/p&gt;

&lt;p&gt;O webhook da versão 2.3.7 não é a lista solta de campos. O corpo tem um objeto &lt;code&gt;webhook&lt;/code&gt;, como o schema do repositório exige (&lt;code&gt;enabled&lt;/code&gt; e &lt;code&gt;url&lt;/code&gt; obrigatórios):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -fsS -X POST https://api.example.com/webhook/set/atendimento \
  -H &lt;span class="s2"&gt;"apikey: $AUTHENTICATION_API_KEY"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"webhook":{"enabled":true,"url":"http://n8n:5678/webhook/whatsapp","byEvents":false,"base64":false,"events":["MESSAGES_UPSERT","QRCODE_UPDATED","CONNECTION_UPDATE"]}}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A resposta é 201 e devolve a mesma URL. Confira com:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -fsS https://api.example.com/webhook/find/atendimento \
  -H &lt;span class="s2"&gt;"apikey: $AUTHENTICATION_API_KEY"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;MESSAGES_UPSERT&lt;/code&gt; é o evento de mensagem nova. &lt;code&gt;QRCODE_UPDATED&lt;/code&gt; e &lt;code&gt;CONNECTION_UPDATE&lt;/code&gt; servem para ver a conexão antes de existir mensagem. &lt;code&gt;byEvents: false&lt;/code&gt; manda tudo para a mesma URL. Com &lt;code&gt;true&lt;/code&gt;, a API acrescenta o nome do evento no caminho e o n8n deixa de achar o webhook.&lt;/p&gt;

&lt;p&gt;O QR, para escanear no celular em Aparelhos conectados:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -fsS https://api.example.com/instance/connect/atendimento \
  -H &lt;span class="s2"&gt;"apikey: $AUTHENTICATION_API_KEY"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A resposta traz &lt;code&gt;base64&lt;/code&gt; (a imagem do QR) e &lt;code&gt;count&lt;/code&gt;. Neste teste o &lt;code&gt;count&lt;/code&gt; chegou a 1 e o log da API registrou &lt;code&gt;qrcode.updated&lt;/code&gt; e &lt;code&gt;connection.update&lt;/code&gt; com &lt;code&gt;state: connecting&lt;/code&gt;, os dois com destino &lt;code&gt;http://n8n:5678/webhook/whatsapp&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  O workflow no n8n
&lt;/h2&gt;

&lt;p&gt;Abra &lt;code&gt;https://n8n.example.com&lt;/code&gt;, crie a conta de owner e um workflow com dois nós.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Nó Webhook, método POST, caminho &lt;code&gt;whatsapp&lt;/code&gt;, resposta imediata. Publique o workflow. A URL de produção fica &lt;code&gt;https://n8n.example.com/webhook/whatsapp&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Nó HTTP Request, método POST, URL &lt;code&gt;http://evolution-api:8080/message/sendText/atendimento&lt;/code&gt;. Cabeçalho &lt;code&gt;apikey&lt;/code&gt; com o valor de &lt;code&gt;AUTHENTICATION_API_KEY&lt;/code&gt;. Corpo JSON com &lt;code&gt;number&lt;/code&gt; (DDI e DDD, só dígitos) e &lt;code&gt;text&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Ligue a saída do Webhook na entrada do HTTP Request. Publique de novo. No teste, o painel mostrou esta URL de produção, com Authentication em None:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fdggavduc0nta9istb32x.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fdggavduc0nta9istb32x.webp" alt="URL de produção do webhook do n8n em https://n8n.example.com/webhook/whatsapp, no workflow que chama a Evolution API" width="800" height="611"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;O workflow publicado num nome público aceita POST de qualquer um. A Evolution API desta stack chama &lt;code&gt;http://n8n:5678&lt;/code&gt; por dentro e não precisa dessa URL pública para entregar o evento. No teste, &lt;code&gt;qrcode.updated&lt;/code&gt; e &lt;code&gt;connection.update&lt;/code&gt; também executaram o nó HTTP Request e receberam o mesmo 500. Esses eventos não são mensagem: o &lt;code&gt;sendText&lt;/code&gt; só faz sentido quando o evento é &lt;code&gt;MESSAGES_UPSERT&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;O webhook de produção só existe com o workflow publicado. Antes disso, &lt;code&gt;POST /webhook/whatsapp&lt;/code&gt; responde 404 e o corpo diz que o workflow precisa estar ativo.&lt;/p&gt;

&lt;p&gt;Um POST de fora, pelo Caddy, confirma o caminho público. Com o workflow publicado:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -fsS -X POST https://n8n.example.com/webhook/whatsapp \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"event":"messages.upsert","data":{"message":{"conversation":"oi do teste"}}}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A resposta é &lt;code&gt;{"message":"Workflow was started"}&lt;/code&gt;. Na execução, o n8n grava &lt;code&gt;webhookUrl&lt;/code&gt; como &lt;code&gt;https://n8n.example.com/webhook/whatsapp&lt;/code&gt; e &lt;code&gt;x-forwarded-proto&lt;/code&gt; como &lt;code&gt;https&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;A Evolution API, do contêiner dela, usa a URL interna. No teste, cada &lt;code&gt;qrcode.updated&lt;/code&gt; virou uma execução com status success no n8n. É o mesmo webhook. Não é um segundo workflow.&lt;/p&gt;

&lt;h2&gt;
  
  
  Antes de escanear o QR
&lt;/h2&gt;

&lt;p&gt;Sem o celular pareado, o envio não sai. O comando, nos dois momentos, foi este:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl --cacert ./caddy-root.crt -sS -o /tmp/send-text.json -w &lt;span class="s1"&gt;'%{http_code}\n'&lt;/span&gt; \
  -X POST https://api.example.com/message/sendText/atendimento \
  -H &lt;span class="s2"&gt;"apikey: $AUTHENTICATION_API_KEY"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"number":"5511999999999","text":"teste de envio antes do pareamento"}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O código foi 500 nas duas vezes. Logo depois do create, antes do &lt;code&gt;connect&lt;/code&gt;, a mensagem interna era &lt;code&gt;Cannot read properties of undefined (reading 'onWhatsApp')&lt;/code&gt;. Depois do &lt;code&gt;connect&lt;/code&gt;, com a instância em &lt;code&gt;connecting&lt;/code&gt;, o corpo foi:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;500&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"error"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Internal Server Error"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"response"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"message"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Cannot read properties of undefined (reading 'find')"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;O mesmo 500 apareceu na execução do n8n quando o nó HTTP Request chamou &lt;code&gt;http://evolution-api:8080/message/sendText/atendimento&lt;/code&gt;. O workflow foi marcado como sucesso porque o nó estava com continuar em caso de erro. O item da execução guardou o texto &lt;code&gt;500 - "{\"status\":500,...}"&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Isso não é uma mensagem entregue no WhatsApp. É a API respondendo antes de existir sessão. Depois que o QR for aceito no celular, o mesmo &lt;code&gt;POST&lt;/code&gt; é o envio. Este laboratório parou antes desse aceite: não houve telefone, então não houve mensagem saindo para um número real.&lt;/p&gt;

&lt;p&gt;O corpo do &lt;code&gt;sendText&lt;/code&gt; na v2.3.7 é o da classe &lt;code&gt;SendTextDto&lt;/code&gt; do repositório: &lt;code&gt;number&lt;/code&gt; e &lt;code&gt;text&lt;/code&gt;. O cabeçalho é &lt;code&gt;apikey&lt;/code&gt;, não &lt;code&gt;Authorization&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  O que sobrevive a um recomeço
&lt;/h2&gt;

&lt;p&gt;Com a instância e o webhook gravados, reinicie só a API:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose restart evolution-api
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Espere &lt;code&gt;HTTP - ON: 8080&lt;/code&gt; de novo e repita o &lt;code&gt;GET /instance/fetchInstances&lt;/code&gt; e o &lt;code&gt;GET /webhook/find/atendimento&lt;/code&gt;. No teste, &lt;code&gt;atendimento&lt;/code&gt; continuou na lista e a URL do webhook continuou &lt;code&gt;http://n8n:5678/webhook/whatsapp&lt;/code&gt;. A sessão do WhatsApp, quando existir, fica no volume &lt;code&gt;evolution_instances&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Recrie o n8n sem apagar o volume:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo docker compose up -d --force-recreate n8n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;No teste, o login do owner voltou a responder 200 e &lt;code&gt;urlBaseWebhook&lt;/code&gt; continuou &lt;code&gt;https://n8n.example.com/&lt;/code&gt;. A conta fica no Postgres 18.7 e a chave, no volume &lt;code&gt;n8n_data&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;O backup que este teste gravou:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/whatsapp
&lt;span class="nb"&gt;set&lt;/span&gt; -a &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; . ./.env &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;set&lt;/span&gt; +a
sudo docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T n8n-postgres pg_dumpall -U &lt;span class="s2"&gt;"$N8N_POSTGRES_USER"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; n8n-db-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql
grep -c &lt;span class="s2"&gt;"PostgreSQL database cluster dump complete"&lt;/span&gt; n8n-db-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql
sudo docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T evolution-postgres pg_dump -U &lt;span class="s2"&gt;"$POSTGRES_USERNAME"&lt;/span&gt; &lt;span class="s2"&gt;"$POSTGRES_DATABASE"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; evolution-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql
grep -c &lt;span class="s2"&gt;"PostgreSQL database dump complete"&lt;/span&gt; evolution-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql
sudo docker run --rm --volumes-from &lt;span class="s2"&gt;"$(sudo docker compose ps -q n8n)"&lt;/span&gt; -v &lt;span class="s2"&gt;"$PWD"&lt;/span&gt;:/backup ubuntu:24.04 tar czf /backup/n8n-data-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.tar.gz /home/node/.n8n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Os dois &lt;code&gt;grep&lt;/code&gt; imprimiram &lt;code&gt;1&lt;/code&gt;. Copie os &lt;code&gt;.sql&lt;/code&gt;, o &lt;code&gt;.tar.gz&lt;/code&gt; e o &lt;code&gt;.env&lt;/code&gt; para outra máquina. Uma cópia que fica só neste disco se perde com a VPS. O guia do n8n detalha a restauração.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Nunca rode &lt;code&gt;docker compose down -v&lt;/code&gt; nesta pasta.&lt;/strong&gt; O &lt;code&gt;-v&lt;/code&gt; apaga os volumes: o banco do n8n, a chave, o banco da Evolution API e as sessões do WhatsApp.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Atualizar
&lt;/h2&gt;

&lt;p&gt;As tags deste guia não flutuam. Atualizar é trocar o número no &lt;code&gt;.env&lt;/code&gt; ou no Compose, ler a nota da versão e recriar.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/whatsapp
sudo docker compose pull
sudo docker compose up -d
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;No teste, o &lt;code&gt;pull&lt;/code&gt; das sete imagens pinadas respondeu que já estavam baixadas, e o &lt;code&gt;up -d&lt;/code&gt; manteve os contêineres. Trocar &lt;code&gt;N8N_VERSION&lt;/code&gt; puxa o n8n e o runner juntos. O n8n aplica migração ao iniciar, e voltar a tag não desfaz a migração: o dump vem antes. A Evolution API &lt;code&gt;v2.3.7&lt;/code&gt; não avisa sozinha quando um salto de versão exige passo manual no banco. Leia a nota no repositório antes de mudar a tag.&lt;/p&gt;

&lt;p&gt;Subir o Postgres de 18.7 para outra versão principal, ou o 15.20 da API, é dump e restauração, não troca de tag.&lt;/p&gt;

&lt;h2&gt;
  
  
  Próximo passo
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;O webhook que ainda mostra &lt;code&gt;localhost:5678&lt;/code&gt; está em &lt;a href="https://nuvits.net/blog/webhook-n8n-localhost-5678" rel="noopener noreferrer"&gt;O webhook do n8n mostra localhost:5678&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;A VPS de um serviço só está em &lt;a href="https://nuvits.net/vps-para-n8n" rel="noopener noreferrer"&gt;VPS para n8n&lt;/a&gt; e &lt;a href="https://nuvits.net/vps-para-evolution-api" rel="noopener noreferrer"&gt;VPS para Evolution API&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Se o Docker ainda vai ser instalado, o caminho é &lt;a href="https://nuvits.net/vps-docker" rel="noopener noreferrer"&gt;VPS com Docker&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;Publicado originalmente em &lt;a href="https://nuvits.net/blog/n8n-evolution-api-mesma-vps" rel="noopener noreferrer"&gt;https://nuvits.net/blog/n8n-evolution-api-mesma-vps&lt;/a&gt;&lt;/p&gt;

</description>
      <category>braziliandevs</category>
      <category>portugues</category>
      <category>n8n</category>
      <category>whatsapp</category>
    </item>
  </channel>
</rss>
