# Como instalar o Supabase self-hosted numa VPS Ubuntu | Nuvits

Fonte: [https://nuvits.net/blog/como-instalar-supabase-self-hosted-vps-ubuntu](https://nuvits.net/blog/como-instalar-supabase-self-hosted-vps-ubuntu)

Publicado em 2026-11-21, por Fernando Chagas.

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.

As versões e arquivos deste passo a passo acompanham o repositório oficial [`supabase/supabase`](https://github.com/supabase/supabase/tree/master/docker), 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](https://nuvits.net/blog/como-instalar-n8n-docker-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](https://nuvits.net/blog/como-instalar-supabase-self-hosted-vps-ubuntu/arquitetura-supabase-self-hosted-caddy-envoy.webp)

> **Atenção às portas 5432 e 6543 do Supavisor.** O `docker-compose.caddy.yml` oficial remove a porta `8000` do Envoy, mas não altera o serviço `supavisor`, que continua publicando `5432` e `6543` em `0.0.0.0`. Como o Docker contorna regras de entrada do `ufw`, vamos adicionar um override próprio (`docker-compose.local-db.yml`) para prender essas duas portas a `127.0.0.1`. O motivo detalhado está em [A porta do Docker continua aberta com o ufw](https://nuvits.net/blog/porta-do-docker-aberta-com-ufw).

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

> **Guarde o `.env` fora da VPS.** Sem `POSTGRES_PASSWORD`, `JWT_SECRET`, `JWT_KEYS` e `VAULT_ENC_KEY`, um dump do banco restaurado em outro servidor não consegue validar sessões antigas nem decifrar segredos guardados no Vault do Supavisor.

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

```ini .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
SMTP_ADMIN_EMAIL=auth@example.com
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:

```yaml 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:SUA_POSTGRES_PASSWORD@127.0.0.1:5432/postgres"

# Modo transação (porta 6543 — recomendado para apps serverless ou com muitas conexões)
psql "postgresql://postgres.nuvits-prod-01:SUA_POSTGRES_PASSWORD@127.0.0.1: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](https://nuvits.net/blog/backup-automatico-n8n)).

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
```

> **Cuidado ao trocar a versão maior do PostgreSQL.** O `docker-compose.yml` atual usa PostgreSQL 17. Atualizações menores dentro do 17 são diretas; mudanças de versão maior exigem dump e restore planejado, nunca apenas trocar a tag da imagem.

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

- Para entender por que o override `docker-compose.local-db.yml` é indispensável em qualquer VPS com Docker e `ufw`, leia [A porta do Docker continua aberta com o ufw](https://nuvits.net/blog/porta-do-docker-aberta-com-ufw).
- Se quiser conectar automações ao seu banco Supabase ou webhooks do Auth, veja [Como instalar o n8n com Docker numa VPS](https://nuvits.net/blog/como-instalar-n8n-docker-vps).
- Se ainda estiver escolhendo o servidor para hospedar a stack, compare os planos em [VPS com Docker](https://nuvits.net/vps-docker) e [VPS Linux](https://nuvits.net/vps-linux).
