From 04a775cbaf8aab2be00a69979b3baec7c83c62ed Mon Sep 17 00:00:00 2001
From: Erik Silva <erik@stackbyte.cloud>
Date: Mon, 1 Dec 2025 01:51:06 -0300
Subject: [PATCH] docs(supabase): Add self-hosted configuration guide and
 update env templates

---
 SUPABASE_SELFHOSTED_SETUP.md | 277 +++++++++++++++++++++++++++++++++++
 backend-api/.env.example     |   4 +-
 2 files changed, 280 insertions(+), 1 deletion(-)
 create mode 100644 SUPABASE_SELFHOSTED_SETUP.md

diff --git a/SUPABASE_SELFHOSTED_SETUP.md b/SUPABASE_SELFHOSTED_SETUP.md
new file mode 100644
index 0000000..e8bb939
--- /dev/null
+++ b/SUPABASE_SELFHOSTED_SETUP.md
@@ -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/`
diff --git a/backend-api/.env.example b/backend-api/.env.example
index 19ea10a..ffd943a 100644
--- a/backend-api/.env.example
+++ b/backend-api/.env.example
@@ -1,6 +1,8 @@
 # ======================================
-# SUPABASE CONFIGURATION
+# SUPABASE CONFIGURATION (Self-Hosted)
 # ======================================
+# URL: https://supabase.stackbackup.cloud/
+# Obter chaves em: Projeto → Settings → API
 SUPABASE_URL=https://supabase.stackbackup.cloud
 SUPABASE_ANON_KEY=your_supabase_anon_key_here
 SUPABASE_SERVICE_KEY=your_supabase_service_key_here