Como instalar o Supabase em uma VPS

Pré-requisitos

Escolha Ubuntu 22.04 ou 24.04 com SSH, IP público e um domínio dedicado, como api.example.com. Os requisitos mínimos oficiais são 4 GB de RAM no mínimo (8 GB recomendados), 2 ou mais núcleos de CPU e mais de 40 GB de SSD. Uma instalação de desenvolvimento pode usar uma máquina modesta, enquanto a produção precisa de espaço para PostgreSQL, logs, armazenamento e migrações.

Você precisa do Docker Compose, de um meio seguro para gerar segredos e de armazenamento fora da VPS para os backups. A auto-hospedagem do Supabase pressupõe que você consegue manter o sistema operacional e o banco de dados. Não é um serviço de banco de dados gerenciado.

Etapa 1, conectando-se ao servidor

Conecte-se e crie um diretório de trabalho protegido:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl git
mkdir -p /opt/supabase
cd /opt/supabase
chmod 750 /opt/supabase

Abra somente SSH, HTTP e HTTPS no nível do provedor. Evite instalar outro proxy reverso ou outra instância PostgreSQL até entender quais portas o conjunto oficial de serviços usa.

Etapa 2, instalando o Docker e o Docker Compose

Instale o Docker Engine e o plugin Compose seguindo as instruções oficiais do Docker para Ubuntu. Confira a instalação:

docker --version
docker compose version
systemctl enable --now docker

Confira o espaço em disco e a memória disponíveis antes de baixar as imagens:

df -h
free -h

Etapa 3, executando o conjunto oficial de serviços do Supabase

O Supabase mantém a configuração Docker para auto-hospedagem em seu repositório oficial. A maneira recomendada de iniciar é pelo script oficial de configuração:

curl -fsSL https://supabase.link/setup.sh | sh

Como alternativa, clone o repositório manualmente:

git clone --depth 1 https://github.com/supabase/supabase.git source
cd source/docker
cp .env.example .env

Segredos e chaves JWT

O Supabase agora usa pares de chaves JWT assimétricas em vez de um único JWT_SECRET. Depois de clonar, gere as chaves necessárias com os scripts auxiliares incluídos:

./docker/utils/generate-keys.sh
./docker/utils/add-new-auth-keys.sh

Esses scripts criam o par de chaves RSA para assinatura de JWT e adicionam as novas chaves à configuração de autenticação. O arquivo docker/volumes/api/kong.yml gerencia o Gateway e docker/volumes/db/init/ cuida do banco de dados.

Variáveis de ambiente críticas

Abra .env e substitua todos os marcadores de posição. Os valores padrão de .env.example são PERIGOSOS e nunca devem ser usados em produção.

Variável	Requisitos
DASHBOARD_PASSWORD	Precisa conter pelo menos uma letra (senhas só com números são rejeitadas)
POSTGRES_PASSWORD	Use somente letras e números para evitar problemas com codificação de URL

Todos os outros marcadores de posição em .env também devem ser substituídos por valores exclusivos gerados. Nunca publique esse arquivo.

Usuários do Windows: Se você clonar o repositório no Windows, confirme que as terminações de linha são LF (estilo Unix). Terminações CRLF quebram o script de inicialização do Kong Gateway. Execute git config --global core.autocrlf false antes de clonar ou converta o arquivo com dos2unix.

Valide todo o projeto oficial antes de iniciá-lo:

docker compose config
docker compose pull
docker compose up -d
docker compose ps

O arquivo Compose oficial é a implantação de referência deste guia. Não o substitua por um arquivo personalizado curto, pois remover um gateway, uma migração ou um serviço de armazenamento pode deixar o serviço de back-end funcionando apenas parcialmente.

Etapa 4, configurando o proxy reverso

O Supabase inclui arquivos oficiais de configuração complementar para Caddy e Nginx. Ative-os com:

sh run.sh config add caddy
# or
sh run.sh config add nginx

Encaminhe api.example.com para a porta localhost do gateway indicada no arquivo Compose oficial. Atualize estas variáveis em .env para corresponder ao seu domínio:

SUPABASE_PUBLIC_URL=https://api.example.com
API_EXTERNAL_URL=https://api.example.com
SITE_URL=https://api.example.com

Encerre o TLS no proxy, encaminhe os cabeçalhos originais do servidor e do protocolo e mantenha PostgreSQL e os serviços internos privados. Se precisar acessar o Studio remotamente, proteja-o pelo método de acesso documentado para sua versão, em vez de abrir todas as portas dos contêineres.

WebSocket: O Supabase Realtime precisa de suporte a WebSocket no proxy. Confirme que a configuração do proxy reverso permite atualizações WebSocket (o Caddy faz isso por padrão; o Nginx exige proxy_set_header Upgrade $http_upgrade e proxy_set_header Connection "upgrade" explícitos).

Teste o endpoint HTTPS, uma solicitação autenticada à API e uma operação de armazenamento. Uma página válida do painel, por si só, não comprova que as migrações do banco de dados, a autenticação ou o armazenamento de objetos estão funcionando corretamente.

Etapa 5, primeiro acesso e configuração inicial

Acesse o endereço do Studio pela rota protegida e entre com as credenciais configuradas em .env. Crie um projeto de teste ou use o projeto padrão apenas para avaliação. Registre a URL do projeto e a chave anônima pública na configuração do aplicativo, mas mantenha as chaves da função de serviço no servidor.

Crie uma tabela, aplique uma migração e teste a autenticação em um aplicativo descartável. Confirme que a segurança em nível de linha está ativada onde deveria. Nunca use uma chave da função de serviço em código de navegador.

Manutenção

Faça backup do PostgreSQL, dos objetos de armazenamento e de todos os segredos de ambiente. Consulte as notas de versão do projeto oficial antes de atualizar o repositório e as imagens. Faça um snapshot do banco de dados antes das migrações, execute a atualização em uma janela de manutenção e verifique a autenticação, as APIs e o armazenamento depois.

Monitore as conexões do banco de dados, o disco, o armazenamento de objetos, os erros do gateway e a integridade dos contêineres. Se um serviço falhar, colete docker compose ps, os logs do serviço e a configuração Compose efetiva antes de reiniciar ou excluir qualquer coisa.