docs/HF_COMPLETE_SETUP_GUIDE.md

# 🚀 HUGGINGFACE SPACE - KOMPLET SETUP GUIDE

**Space URL:** https://huggingface.co/spaces/Kraft102/widgetdc-cortex  
**Backend API:** https://kraft102-widgetdc-cortex.hf.space/  
**Status:** Deployed ✅ (Environment setup needed)  
**Dato:** 2025-12-12

---

## ✅ HVAD ER GJORT

- ✅ Backend files uploaded til HuggingFace Space
- ✅ Dockerfile oprettet
- ✅ README.md med Space metadata
- ✅ All source files kopieret korrekt
- ✅ Python deployment script virker

---

## 🔧 STEP 1: TILFØJ ENVIRONMENT VARIABLES (GØR NU!)

### Åbn Space Settings

1. Gå til: **https://huggingface.co/spaces/Kraft102/widgetdc-cortex/settings**
2. Scroll ned til **"Variables and secrets"**
3. Klik **"New secret"** for hver variabel

---

### 🔑 API KEYS (Fra din .env fil)

**Copy-paste disse direkte fra din .env fil:**

#### AI Provider Keys:
```
Name: GEMINI_API_KEY
Value: <copy fra .env>

Name: ANTHROPIC_API_KEY
Value: <copy fra .env>

Name: OPENAI_API_KEY  
Value: <copy fra .env>

Name: GOOGLE_API_KEY
Value: <copy fra .env>

Name: DEEPSEEK_API_KEY
Value: <copy fra .env>

Name: DEEPSEEK_BASE_URL
Value: https://api.deepseek.com
```

#### Tool & Service Keys:
```
Name: FIRECRAWL_API_KEY
Value: <copy fra .env>

Name: EXA_API_KEY
Value: <copy fra .env>

Name: BROWSERBASE_API_KEY
Value: <copy fra .env>

Name: HUGGINGFACE_API_KEY
Value: <copy fra .env>
```

---

### 🗄️ DATABASE CREDENTIALS

**VIGTIGT:** HuggingFace Spaces har IKKE persistent storage!  
Du skal bruge remote database services:

#### Neo4j (Graph Database):
```
Name: NEO4J_URI
Value: <din neo4j uri - f.eks. neo4j+s://xxxx.databases.neo4j.io>

Name: NEO4J_USER
Value: neo4j

Name: NEO4J_PASSWORD
Value: <din neo4j password>
```

**Hvis du IKKE har Neo4j endnu:**
→ Opret gratis på: https://neo4j.com/cloud/aura/
→ Vælg "AuraDB Free"
→ Copy connection URI og credentials

#### PostgreSQL (Vector Database):
```
Name: POSTGRES_HOST
Value: <din postgres host>

Name: POSTGRES_PORT
Value: 5432

Name: POSTGRES_USER
Value: <din postgres user>

Name: POSTGRES_PASSWORD
Value: <din postgres password>

Name: POSTGRES_DB
Value: widgetdc

Name: DATABASE_URL
Value: postgresql://<user>:<password>@<host>:5432/widgetdc
```

**Hvis du IKKE har PostgreSQL endnu:**
→ Opret gratis på: https://neon.tech/
→ Copy connection string

#### Redis (Cache):
```
Name: REDIS_URL
Value: <din redis url>
```

**Hvis du IKKE har Redis endnu:**
→ Opret gratis på: https://upstash.com/
→ Copy Redis URL

---

### ⚙️ BACKEND CONFIGURATION

```
Name: NODE_ENV
Value: production

Name: PORT
Value: 7860

Name: LOG_LEVEL
Value: info

Name: CORS_ORIGIN
Value: *
```

---

## 📊 STEP 2: VERIFICER BUILD STATUS

### Check Docker Build Progress

1. Gå til **"Logs"** tab: https://huggingface.co/spaces/Kraft102/widgetdc-cortex/logs
2. Se Docker build progress
3. Vent til "Running" status (~5-10 minutter)

### Forventede Build Logs:
```
Building...
[+] Building Docker image
[1/8] FROM docker.io/library/node:20
[2/8] COPY package*.json ./
[3/8] RUN npm ci
[4/8] COPY . .
[5/8] RUN npm run build
[6/8] EXPOSE 7860
[7/8] CMD ["npm", "start"]
[8/8] Running...
```

### Space Status Indicator:
- 🔵 **Building** - Docker bygger (5-10 min)
- 🟢 **Running** - Backend kører! ✅
- 🔴 **Runtime Error** - Check logs for fejl
- 🟡 **Sleeping** - Space er paused (klik for at wake up)

---

## 🧪 STEP 3: TEST BACKEND

### Når Space viser "Running" status:

#### Test 1: Health Check
```bash
curl https://kraft102-widgetdc-cortex.hf.space/health
```

