Este guia sobe o Supabase self-hosted numa VPS Ubuntu 24.04 usando o Docker Compose oficial, com Envoy como API gateway, Caddy na frente cuidando do HTTPS automático e as portas do PostgreSQL restritas ao localhost. Só as portas 80 e 443 ficam abertas para a internet; o Studio exige autenticação HTTP Basic no proxy e o acesso direto ao banco passa por túnel SSH.
Neste artigo
- O que você vai precisar
- Como a stack e o proxy se organizam
- Baixar a pasta docker do Supabase
- Gerar chaves e segredos com os scripts oficiais
- Configurar domínio, Auth e SMTP no `.env`
- Ativar o Caddy e fechar as portas do banco no host
- Subir a stack e conferir saúde e portas
- Validar HTTPS, Studio, API e acesso ao PostgreSQL
- Backup e atualização sem surpresa
- Erros comuns na primeira subida
- Próximos passos
As versões e arquivos deste passo a passo acompanham o repositório oficial supabase/supabase, que usa PostgreSQL 17 (supabase/postgres:17.6.1.136), envoyproxy/envoy:v1.39.6 como gateway padrão, supabase/supavisor:2.9.13 para pool de conexões e o override nativo docker-compose.caddy.yml.
O que você vai precisar
- Uma VPS com Ubuntu 24.04 de 64 bits, Docker Engine com Compose plugin (
v2.20+),git,openssle acesso SSH comsudo. - Um domínio ou subdomínio apontando em registro
Apara o IPv4 público da VPS (nos exemplos abaixo,supabase.example.com). - Um servidor SMTP (como Resend, Postmark ou SES) para enviar e-mails de confirmação de conta e recuperação de senha pelo Auth.
A stack padrão sem os serviços opcionais de logs sobe 12 contêineres com o Caddy: PostgreSQL 17, Supavisor, Envoy (api-gw), Studio, GoTrue (Auth), PostgREST, Realtime, Storage, imgproxy, postgres-meta, Edge Functions e Caddy.
| Ambiente | vCPU | Memória RAM | Disco SSD | Observação |
|---|---|---|---|---|
| Testes e protótipos | 2 vCPU | 4 GB | 40 GB | Piso mínimo para subir a stack sem carga concorrente |
| Produção pequena e média | 4 vCPU | 8 GB | 100 GB | Recomendado para banco, Realtime, Storage e margem de cache |
| Vários projetos ou alta concorrência | 6–8 vCPU | 12–24 GB | 200+ GB | Folga para conexões simultâneas, pgvector e backups locais |
Se o Docker ainda não estiver instalado na VPS, use o repositório apt oficial descrito em Como instalar o n8n com Docker numa VPS.
Como a stack e o proxy se organizam
No Compose atual do Supabase, o Envoy substituiu o Kong como API gateway padrão (api-gw), mantendo os aliases internos envoy e kong na rede do Docker. Quando você ativa o override docker-compose.caddy.yml, o Caddy passa a ser o único ponto de entrada HTTP/HTTPS nas portas 80 e 443:
- Rotas de API (
/auth/v1/*,/rest/v1/*,/graphql/v1,/realtime/v1/*,/storage/v1/*,/functions/v1/*,/mcp,/sso/*) vão paraapi-gw:8000, onde o Envoy valida as chaves de API e faz o upgrade de WebSocket do Realtime. - Todas as demais rotas caem no Studio (
studio:3000), protegidas porbasic_authgerado automaticamente pelo Caddy a partir do.env.

Baixar a pasta docker do Supabase
Evite clonar o histórico inteiro do monorepo. Faça um clone raso e copie apenas o diretório docker para ~/supabase:
git clone --depth 1 --filter=blob:none --sparse https://github.com/supabase/supabase.git /tmp/supabase-repo
git -C /tmp/supabase-repo sparse-checkout set docker
cp -r /tmp/supabase-repo/docker ~/supabase
rm -rf /tmp/supabase-repo
cd ~/supabase
cp .env.example .env
chmod 600 .envA pasta ~/supabase traz o docker-compose.yml, os overrides oficiais (docker-compose.caddy.yml, docker-compose.s3.yml, docker-compose.logs.yml), o utilitário run.sh, a pasta volumes/ e os scripts de geração de chaves em utils/.
Gerar chaves e segredos com os scripts oficiais
Nunca suba o Supabase com os valores de exemplo do .env.example. O repositório oficial inclui dois scripts que criam segredos fortes e gravam tudo direto no .env.
1. Segredos da stack e chaves JWT legadas
Rode generate-keys.sh com --update-env. Ele gera senhas aleatórias para POSTGRES_PASSWORD e DASHBOARD_PASSWORD, o JWT_SECRET, os tokens assinados ANON_KEY e SERVICE_ROLE_KEY, além das chaves de criptografia exigidas pelo Realtime, Supavisor, postgres-meta e Storage (SECRET_KEY_BASE, REALTIME_DB_ENC_KEY, VAULT_ENC_KEY, PG_META_CRYPTO_KEY, S3_PROTOCOL_ACCESS_KEY_ID e S3_PROTOCOL_ACCESS_KEY_SECRET):
sh utils/generate-keys.sh --update-env2. Chaves assimétricas ES256 e chaves opacas
Em seguida, gere o par assimétrico EC P-256 (JWT_KEYS e JWT_JWKS) e as chaves opacas SUPABASE_PUBLISHABLE_KEY e SUPABASE_SECRET_KEY, usadas pelas versões atuais dos SDKs do Supabase:
sh utils/add-new-auth-keys.sh --update-envEsse script usa Node.js >= 16 se estiver instalado na máquina, ou cai automaticamente para um contêiner temporário do Docker.
Configurar domínio, Auth e SMTP no .env
Abra o .env e substitua os campos de URL, tenant do pooler, usuário do Studio e SMTP. Troque supabase.example.com pelo seu domínio real e app.example.com pela URL do seu frontend:
# Domínio público e URLs do Auth
PROXY_DOMAIN=supabase.example.com
SUPABASE_PUBLIC_URL=https://supabase.example.com
API_EXTERNAL_URL=https://supabase.example.com/auth/v1
SITE_URL=https://app.example.com
ADDITIONAL_REDIRECT_URLS=https://app.example.com/**
# Identificador único do tenant no Supavisor (usado no usuário do Postgres)
POOLER_TENANT_ID=nuvits-prod-01
# Usuário do Basic Auth do Studio (a senha já foi gerada pelo generate-keys.sh)
DASHBOARD_USERNAME=admin-supabase
# SMTP real para confirmação de cadastro e redefinição de senha
[email protected]
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=usuario-smtp
SMTP_PASS=senha-smtp
SMTP_SENDER_NAME=Minha AppConfira dois detalhes antes de salvar:
- Deixe
ENABLE_EMAIL_AUTOCONFIRM=falseem produção para exigir confirmação de e-mail no cadastro. Se ainda não tiver SMTP pronto apenas para um teste inicial, você pode temporariamente testar comENABLE_EMAIL_AUTOCONFIRM=truee voltar parafalseantes de abrir para usuários reais. POOLER_TENANT_IDnão deve continuar comoyour-tenant-id. Use um identificador simples com letras minúsculas, números e hífen.
Ativar o Caddy e fechar as portas do banco no host
Primeiro, adicione o override oficial do Caddy à variável COMPOSE_FILE do .env usando o próprio run.sh do Supabase:
sh run.sh config add caddyEsse comando atualiza COMPOSE_FILE para docker-compose.yml:docker-compose.caddy.yml. O arquivo docker-compose.caddy.yml usa ports: !reset [] para retirar a porta 8000 do api-gw e sobe o contêiner supabase-caddy nas portas 80, 443 e 443/udp, lendo volumes/proxy/caddy/Caddyfile.
Agora crie um segundo override na mesma pasta para impedir que o supavisor exponha as portas 5432 e 6543 na interface pública da VPS:
services:
supavisor:
ports: !reset
- "127.0.0.1:${POSTGRES_PORT}:5432"
- "127.0.0.1:${POOLER_PROXY_PORT_TRANSACTION}:6543"Ative o override com o run.sh e valide o Compose final mesclado:
sh run.sh config add local-db
sh run.sh config
sudo docker compose config --quietA saída de sh run.sh config precisa listar exatamente os três arquivos nesta ordem:
COMPOSE_FILE=docker-compose.yml:docker-compose.caddy.yml:docker-compose.local-db.yml
compose files:
docker-compose.yml
docker-compose.caddy.yml
docker-compose.local-db.ymlSe docker compose config --quiet terminar sem mensagens e com código 0, a sintaxe YAML e o !reset estão válidos.
Subir a stack e conferir saúde e portas
Baixe as imagens e inicie todos os serviços aguardando os healthchecks:
sudo sh run.sh pull
sudo sh run.sh startO run.sh start executa docker compose up -d --wait. Na primeira subida, o PostgreSQL inicializa os schemas internos (auth, storage, realtime, _supabase) e o Caddy solicita o certificado TLS na Let's Encrypt — isso leva de um a dois minutos.
Confira o estado dos contêineres:
sudo sh run.sh statusTodos os serviços devem aparecer como Up (healthy) (ou Up no caso do Caddy e do Edge Runtime). Em seguida, confirme quais portas estão escutando no host:
sudo ss -tulpn | grep -E ':(80|443|5432|6543|8000)\b'O resultado esperado é:
:80e:443em0.0.0.0(ou*:80/*:443) pelodocker-proxydo Caddy.127.0.0.1:5432e127.0.0.1:6543presos ao loopback pelo Supavisor.- Nenhuma porta
8000nem3000publicada no host.
Se o firewall ufw ainda não estiver ativo na VPS, libere apenas SSH, HTTP e HTTPS:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw enableValidar HTTPS, Studio, API e acesso ao PostgreSQL
1. Conferir que o Studio exige autenticação
Do seu computador local (fora da VPS), peça a raiz do domínio sem credenciais:
curl -I https://supabase.example.com/O Caddy deve devolver HTTP/2 401 com www-authenticate: Basic. Ao abrir https://supabase.example.com no navegador, informe o DASHBOARD_USERNAME e a DASHBOARD_PASSWORD salvos no .env (você pode lê-los na VPS com sh run.sh secrets).
2. Conferir a API REST pelo Envoy
Carregue sua SUPABASE_PUBLISHABLE_KEY (ou ANON_KEY) e teste o endpoint /rest/v1/:
curl -fsS https://supabase.example.com/rest/v1/ \
-H "apikey: SUA_SUPABASE_PUBLISHABLE_KEY" | head -c 300Um documento OpenAPI em JSON confirma que TLS, Caddy, Envoy e PostgREST estão respondendo na cadeia completa.
3. Conectar ao PostgreSQL com segurança via túnel SSH
Como prendemos o Supavisor a 127.0.0.1, ferramentas como psql, DBeaver, Drizzle ou Prisma rodam a partir da sua máquina usando túnel SSH:
ssh -N -L 5432:127.0.0.1:5432 -L 6543:127.0.0.1:6543 usuario@IP_DA_VPSEm outro terminal, conecte usando o formato de usuário exigido pelo Supavisor (postgres.<POOLER_TENANT_ID>):
# Modo sessão (porta 5432 — recomendado para migrations e psql)
psql "postgresql://postgres.nuvits-prod-01:[email protected]:5432/postgres"
# Modo transação (porta 6543 — recomendado para apps serverless ou com muitas conexões)
psql "postgresql://postgres.nuvits-prod-01:[email protected]:6543/postgres"Para aplicações que rodam no mesmo Docker da VPS (como um backend ou um fluxo do n8n), conecte pela rede interna do Docker em db:5432 ou supavisor:6543, sem precisar abrir portas externas.
Backup e atualização sem surpresa
Um backup completo do Supabase self-hosted precisa guardar três peças:
- Dump lógico do PostgreSQL: preserva roles, schemas (
public,auth,storage), políticas RLS e dados. - Arquivos do Storage em
~/supabase/volumes/storage/(ou no seu bucket S3, se usardocker-compose.s3.yml). - O arquivo
.env, criptografado fora da VPS.
Gere um dump completo comprimido com um comando único:
mkdir -p ~/backups/supabase
sudo docker exec supabase-db pg_dumpall -U postgres | gzip > ~/backups/supabase/supabase-$(date +%F).sql.gzEnvie esse .sql.gz e a pasta volumes/storage/ diariamente para um storage externo (por exemplo, via rclone, no mesmo molde descrito em Backup automático do n8n fora da VPS).
Quando precisar atualizar a stack, faça backup antes, traga os arquivos novos do diretório docker/ de supabase/supabase preservando o .env e o docker-compose.local-db.yml, baixe as imagens novas e recrie os contêineres:
cd ~/supabase
sudo sh run.sh pull
sudo sh run.sh startErros comuns na primeira subida
- Studio abre em branco ou acusa erro de CORS / Mixed Content:
SUPABASE_PUBLIC_URLouAPI_EXTERNAL_URLainda está comhttp://localhost:8000. Corrija ambos parahttps://supabase.example.com(com/auth/v1emAPI_EXTERNAL_URL) e rodesudo sh run.sh recreate studio auth api-gw. - Erro
Tenant or user not foundnopsql: ao conectar pelas portas do Supavisor (5432ou6543), o usuário precisa levar o sufixo do tenant (postgres.<POOLER_TENANT_ID>), não apenaspostgres. - Caddy não emite o certificado TLS: confirme que o registro
AdePROXY_DOMAINjá resolve para o IPv4 da VPS (dig +short supabase.example.com) e que as portas 80 e 443 estão liberadas no firewall. - Realtime desconecta em segundos: se você colocou outro proxy na frente do Caddy (ou ativou proxy laranja com timeouts curtos), verifique se o suporte a WebSockets está ligado e evite camada dupla de TLS sem necessidade.
Próximos passos
- Para entender por que o override
docker-compose.local-db.ymlé indispensável em qualquer VPS com Docker eufw, leia A porta do Docker continua aberta com o ufw. - Se quiser conectar automações ao seu banco Supabase ou webhooks do Auth, veja Como instalar o n8n com Docker numa VPS.
- Se ainda estiver escolhendo o servidor para hospedar a stack, compare os planos em VPS com Docker e VPS Linux.