Supabase Self-Hosted — Guia do usuário

Guia do produto Supabase Self-Hosted do marketplace: o que é, para que serve, em que difere do Supabase Cloud e como acessar e operar o que é instalado.

1. O que é

O Supabase é uma alternativa open-source ao Firebase. Ele entrega, num único pacote, o backend completo de uma aplicação em cima de um banco PostgreSQL:

Componente	Para que serve
PostgreSQL	Banco de dados relacional, com acesso direto por string de conexão
API REST e GraphQL	API gerada automaticamente a partir das tabelas (PostgREST)
Auth	Cadastro, login (e-mail/senha, magic link, OAuth), sessões e JWT
Storage	Upload e entrega de arquivos, com regras de acesso
Realtime	Eventos em tempo real (mudanças no banco, broadcast, presença)
Edge Functions	Funções serverless em Deno/TypeScript
Studio	Painel web para administrar tudo isso

Este produto instala a versão self-hosted oficial (self-hosted/v0.8.2), seguindo a documentação do Supabase, num nó Docker do seu ambiente, com HTTPS (certificado Let's Encrypt) pelo proxy Caddy.

2. Para que serve

Ter o backend de um app (web ou mobile) — banco, login, arquivos e API — sem escrever um servidor do zero.
Manter os dados na sua infraestrutura, na região do seu ambiente (útil para LGPD e políticas internas).
Ter custo previsível, pelos recursos do ambiente, sem cobrança por usuário ativo, requisição ou armazenamento do Supabase.
Ambientes de desenvolvimento, homologação ou produção que você controla por completo.

3. Self-hosted × Supabase Cloud: o que muda

Só as diferenças que afetam o uso no dia a dia:

Tema	Supabase Cloud (hosted)	Este produto (self-hosted)
Projetos	Vários projetos por organização	Um projeto por ambiente (para outro projeto, instale outro ambiente)
Atualizações	Feitas pelo Supabase	Versão fixa (`v0.8.2`); atualizar é manual
Config. de Auth (SMTP, provedores OAuth, URLs de redirect)	Pelo painel	Pelo arquivo `.env` + reinício (ver seção 8.2)
E-mails de Auth	SMTP embutido (com limites)	Sem SMTP real: configure o seu antes de liberar cadastro por e-mail
Painel (Studio)	Completo: organizações, billing, branching	Reduzido: um projeto, sem billing/branching
Edge Functions	Deploy pela CLI (`supabase functions deploy`)	Código em `/home/supabase/volumes/functions` no servidor
Escala e recursos	Gerenciados pelo Supabase	Recursos do nó ajustáveis por você

Resumo: você ganha controle, dados no seu servidor e custo fixo; em troca, backups, atualizações, e-mail e monitoramento passam a ser seus.

4. Instalação

4.1 Opções

Opção	Padrão	O que faz
Habilitar MCP	Desmarcada	Expõe o servidor MCP do Supabase em `https://<domínio>/mcp`, protegido por token (ver seções 6.3 e 7). Pode ser habilitado ou desabilitado depois, pelo add-on MCP.

4.2 O que é criado

Um nó Docker Engine com IP público, portas 80/443, até 32 cloudlets (mínimo reservado de 8) e 30 GB de disco. Tudo do Supabase fica em /home/supabase (volume persistente).

Durante a instalação, automaticamente:

São gerados a senha do painel, a senha do PostgreSQL, as chaves JWT/API e, se marcado, o token do MCP.
Os arquivos oficiais do Supabase são baixados e o .env é configurado com o domínio do ambiente.
As imagens Docker são baixadas e os serviços iniciados enquanto o add-on Let's Encrypt Free SSL emite o certificado (em paralelo, para instalar mais rápido).
O Caddy sobe com o certificado e o HTTPS é testado.
São instalados os add-ons Senha do painel Supabase, Custom Domain e MCP.

Ao final, a tela de sucesso (também enviada por e-mail) traz todos os acessos. Guarde esse e-mail — ele é o único lugar com todas as senhas e chaves juntas.

5. Acessos

Nos exemplos, <domínio> é o domínio do ambiente (ex.: env-1234567.sp1.br.saveincloud.net.br) ou o seu domínio próprio, se configurado.

5.1 Studio (painel)

Acesso	Valor
URL	`https://<domínio>`
Usuário	`supabase`
Senha	a do e-mail de instalação (troque pelo add-on Senha do painel Supabase)

O Studio é o painel de administração: tabelas, SQL Editor, usuários do Auth, buckets do Storage, políticas (RLS) e chaves.

5.2 API (para os apps)

A URL do projeto é https://<domínio> — a mesma que vai no SDK:

import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://<domínio>', '<publishable key>')

Chave	Onde usar
Publishable key (`sb_publishable_…`)	Frontend e apps mobile. É pública; o acesso é limitado pelas políticas RLS.
Secret key (`sb_secret_…`)	Só no backend. Ignora o RLS: nunca coloque em código de navegador/app.
Anon key (legado)	Equivalente à publishable, para bibliotecas antigas.
Service role key (legado)	Equivalente à secret, para bibliotecas antigas. Só no backend.

Endpoints disponíveis: /rest/v1, /graphql/v1, /auth/v1, /storage/v1, /realtime/v1 e /functions/v1.

5.3 PostgreSQL (conexão direta)

A conexão passa pelo pooler (Supavisor). O usuário leva o nome do ambiente:

postgresql://postgres.<nome-do-ambiente>:<senha-do-postgres>@<domínio>:5432/postgres

Porta	Modo	Quando usar
5432	Session	Ferramentas (DBeaver, pgAdmin, `psql`), migrações, apps com conexão longa
6543	Transaction	Serverless e muitas conexões curtas

Se a conexão de fora não abrir, verifique se o firewall do ambiente libera as portas 5432/6543. Se não precisar de acesso externo ao banco, mantenha-as fechadas.

6. Add-ons

Ficam na aba Add-Ons do nó. Todos pedem confirmação antes de agir.

6.1 Senha do painel Supabase

Botão Redefinir senha: gera uma senha nova para o Studio (usuário supabase), aplica e envia por e-mail. A senha anterior para de funcionar na hora. O painel fica indisponível por alguns segundos.

6.2 Custom Domain

Aplica um domínio próprio (ex.: api.suaempresa.com.br) nas configurações do Supabase. Ele não emite certificado. A ordem é:

No DNS, aponte o domínio para o ambiente: CNAME para o domínio do ambiente ou registro A para o IP público do nó.
No add-on Let's Encrypt Free SSL → Configure, adicione o domínio.
No add-on Custom Domain, informe o domínio e clique em Configurar domínio.

Os containers são reiniciados (até ~1 minuto fora do ar). O Supabase passa a responder no domínio novo e continua no domínio do ambiente. Depois, atualize a URL nos seus apps. Para voltar, informe o próprio domínio do ambiente.

6.3 MCP

O MCP (Model Context Protocol) permite que assistentes de IA (Claude, Cursor, VS Code etc.) consultem e administrem o projeto: listar tabelas, rodar SQL, ver a documentação.

Botão	O que faz
Habilitar / gerar novo token	Habilita o endpoint (se ainda não estiver) e gera um token novo, enviado por e-mail. Um token anterior deixa de funcionar.
Desabilitar	Bloqueia o `/mcp`, remove o token e desfaz a configuração do MCP, voltando ao padrão da instalação.

Nos dois casos o proxy e o api-gw são reiniciados (alguns segundos fora do ar).

⚠️ Quem tem o token tem acesso administrativo ao projeto. Trate-o como a secret key: não publique, não coloque em repositório e gere outro se vazar.

7. Uso do MCP

7.1 Conexão

Campo	Valor
URL	`https://<domínio>/mcp`
Header	`Authorization: Bearer <token>`

Sem o header correto, o /mcp responde 401. Com o MCP desabilitado, a rota fica bloqueada (403).

7.2 Exemplo de configuração no cliente

A maioria dos clientes MCP aceita um JSON como este:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://<domínio>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

8. Operação

O acesso ao servidor é pelo Web SSH do nó (usuário root). Os comandos abaixo rodam em /home/supabase.

8.1 Comandos

Comando	O que faz
`sh run.sh start`	Aplica mudanças do `.env` (recria só o que mudou)
`sh run.sh status`	Estado dos containers
`sh run.sh logs`	Acompanha os logs (`sh run.sh logs auth` para um serviço; Ctrl+C para sair)
`sh run.sh restart`	Reinicia os serviços

Toda a configuração fica em /home/supabase/.env. Depois de editar, rode sh run.sh start.

8.2 Configurações de Auth e e-mail

O .env vem sem servidor de e-mail real. Sem SMTP, os e-mails do Auth (confirmação de cadastro, magic link, recuperação de senha) não são entregues — e, como a confirmação de e-mail vem ligada, usuários novos não conseguem confirmar o cadastro.

Antes de liberar cadastro por e-mail, ajuste no .env:

Variável	Para quê
`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`	Seu provedor de e-mail
`SMTP_ADMIN_EMAIL`, `SMTP_SENDER_NAME`	Remetente dos e-mails
`SITE_URL`	URL do seu app (destino padrão dos links de e-mail)
`ADDITIONAL_REDIRECT_URLS`	Outras URLs permitidas para redirect, separadas por vírgula
`DISABLE_SIGNUP`	`true` para bloquear novos cadastros
`ENABLE_EMAIL_AUTOCONFIRM`	`true` dispensa a confirmação por e-mail (não recomendado em produção)

Provedores OAuth (Google, GitHub etc.) também se configuram por variáveis de ambiente do serviço auth — veja a documentação do Supabase.

8.3 Onde ficam os dados

Caminho	Conteúdo
`/home/supabase/volumes/db/data`	Dados do PostgreSQL
`/home/supabase/volumes/storage`	Arquivos do Storage
`/home/supabase/volumes/functions`	Código das Edge Functions (uma pasta por função)
`/home/supabase/.env`	Configuração, senhas e chaves

8.4 Backups

Não há backup automático. Recomendado:

Banco: pg_dump periódico, por exemplo:

cd /home/supabase
docker exec supabase-db pg_dump -U postgres -Fc postgres > backup-$(date +%F).dump

e copie o arquivo para fora do servidor.

Arquivos: copie /home/supabase/volumes/storage.
Configuração: guarde uma cópia do .env em local seguro (sem ele, as chaves JWT mudam e os tokens emitidos param de valer).

8.5 Recursos

Se o Studio ficar lento ou containers reiniciarem por falta de memória, aumente o limite de cloudlets do nó na Topologia do Ambiente.

9. Segurança — checklist

Guardar o e-mail de instalação em local seguro e trocar a senha do painel se ele for compartilhado.
Usar só a publishable key no frontend; secret/service role só no backend.
Ativar RLS em todas as tabelas expostas pela API.
Configurar SMTP antes de abrir cadastro por e-mail.
Fechar as portas 5432/6543 se não houver acesso externo ao banco.
Habilitar o MCP só se for usar, gerar novo token se ele vazar e desabilitar quando não precisar mais.

10. Problemas comuns

Sintoma	Causa provável / o que fazer
Navegador avisa certificado inválido	Certificado ainda não emitido ou domínio fora dele: confira o add-on Let's Encrypt
Domínio próprio não abre	DNS não aponta para o ambiente, ou o domínio não foi incluído no Let's Encrypt antes do Custom Domain
E-mail de confirmação não chega	SMTP não configurado (ver seção 8.2)
`/mcp` responde 401	Token ausente/errado no header `Authorization: Bearer`
`/mcp` responde 403	MCP desabilitado: use Habilitar no add-on MCP
Algo não sobe	`sh run.sh status` e `sh run.sh logs <serviço>`

1. O que é​

2. Para que serve​

3. Self-hosted × Supabase Cloud: o que muda​

4. Instalação​

4.1 Opções​

4.2 O que é criado​

5. Acessos​

5.1 Studio (painel)​

5.2 API (para os apps)​

5.3 PostgreSQL (conexão direta)​

6. Add-ons​

6.1 Senha do painel Supabase​

6.2 Custom Domain​

6.3 MCP​

7. Uso do MCP​

7.1 Conexão​

7.2 Exemplo de configuração no cliente​

8. Operação​

8.1 Comandos​

8.2 Configurações de Auth e e-mail​

8.3 Onde ficam os dados​

8.4 Backups​

8.5 Recursos​

9. Segurança — checklist​

10. Problemas comuns​

11. Referências​