**Forventet svar:**
```json
{
  "status": "ok",
  "timestamp": "2025-12-12T11:00:00.000Z",
  "uptime": 123.45
}
```

#### Test 2: API Status
```bash
curl https://kraft102-widgetdc-cortex.hf.space/api/status
```

#### Test 3: I Browser
Åbn: https://kraft102-widgetdc-cortex.hf.space/

Du burde se backend response (ikke 404)

---

## 🎨 STEP 4: DEPLOY FRONTEND

### Option A: Netlify (ANBEFALET - Gratis & Hurtig)

```bash
# Install Netlify CLI
npm install -g netlify-cli

# Login til Netlify
netlify login

# Build frontend
cd apps/matrix-frontend
npm run build

# Deploy
netlify deploy --prod --dir=dist

# Note URL som netlify returnerer (f.eks. https://widgetdc.netlify.app)
```

### Option B: Vercel

```bash
# Install Vercel CLI
npm install -g vercel

# Login
vercel login

# Deploy (fra matrix-frontend dir)
cd apps/matrix-frontend
vercel --prod
```

### Option C: Separat HuggingFace Space

```bash
# Opret ny Space for frontend
python -c "from huggingface_hub import create_repo; create_repo('Kraft102/widgetdc-frontend', repo_type='space', space_sdk='static')"

# Build frontend
cd apps/matrix-frontend
npm run build

# Upload
python -c "from huggingface_hub import HfApi; api = HfApi(); api.upload_folder(folder_path='dist', repo_id='Kraft102/widgetdc-frontend', repo_type='space')"
```

---

## 🔗 STEP 5: CONNECT FRONTEND ↔ BACKEND

### Update Frontend Configuration

Opret/opdater `apps/matrix-frontend/.env.production`:

```bash
VITE_API_URL=https://kraft102-widgetdc-cortex.hf.space
VITE_WS_URL=wss://kraft102-widgetdc-cortex.hf.space
VITE_BACKEND_URL=https://kraft102-widgetdc-cortex.hf.space
```

### Rebuild & Redeploy Frontend

```bash
cd apps/matrix-frontend
npm run build
# Deploy igen til chosen platform (netlify/vercel/hf)
```

---

## ✅ STEP 6: END-TO-END VERIFICATION

### Checklist:

- [ ] Backend Space shows "Running" status
- [ ] Health endpoint returns 200 OK
- [ ] All environment variables added
- [ ] Database connections working
- [ ] Frontend deployed
- [ ] Frontend loads in browser
- [ ] Frontend connects to backend
- [ ] No console errors
- [ ] Widgets render correctly
- [ ] Backend logs show no errors

---

## 🚨 TROUBLESHOOTING

### Problem: "Runtime Error" Status

**Løsning:**
1. Check Logs tab
2. Look for missing environment variables
3. Verify database connection strings
4. Check for port conflicts (should be 7860)

### Problem: "Connection Refused"

**Løsning:**
1. Verify Space is "Running" (not "Building" or "Sleeping")
2. Check CORS settings
3. Verify API URL format

###  Problem: Database Connection Errors

**Løsning:**
1. Verify all database credentials
2. Check database is accessible from internet
3. Whitelist HuggingFace IPs if needed
4. Test connection locally first

### Problem: Frontend Can't Connect

**Løsning:**
1. Check `.env.production` variables
2. Verify backend CORS allows frontend domain
3. Check browser console for errors
4. Test API endpoint directly with curl

---

## 📱 MONITORING

### View Space Status:
```bash
python -c "from huggingface_hub import HfApi; api = HfApi(); info = api.repo_info('Kraft102/widgetdc-cortex', repo_type='space'); print(f'Status: {info}')

"
```

### View Logs:
https://huggingface.co/spaces/Kraft102/widgetdc-cortex/logs

### Restart Space:
Settings → Factory Reboot

---

## 🎯 QUICK START COMMANDS

### Check hvis Space er live:
```bash
curl -I https://kraft102-widgetdc-cortex.hf.space/health
```

### Test WebSocket:
```javascript
const ws = new WebSocket('wss://kraft102-widgetdc-cortex.hf.space');
ws.onopen = () => console.log('Connected!');
```

### Deploy Frontend til Netlify:
```bash
cd apps/matrix-frontend && npm run build && netlify deploy --prod --dir=dist
```

---

## 📞 NÆSTE SKRIDT

### RIGHT NOW:
1. ✅ Gå til https://huggingface.co/spaces/Kraft102/widgetdc-cortex/settings
2. ✅ Add ALLE environment variables (især API keys)
3. ✅ Vent på build completion (~5-10 min)
4. ✅ Test health endpoint

### THEN:
5. ✅ Deploy frontend (Netlify anbefalet)
6. ✅ Configure frontend environment
7. ✅ Test complete flow
8. ✅ You're LIVE! 🎉

---

**Du er 90% færdig!** 🚀  
Fortæl mig når environment variables er tilføjet!