Supabase Self-Hosted — Guía del usuario

Guía del producto Supabase Self-Hosted del marketplace: qué es, para qué sirve, en qué se diferencia de Supabase Cloud y cómo acceder y operar lo que se instala.

1. Qué es

Supabase es una alternativa open-source a Firebase. En un único paquete, entrega el backend completo de una aplicación sobre una base de datos PostgreSQL:

Componente	Para qué sirve
PostgreSQL	Base de datos relacional, con acceso directo mediante cadena de conexión
API REST y GraphQL	API generada automáticamente a partir de las tablas (PostgREST)
Auth	Registro, login (email/contraseña, magic link, OAuth), sesiones y JWT
Storage	Carga y entrega de archivos, con reglas de acceso
Realtime	Eventos en tiempo real (cambios en la base, broadcast, presencia)
Edge Functions	Funciones serverless en Deno/TypeScript
Studio	Panel web para administrar todo lo anterior

Este producto instala la versión self-hosted oficial (self-hosted/v0.8.2), siguiendo la documentación de Supabase, en un nodo Docker de tu entorno, con HTTPS (certificado Let's Encrypt) a través del proxy Caddy.

2. Para qué sirve

Tener el backend de una app (web o móvil) — base de datos, login, archivos y API — sin escribir un servidor desde cero.
Mantener los datos en tu infraestructura, en la región de tu entorno (útil para LGPD/RGPD y políticas internas).
Tener un costo previsible, según los recursos del entorno, sin cobros de Supabase por usuario activo, solicitud o almacenamiento.
Entornos de desarrollo, homologación o producción que controlas por completo.

3. Self-hosted × Supabase Cloud: qué cambia

Solo las diferencias que afectan el uso diario:

Tema	Supabase Cloud (hosted)	Este producto (self-hosted)
Proyectos	Varios proyectos por organización	Un proyecto por entorno (para otro proyecto, instala otro entorno)
Actualizaciones	Las hace Supabase	Versión fija (`v0.8.2`); actualizar es manual
Config. de Auth (SMTP, proveedores OAuth, URLs de redirect)	Desde el panel	Desde el archivo `.env` + reinicio (ver sección 8.2)
Emails de Auth	SMTP integrado (con límites)	Sin SMTP real: configura el tuyo antes de habilitar el registro por email
Panel (Studio)	Completo: organizaciones, billing, branching	Reducido: un proyecto, sin billing/branching
Edge Functions	Deploy con la CLI (`supabase functions deploy`)	Código en `/home/supabase/volumes/functions` en el servidor
Escala y recursos	Gestionados por Supabase	Recursos del nodo ajustables por ti

Resumen: ganas control, datos en tu servidor y costo fijo; a cambio, backups, actualizaciones, email y monitoreo pasan a ser tuyos.

4. Instalación

4.1 Opciones

Opción	Predeterminado	Qué hace
Habilitar MCP	Desmarcada	Expone el servidor MCP de Supabase en `https://<dominio>/mcp`, protegido por token (ver secciones 6.3 y 7). Se puede habilitar o deshabilitar después con el add-on MCP.

4.2 Qué se crea

Un nodo Docker Engine con IP pública, puertos 80/443, hasta 32 cloudlets (8 reservados) y 30 GB de disco. Todo lo de Supabase queda en /home/supabase (volumen persistente).

Durante la instalación, automáticamente:

Se generan la contraseña del panel, la contraseña de PostgreSQL, las claves JWT/API y, si está marcado, el token del MCP.
Se descargan los archivos oficiales de Supabase y el .env se configura con el dominio del entorno.
Se descargan las imágenes Docker y se inician los servicios mientras el add-on Let's Encrypt Free SSL emite el certificado (en paralelo, para instalar más rápido).
Caddy arranca con el certificado y se prueba el HTTPS.
Se instalan los add-ons Senha do painel Supabase, Custom Domain y MCP.

Al final, la pantalla de éxito (también enviada por email) trae todos los accesos. Guarda ese email — es el único lugar con todas las contraseñas y claves juntas.

5. Accesos

En los ejemplos, <dominio> es el dominio del entorno (ej.: env-1234567.sp1.br.saveincloud.net.br) o tu dominio propio, si está configurado.

5.1 Studio (panel)

Acceso	Valor
URL	`https://<dominio>`
Usuario	`supabase`
Contraseña	la del email de instalación (cámbiala con el add-on Senha do painel Supabase)

Studio es el panel de administración: tablas, SQL Editor, usuarios de Auth, buckets de Storage, políticas (RLS) y claves.

5.2 API (para las apps)

La URL del proyecto es https://<dominio> — la misma que se usa en el SDK:

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

Clave	Dónde usarla
Publishable key (`sb_publishable_…`)	Frontend y apps móviles. Es pública; el acceso queda limitado por las políticas RLS.
Secret key (`sb_secret_…`)	Solo en el backend. Ignora el RLS: nunca la pongas en código de navegador/app.
Anon key (legado)	Equivalente a la publishable, para bibliotecas antiguas.
Service role key (legado)	Equivalente a la secret, para bibliotecas antiguas. Solo en el backend.

Endpoints disponibles: /rest/v1, /graphql/v1, /auth/v1, /storage/v1, /realtime/v1 y /functions/v1.

5.3 PostgreSQL (conexión directa)

La conexión pasa por el pooler (Supavisor). El usuario incluye el nombre del entorno:

postgresql://postgres.<nombre-del-entorno>:<contraseña-de-postgres>@<dominio>:5432/postgres

Puerto	Modo	Cuándo usarlo
5432	Session	Herramientas (DBeaver, pgAdmin, `psql`), migraciones, apps con conexiones largas
6543	Transaction	Serverless y muchas conexiones cortas

Si la conexión externa no funciona, verifica que el firewall del entorno permita los puertos 5432/6543. Si no necesitas acceso externo a la base, mantenlos cerrados.

6. Add-ons

Están en la pestaña Add-Ons del nodo. Todos piden confirmación antes de actuar.

6.1 Senha do painel Supabase (contraseña del panel de Supabase)

Botón Redefinir senha (Restablecer contraseña): genera una contraseña nueva para Studio (usuario supabase), la aplica y la envía por email. La contraseña anterior deja de funcionar al instante. El panel queda indisponible por unos segundos.

6.2 Custom Domain

Aplica un dominio propio (ej.: api.tuempresa.com) en la configuración de Supabase. No emite certificado. El orden es:

En el DNS, apunta el dominio al entorno: un CNAME al dominio del entorno o un registro A a la IP pública del nodo.
En el add-on Let's Encrypt Free SSL → Configure, agrega el dominio.
En el add-on Custom Domain, ingresa el dominio y haz clic en Configurar domínio (Configurar dominio).

Los contenedores se reinician (hasta ~1 minuto fuera de línea). Supabase pasa a responder en el dominio nuevo y sigue respondiendo en el dominio del entorno. Después, actualiza la URL en tus apps. Para volver, ingresa el propio dominio del entorno.

6.3 MCP

El MCP (Model Context Protocol) permite que asistentes de IA (Claude, Cursor, VS Code, etc.) consulten y administren el proyecto: listar tablas, ejecutar SQL, ver la documentación.

Botón	Qué hace
Habilitar / gerar novo token (Habilitar / generar nuevo token)	Habilita el endpoint (si aún no lo está) y genera un token nuevo, enviado por email. Un token anterior deja de funcionar.
Desabilitar (Deshabilitar)	Bloquea `/mcp`, elimina el token y deshace la configuración del MCP, volviendo al estado predeterminado de la instalación.

En ambos casos se reinician el proxy y el api-gw (unos segundos fuera de línea).

⚠️ Quien tiene el token tiene acceso administrativo al proyecto. Trátalo como la secret key: no lo publiques, no lo subas a un repositorio y genera otro si se filtra.

7. Uso del MCP

7.1 Conexión

Campo	Valor
URL	`https://<dominio>/mcp`
Header	`Authorization: Bearer <token>`

Sin el header correcto, /mcp responde 401. Con el MCP deshabilitado, la ruta queda bloqueada (403).

7.2 Ejemplo de configuración en el cliente

La mayoría de los clientes MCP acepta un JSON como este:

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

8. Operación

El acceso al servidor es por el Web SSH del nodo (usuario root). Los comandos de abajo se ejecutan en /home/supabase.

8.1 Comandos

Comando	Qué hace
`sh run.sh start`	Aplica los cambios del `.env` (recrea solo lo que cambió)
`sh run.sh status`	Estado de los contenedores
`sh run.sh logs`	Sigue los logs (`sh run.sh logs auth` para un servicio; Ctrl+C para salir)
`sh run.sh restart`	Reinicia los servicios

Toda la configuración está en /home/supabase/.env. Después de editarlo, ejecuta sh run.sh start.

8.2 Configuración de Auth y email

El .env viene sin un servidor de email real. Sin SMTP, los emails de Auth (confirmación de registro, magic link, recuperación de contraseña) no se entregan — y, como la confirmación por email viene activada, los usuarios nuevos no pueden confirmar su registro.

Antes de habilitar el registro por email, ajusta en el .env:

Variable	Para qué
`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`	Tu proveedor de email
`SMTP_ADMIN_EMAIL`, `SMTP_SENDER_NAME`	Remitente de los emails
`SITE_URL`	URL de tu app (destino predeterminado de los enlaces de email)
`ADDITIONAL_REDIRECT_URLS`	Otras URLs permitidas para redirect, separadas por coma
`DISABLE_SIGNUP`	`true` para bloquear nuevos registros
`ENABLE_EMAIL_AUTOCONFIRM`	`true` omite la confirmación por email (no recomendado en producción)

Los proveedores OAuth (Google, GitHub, etc.) también se configuran con variables de entorno del servicio auth — consulta la documentación de Supabase.

8.3 Dónde están los datos

Ruta	Contenido
`/home/supabase/volumes/db/data`	Datos de PostgreSQL
`/home/supabase/volumes/storage`	Archivos de Storage
`/home/supabase/volumes/functions`	Código de las Edge Functions (una carpeta por función)
`/home/supabase/.env`	Configuración, contraseñas y claves

8.4 Backups

No hay backup automático. Recomendado:

Base de datos: pg_dump periódico, por ejemplo:

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

y copia el archivo fuera del servidor.

Archivos: copia /home/supabase/volumes/storage.
Configuración: guarda una copia del .env en un lugar seguro (sin él, las claves JWT cambian y los tokens emitidos dejan de ser válidos).

8.5 Recursos

Si Studio se vuelve lento o los contenedores se reinician por falta de memoria, aumenta el límite de cloudlets del nodo en la Topología del Entorno.

9. Seguridad — checklist

Guardar el email de instalación en un lugar seguro y cambiar la contraseña del panel si se comparte.
Usar solo la publishable key en el frontend; secret/service role solo en el backend.
Activar RLS en todas las tablas expuestas por la API.
Configurar SMTP antes de abrir el registro por email.
Cerrar los puertos 5432/6543 si no hay acceso externo a la base.
Habilitar el MCP solo si lo vas a usar, generar un token nuevo si se filtra y deshabilitarlo cuando ya no se necesite.

10. Problemas comunes

Síntoma	Causa probable / qué hacer
El navegador avisa de un certificado inválido	Certificado aún no emitido o el dominio no está en él: revisa el add-on Let's Encrypt
El dominio propio no abre	El DNS no apunta al entorno, o el dominio no se agregó en Let's Encrypt antes de Custom Domain
No llega el email de confirmación	SMTP no configurado (ver sección 8.2)
`/mcp` responde 401	Token ausente/incorrecto en el header `Authorization: Bearer`
`/mcp` responde 403	MCP deshabilitado: usa Habilitar en el add-on MCP
Algo no arranca	`sh run.sh status` y `sh run.sh logs <servicio>`

1. Qué es​

2. Para qué sirve​

3. Self-hosted × Supabase Cloud: qué cambia​

4. Instalación​

4.1 Opciones​

4.2 Qué se crea​

5. Accesos​

5.1 Studio (panel)​

5.2 API (para las apps)​

5.3 PostgreSQL (conexión directa)​

6. Add-ons​

6.1 Senha do painel Supabase (contraseña del panel de Supabase)​

6.2 Custom Domain​

6.3 MCP​

7. Uso del MCP​

7.1 Conexión​

7.2 Ejemplo de configuración en el cliente​

8. Operación​

8.1 Comandos​

8.2 Configuración de Auth y email​

8.3 Dónde están los datos​

8.4 Backups​

8.5 Recursos​

9. Seguridad — checklist​

10. Problemas comunes​

11. Referencias​