DEPLOYMENT.md

🚀 Deployment Guide — GrantForge AI Enterprise (v1.3.0)

Sprint 9 — Instrukcja produkcyjna
Aktualizacja: kwiecień 2026 | Stack: Render.com + PostgreSQL + GitHub Actions CI/CD

---

Architektura Deploymentu

GitHub (main) → GitHub Actions CI/CD → Render.com
                                      ├── grantforge-api   (FastAPI + Gunicorn)
                                      ├── grantforge-frontend (React SPA)
                                      └── grantforge-db    (PostgreSQL 16)

---

KROK 1: GitHub Repository Secrets

Przejdź do: GitHub → Settings → Secrets and variables → Actions

Wymagane Secrets (CI/CD + Deploy):

Secret Name	Skąd wziąć	Ważny?
GOOGLE_API_KEY	Google AI Studio	✅ Wymagany
VITE_CLERK_PUBLISHABLE_KEY	Clerk Dashboard → API Keys → Publishable Key	✅ Wymagany
RENDER_DEPLOY_HOOK_BACKEND	Render → API service → Settings → Deploy Hook	✅ Wymagany
RENDER_DEPLOY_HOOK_FRONTEND	Render → Static service → Settings → Deploy Hook	✅ Wymagany
PINECONE_API_KEY	Pinecone Console	RAG optional
PINECONE_INDEX_NAME	Pinecone Console → Index name	RAG optional
LANGCHAIN_API_KEY	LangSmith → Settings	Monitoring

Jak dodać secret:

GitHub repo → Settings → Secrets → Actions → New repository secret

Render Deploy Hook (backend):

1. Render Dashboard → grantforge-api → Settings
2. Scroll do sekcji Deploy Hooks
3. Kliknij Add Deploy Hook → Nazwa: ci-deploy
4. Skopiuj URL (format: https://api.render.com/deploy/srv-xxx?key=yyy)
5. Zapisz jako secret RENDER_DEPLOY_HOOK_BACKEND

Render Deploy Hook (frontend):

1. Render Dashboard → grantforge-frontend → Settings
2. Kliknij Add Deploy Hook → Nazwa: ci-frontend
3. Skopiuj URL → Zapisz jako RENDER_DEPLOY_HOOK_FRONTEND

---

KROK 2: Render → Environment Variables

Przejdź do: Render → grantforge-api → Environment

Ustaw następujące zmienne (kliknij Add Environment Variable dla każdej):

# ── LLM ─────────────────────────────
GOOGLE_API_KEY=           # Klucz Google Gemini
BIELIK_MODE=disabled      # disabled / huggingface / ollama

# ── Autentykacja Clerk ───────────────
CLERK_SECRET_KEY=         # sk_live_... (Clerk Dashboard → API Keys)
CLERK_PUBLISHABLE_KEY=    # pk_live_... (Clerk Dashboard → API Keys)

# ── RAG / Pinecone ───────────────────
PINECONE_API_KEY=         # Opcjonalne — bez tego RAG działa lokalnie
PINECONE_INDEX_NAME=      # Nazwa indeksu
PINECONE_ENVIRONMENT=     # Np. "gcp-starter"

# ── LangSmith (monitoring) ───────────
LANGCHAIN_API_KEY=        # ls_... ze smith.langchain.com
LANGCHAIN_TRACING_V2=true
LANGCHAIN_PROJECT=grantforge-production

# ── Stripe (płatności) ───────────────
STRIPE_SECRET_KEY=        # sk_live_...
STRIPE_WEBHOOK_SECRET=    # whsec_...
STRIPE_PRICE_ID_PRO=      # price_...

# ── Dysk danych ──────────────────────
UPLOAD_DIR=/data/uploads
VECTOR_STORE_DIR=/data/vector_store
LLAMAPARSE_CACHE_DIR=/data/llamaparse_cache

Uwaga: DATABASE_URL jest automatycznie wstrzyknięty przez Render Blueprint z bloku databases.

---

KROK 3: Pierwsza Migracja Bazy Danych

Po pierwszym deploymencie na Render, uruchom one-off job alembic:

1. Render → grantforge-api → Shell (lub: one-off command)
2. Wpisz:

   alembic upgrade head
   

3. Sprawdź czy tabele zostały stworzone (w tym project_documents z Sprint 8).

Lokalnie (przed deploy):

cd backend
alembic upgrade head

Jeśli błąd — sprawdź DATABASE_URL w .env.

---

KROK 4: Weryfikacja po Deploy

Po uruchomieniu, zweryfikuj każdy endpoint:

# 1. Health check (podstawowy)
curl https://grantforge-api.onrender.com/api/health

# Oczekiwana odpowiedź:
# {"status": "ok", "db": "connected", "version": "1.3.0", ...}

# 2. Sprawdź czy upload PDF działa
curl -X POST https://grantforge-api.onrender.com/api/projects/TEST_PROJECT_ID/documents \
  -F "file=@test.pdf"
# Oczekiwane: 202 Accepted

# 3. Sprawdź listę dokumentów z kwotą
curl https://grantforge-api.onrender.com/api/projects/TEST_PROJECT_ID/documents
# Oczekiwane: {"documents": [], "quota": {"current": 0, "limit": 3, "plan": "free", "can_upload": true}}

# 4. Sprawdź nabory
curl https://grantforge-api.onrender.com/api/grants/nabory
# Oczekiwane: {"total": N, "sources": [...]}

---

KROK 5: CI/CD — Pierwszy Push

Po skonfigurowaniu secrets, każdy push na main uruchomi pipeline:

git add -A
git commit -m "chore: Sprint 9 — upload limits + E2E tests"
git push origin main

Pipeline (.github/workflows/ci.yml):

1. 🔍 Lint & Type Check (ruff + mypy)
2. 🧪 Backend Tests (pytest)
3. 🎯 DeepEval RAG (tylko main)
4. 🏗️ Frontend Build (Vite)
5. 🐳 Docker Build & Push (ghcr.io)
6. 🚀 Deploy to Render (webhook)

Monitor pipeline: GitHub → Actions → CI/CD — GrantForge AI

---

Limity Upload PDF (Sprint 9)

Plan	Max pliki/projekt	Hard limit
Free	3 PDF	10 PDF
Pro	50 PDF	10 PDF
Enterprise	50 PDF	10 PDF

Hard limit (10) jest bezwzględny — dotyczy wszystkich planów.
Soft limit jest egzekwowany przez _check_upload_limits() w endpoints/documents.py.

---

Troubleshooting

Backend nie startuje

# Sprawdź logi Render → Logs
# Najczęstszy błąd: brak DATABASE_URL lub import error

Alembic error: "Can't locate revision"

cd backend
alembic stamp head  # jeśli tabele już istnieją
alembic upgrade head

Upload 429 Too Many Requests

Użytkownik osiągnął limit planu. Opcje:

1. Usuń stary dokument w zakładce "Dokumenty RAG"
2. Przejdź na plan Pro (/cennik)

RAG nie indeksuje (status: error)

Sprawdź w Render Shell:

# W logach szukaj [RAG Upload] ❌
# Najprawdopodobniejsza przyczyna: Pinecone key / pusty PDF