Hugging Face's logo

Spaces:
Kraft102
/
widgettdc-api
Paused

App Files Community
widgettdc-api / docs /HF_COMPLETE_SETUP_GUIDE.md
Kraft102's picture
Kraft102
fix: sql.js Docker/Alpine compatibility layer for PatternMemory and FailureMemory
5a81b95
preview code
|
raw
history blame contribute delete
7.72 kB

🚀 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 

curl https://kraft102-widgetdc-cortex.hf.space/health

Forventet svar:

{
  "status": "ok",
  "timestamp": "2025-12-12T11:00:00.000Z",
  "uptime": 123.45
}

Test 2: API Status 

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) 

# 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 

# 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 

# 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:

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 

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: 

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: 

curl -I https://kraft102-widgetdc-cortex.hf.space/health

Test WebSocket: 

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

Deploy Frontend til Netlify: 

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:

  1. ✅ Deploy frontend (Netlify anbefalet)
  2. ✅ Configure frontend environment
  3. ✅ Test complete flow
  4. ✅ You're LIVE! 🎉

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