docs(supabase): Add self-hosted configuration guide and update env templates
This commit is contained in:
Erik Silva
277
SUPABASE_SELFHOSTED_SETUP.md
Normal file
277
SUPABASE_SELFHOSTED_SETUP.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 🔧 Supabase Self-Hosted Configuration Guide
|
||||
|
||||
## 📌 O que é Supabase Self-Hosted?
|
||||
|
||||
Supabase self-hosted é uma implementação da plataforma Supabase que você hospeda em sua própria infraestrutura (servidor, VPS, Docker, etc.) ao invés de usar o serviço cloud em `supabase.co`.
|
||||
|
||||
**Sua URL**: `https://supabase.stackbackup.cloud/`
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Configuração no Backend (NestJS)
|
||||
|
||||
### Passo 1: Arquivo `.env` do Backend
|
||||
|
||||
```dotenv
|
||||
# ============================================================================
|
||||
# SUPABASE CONFIGURATION (Self-Hosted)
|
||||
# ============================================================================
|
||||
SUPABASE_URL=https://supabase.stackbackup.cloud
|
||||
SUPABASE_ANON_KEY=seu_anon_key_aqui
|
||||
SUPABASE_SERVICE_KEY=seu_service_key_aqui
|
||||
|
||||
# ============================================================================
|
||||
# JWT CONFIGURATION
|
||||
# ============================================================================
|
||||
JWT_SECRET=sua_chave_secreta_minimo_32_caracteres
|
||||
JWT_EXPIRATION=7d
|
||||
|
||||
# ============================================================================
|
||||
# DATABASE (Opcional - se precisar acesso direto)
|
||||
# ============================================================================
|
||||
# DATABASE_URL=postgresql://user:password@seu-host:5432/postgres
|
||||
|
||||
# ============================================================================
|
||||
# APP CONFIGURATION
|
||||
# ============================================================================
|
||||
NODE_ENV=development
|
||||
PORT=3000
|
||||
API_PREFIX=/api
|
||||
|
||||
# ============================================================================
|
||||
# CORS CONFIGURATION
|
||||
# ============================================================================
|
||||
CORS_ORIGIN=http://localhost:3000,http://localhost:3001
|
||||
```
|
||||
|
||||
### Passo 2: Verificar Conexão com Supabase Self-Hosted
|
||||
|
||||
Ao rodar o backend:
|
||||
|
||||
```bash
|
||||
cd backend-api
|
||||
npm run start:dev
|
||||
```
|
||||
|
||||
**Você deve ver no console:**
|
||||
```
|
||||
Supabase client initialized successfully
|
||||
Connected to: https://supabase.stackbackup.cloud
|
||||
```
|
||||
|
||||
### Passo 3: Encontrar suas Chaves API
|
||||
|
||||
1. **Acesse**: `https://supabase.stackbackup.cloud/`
|
||||
2. **Vá para**: Projeto → Settings → API
|
||||
3. **Copie**:
|
||||
- `SUPABASE_URL` - URL base do seu Supabase
|
||||
- `SUPABASE_ANON_KEY` - Chave anônima (pública, ok expor no frontend)
|
||||
- `SUPABASE_SERVICE_KEY` - Chave de serviço (SECRETA! só backend)
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Configuração no Frontend (Next.js)
|
||||
|
||||
### Passo 1: Arquivo `.env.local` do Frontend
|
||||
|
||||
```dotenv
|
||||
# ============================================================================
|
||||
# API Backend
|
||||
# ============================================================================
|
||||
NEXT_PUBLIC_API_URL=http://localhost:3000/api
|
||||
NEXT_PUBLIC_API_TIMEOUT=10000
|
||||
|
||||
# ============================================================================
|
||||
# Supabase (Self-Hosted)
|
||||
# ============================================================================
|
||||
NEXT_PUBLIC_SUPABASE_URL=https://supabase.stackbackup.cloud
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=seu_anon_key_aqui
|
||||
|
||||
# ============================================================================
|
||||
# Aplicação
|
||||
# ============================================================================
|
||||
NEXT_PUBLIC_APP_NAME=Task Manager
|
||||
NEXT_PUBLIC_APP_VERSION=1.0.0
|
||||
```
|
||||
|
||||
### Passo 2: Usar no Frontend (se necessário)
|
||||
|
||||
Se quiser integração direta com Supabase no frontend:
|
||||
|
||||
```typescript
|
||||
import { createClient } from '@supabase/supabase-js';
|
||||
|
||||
const supabase = createClient(
|
||||
process.env.NEXT_PUBLIC_SUPABASE_URL!,
|
||||
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Diferenças entre ANON_KEY e SERVICE_KEY
|
||||
|
||||
| Propriedade | ANON_KEY | SERVICE_KEY |
|
||||
|------------|----------|------------|
|
||||
| **Localização** | Frontend (público) | Backend (secreto) |
|
||||
| **Permissões** | Limitadas (usuário autenticado) | Total (sem verificação RLS) |
|
||||
| **Segurança** | Ok expor | ⚠️ NUNCA expor |
|
||||
| **Uso** | Autenticação, queries do usuário | Admin tasks, bypass RLS |
|
||||
|
||||
**Seu arquivo `.env.example`**:
|
||||
```dotenv
|
||||
# Público - OK no frontend
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
|
||||
# Secreto - NUNCA EXPOR! Apenas backend
|
||||
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Fluxo de Autenticação
|
||||
|
||||
```
|
||||
Frontend Backend Supabase
|
||||
| | |
|
||||
|--- Clica Login | |
|
||||
| | |
|
||||
|--- POST /auth/login --------> | |
|
||||
| (email, password) |--- Autentica com -------> |
|
||||
| | ANON_KEY |
|
||||
| |<--- JWT token -------------|
|
||||
|<---- Retorna JWT -------------| |
|
||||
| | |
|
||||
| (Armazena token) | |
|
||||
| | |
|
||||
|--- GET /tasks | |
|
||||
| Authorization: Bearer {token} |
|
||||
| |--- Valida JWT |
|
||||
| |--- SELECT * from tasks |
|
||||
| | WHERE user_id = xxx |
|
||||
| | (RLS aplica) --------> |
|
||||
|<--- Retorna tarefas ----------|<--- Tarefas do usuário ---|
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testar Configuração
|
||||
|
||||
### 1. Backend - Testar Conexão
|
||||
|
||||
```bash
|
||||
# Rodar backend
|
||||
cd backend-api
|
||||
npm run start:dev
|
||||
|
||||
# Em outro terminal, testar endpoint
|
||||
curl http://localhost:3000/api/auth/me \
|
||||
-H "Authorization: Bearer seu_token_jwt"
|
||||
```
|
||||
|
||||
**Esperado**:
|
||||
- ✅ Retorna dados do usuário
|
||||
- ❌ 401 se token inválido
|
||||
- ❌ 500 se não conseguir conectar Supabase
|
||||
|
||||
### 2. Frontend - Testar Conexão
|
||||
|
||||
```bash
|
||||
# Rodar frontend
|
||||
cd frontend-next
|
||||
npm run dev
|
||||
|
||||
# Abrir http://localhost:3000
|
||||
# Tentar fazer login
|
||||
|
||||
# Ver console do navegador
|
||||
# Deve mostrar: "API conectada com sucesso"
|
||||
```
|
||||
|
||||
### 3. Verificar URLs
|
||||
|
||||
```bash
|
||||
# Backend deve conseguir alcançar Supabase
|
||||
curl https://supabase.stackbackup.cloud/auth/v1/health
|
||||
|
||||
# Esperado: {"version":"1.x.x"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Troubleshooting
|
||||
|
||||
### Erro: "ENOTFOUND supabase.stackbackup.cloud"
|
||||
|
||||
**Problema**: DNS não está resolvendo a URL
|
||||
**Solução**:
|
||||
1. Verificar se `supabase.stackbackup.cloud` está acessível
|
||||
2. Testar: `ping supabase.stackbackup.cloud`
|
||||
3. Verificar firewall/proxy
|
||||
|
||||
### Erro: "Invalid API key"
|
||||
|
||||
**Problema**: ANON_KEY ou SERVICE_KEY incorreta
|
||||
**Solução**:
|
||||
1. Ir para: `https://supabase.stackbackup.cloud/` → Settings → API
|
||||
2. Copiar chaves novamente (sem espaços extras)
|
||||
3. Atualizar `.env`
|
||||
4. Reiniciar servidores
|
||||
|
||||
### Erro: "CORS error"
|
||||
|
||||
**Problema**: Frontend não consegue chamar backend
|
||||
**Solução**:
|
||||
1. Verificar `NEXT_PUBLIC_API_URL` no frontend
|
||||
2. Verificar `CORS_ORIGIN` no backend
|
||||
3. Certificar que URLs correspondem
|
||||
|
||||
**Backend `.env`**:
|
||||
```dotenv
|
||||
CORS_ORIGIN=http://localhost:3000,https://seu-frontend.com
|
||||
```
|
||||
|
||||
### Erro: "RLS policy violation"
|
||||
|
||||
**Problema**: Usuário não consegue acessar dados por RLS
|
||||
**Solução**:
|
||||
1. Executar SQL de RLS no Supabase:
|
||||
- `https://supabase.stackbackup.cloud/` → SQL Editor
|
||||
- Colar `SQL_TASKS_TABLE_RLS.sql`
|
||||
- Clicar RUN
|
||||
|
||||
---
|
||||
|
||||
## 📚 Referências
|
||||
|
||||
- 📖 [Supabase Self-Hosted Docs](https://supabase.com/docs/guides/hosting/overview)
|
||||
- 📖 [Supabase API Keys](https://supabase.com/docs/guides/api/api-keys)
|
||||
- 📖 [JWT & RLS](https://supabase.com/docs/guides/auth/row-level-security)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Checklist de Configuração
|
||||
|
||||
Para seu setup com `supabase.stackbackup.cloud`:
|
||||
|
||||
- [ ] **Backend `.env`**:
|
||||
- [ ] `SUPABASE_URL=https://supabase.stackbackup.cloud`
|
||||
- [ ] `SUPABASE_ANON_KEY=...` (copiar correto)
|
||||
- [ ] `SUPABASE_SERVICE_KEY=...` (copiar correto)
|
||||
- [ ] `JWT_SECRET=...` (minimo 32 chars)
|
||||
|
||||
- [ ] **Frontend `.env.local`**:
|
||||
- [ ] `NEXT_PUBLIC_API_URL=http://localhost:3000/api`
|
||||
- [ ] `NEXT_PUBLIC_SUPABASE_URL=https://supabase.stackbackup.cloud`
|
||||
- [ ] `NEXT_PUBLIC_SUPABASE_ANON_KEY=...` (copiar correto)
|
||||
|
||||
- [ ] **Testar Conexão**:
|
||||
- [ ] Backend inicia sem erros
|
||||
- [ ] Frontend consegue fazer login
|
||||
- [ ] Consegue criar/listar tarefas
|
||||
- [ ] RLS está isolando dados por usuário
|
||||
|
||||
---
|
||||
|
||||
**Status**: 🟢 Configurado para Supabase Self-Hosted
|
||||
**URL**: `https://supabase.stackbackup.cloud/`
|
||||
Reference in New Issue
Block a user