Ir para o conteúdo

Tutorial

Como instalar o Supabase self-hosted numa VPS Ubuntu

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
  1. O que você vai precisar
  2. Como a stack e o proxy se organizam
  3. Baixar a pasta docker do Supabase
  4. Gerar chaves e segredos com os scripts oficiais
  5. Configurar domínio, Auth e SMTP no `.env`
  6. Ativar o Caddy e fechar as portas do banco no host
  7. Subir a stack e conferir saúde e portas
  8. Validar HTTPS, Studio, API e acesso ao PostgreSQL
  9. Backup e atualização sem surpresa
  10. Erros comuns na primeira subida
  11. 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, openssl e acesso SSH com sudo.
  • Um domínio ou subdomínio apontando em registro A para 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 para api-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 por basic_auth gerado automaticamente pelo Caddy a partir do .env.

Arquitetura do Supabase self-hosted numa VPS Ubuntu com Caddy nas portas 80 e 443, Envoy para APIs, Basic Auth no Studio e Supavisor restrito ao localhost

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:

bash
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 .env

A 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):

bash
sh utils/generate-keys.sh --update-env

2. 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:

bash
sh utils/add-new-auth-keys.sh --update-env

Esse 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:

.env
# 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 App

Confira dois detalhes antes de salvar:

  • Deixe ENABLE_EMAIL_AUTOCONFIRM=false em 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 com ENABLE_EMAIL_AUTOCONFIRM=true e voltar para false antes de abrir para usuários reais.
  • POOLER_TENANT_ID não deve continuar como your-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:

bash
sh run.sh config add caddy

Esse 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:

docker-compose.local-db.yml
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:

bash
sh run.sh config add local-db
sh run.sh config
sudo docker compose config --quiet

A saída de sh run.sh config precisa listar exatamente os três arquivos nesta ordem:

text
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.yml

Se 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:

bash
sudo sh run.sh pull
sudo sh run.sh start

O 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:

bash
sudo sh run.sh status

Todos 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:

bash
sudo ss -tulpn | grep -E ':(80|443|5432|6543|8000)\b'

O resultado esperado é:

  • :80 e :443 em 0.0.0.0 (ou *:80 / *:443) pelo docker-proxy do Caddy.
  • 127.0.0.1:5432 e 127.0.0.1:6543 presos ao loopback pelo Supavisor.
  • Nenhuma porta 8000 nem 3000 publicada no host.

Se o firewall ufw ainda não estiver ativo na VPS, libere apenas SSH, HTTP e HTTPS:

bash
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw enable

Validar 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:

bash
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/:

bash
curl -fsS https://supabase.example.com/rest/v1/ \
  -H "apikey: SUA_SUPABASE_PUBLISHABLE_KEY" | head -c 300

Um 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:

bash
ssh -N -L 5432:127.0.0.1:5432 -L 6543:127.0.0.1:6543 usuario@IP_DA_VPS

Em outro terminal, conecte usando o formato de usuário exigido pelo Supavisor (postgres.<POOLER_TENANT_ID>):

bash
# 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:

  1. Dump lógico do PostgreSQL: preserva roles, schemas (public, auth, storage), políticas RLS e dados.
  2. Arquivos do Storage em ~/supabase/volumes/storage/ (ou no seu bucket S3, se usar docker-compose.s3.yml).
  3. O arquivo .env, criptografado fora da VPS.

Gere um dump completo comprimido com um comando único:

bash
mkdir -p ~/backups/supabase
sudo docker exec supabase-db pg_dumpall -U postgres | gzip > ~/backups/supabase/supabase-$(date +%F).sql.gz

Envie 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:

bash
cd ~/supabase
sudo sh run.sh pull
sudo sh run.sh start

Erros comuns na primeira subida

  • Studio abre em branco ou acusa erro de CORS / Mixed Content: SUPABASE_PUBLIC_URL ou API_EXTERNAL_URL ainda está com http://localhost:8000. Corrija ambos para https://supabase.example.com (com /auth/v1 em API_EXTERNAL_URL) e rode sudo sh run.sh recreate studio auth api-gw.
  • Erro Tenant or user not found no psql: ao conectar pelas portas do Supavisor (5432 ou 6543), o usuário precisa levar o sufixo do tenant (postgres.<POOLER_TENANT_ID>), não apenas postgres.
  • Caddy não emite o certificado TLS: confirme que o registro A de PROXY_DOMAIN já 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