Spaces:

NLarchive
/

my-webapp-hf

Sleeping

App Files Files Community

my-webapp-hf / public /INSTALLATION.md

Deminiko

chore: Update Gemini model to gemini-2.5-flash-lite and guard fallback; update installation docs

4d5737b about 1 month ago

preview code

raw

history blame contribute delete

8.89 kB

AI Agent - Installation & Deployment Guide

Local Development
Environment Setup
HF Spaces Deployment
API Configuration
Troubleshooting

Local Development

Prerequisites

Node.js 18 or higher
npm or yarn
Git
Text editor (VS Code recommended)

Step 1: Install Dependencies

cd public
npm install

This installs:

Express.js (web server)
@google/generative-ai (Gemini SDK)
axios (HTTP client)
cors & body-parser (middleware)
dotenv (environment management)

Step 2: Configure Environment

Copy .env.example to .env:

cp .env.example .env

Edit .env with your API keys:

GEMINI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...
HF_TOKEN=hf_...
GITHUB_REPO=YourUsername/repo-name
GITHUB_OWNER=YourUsername

Step 3: Start Development Server

npm run dev

Output:

[INFO] ... - Server started on port 3000

Visit: http://localhost:3000

Step 4: Test the App

Chat: Open "💬 Chat" tab and try /help command
Scanner: Click "🔍 Run Manual Scan"
Project: View "📁 Project" structure

Environment Setup

Getting API Keys

1. Google Gemini API Key

1. Go: https://makersuite.google.com/app/apikey
2. Click "Create API key"
3. Copy the key
4. Paste into .env GEMINI_API_KEY=

2. GitHub Authentication (Choose One)

Option A: Personal Access Token (Simple)

1. Go: https://github.com/settings/tokens
2. Click "Generate new token" → "Generate new token (classic)"
3. Name: "ai-agent-hf"
4. Select scopes:
   ✓ repo (full access)
   ✓ workflow (update GitHub Actions)
   ✓ gist (optional)
5. Generate and copy
6. Paste into .env GITHUB_TOKEN=

Option B: GitHub App (Recommended for Production)

1. Go: https://github.com/settings/apps
2. Click "New GitHub App"
3. Configure:
   - Name: "AI Agent HF"
   - Homepage URL: https://huggingface.co/spaces/YourUsername/your-space
   - Webhook URL: Leave empty
   - Permissions:
     ✓ Repository permissions → Contents: Read & write
     ✓ Repository permissions → Issues: Read & write
     ✓ Repository permissions → Pull requests: Read & write
     ✓ Repository permissions → Actions: Read & write
     ✓ Repository permissions → Metadata: Read
4. Generate private key (download .pem file)
5. Install app on your repository
6. Get installation ID from app settings
7. Convert private key to base64:
   ```bash
   # On Windows PowerShell
   [Convert]::ToBase64String([IO.File]::ReadAllBytes("path\to\private-key.pem"))

Configure .env:

GH_APP_ID=your_app_id
GH_APP_PRIVATE_KEY_B64=your_base64_private_key
GH_APP_INSTALLATION_ID=your_installation_id

Test authentication:
```
cd scripts
node test-github-auth.js
```


#### 3. Hugging Face Token

Go: https://huggingface.co/settings/tokens
Create new token
Name: "ai-agent"
Type: "read"
Copy token
Paste into .env HF_TOKEN=


### Environment Variables Reference

| Variable | Required | Example | Description |
|----------|----------|---------|-------------|
| GEMINI_API_KEY | ✓ | sk-... | Google Gemini API key |
| GITHUB_TOKEN | ✓ | ghp_... | GitHub Personal Access Token |
| HF_TOKEN | ✓ | hf_... | Hugging Face API token |
| GITHUB_REPO | ✓ | user/repo | GitHub repository |
| GITHUB_OWNER | ✓ | user | GitHub username |
| GITHUB_BRANCH | ✓ | main | Default branch |
| SCAN_INTERVAL | - | 3600000 | Scanner interval (ms) |
| ENABLE_AUTO_FIX | - | true | Enable auto-fixing |
| AUTO_COMMIT | - | false | Auto-commit fixes |
| PORT | - | 3000 | Server port |
| LOG_LEVEL | - | info | Logging level |

## HF Spaces Deployment

### Prerequisites
- HF Space created on Hugging Face
- GitHub repository connected
- All environment variables set in GitHub Secrets

### Step 1: Update Dockerfile

The `Dockerfile` is already configured for HF Spaces (port 7860).

Verify it exists in project root:

D:\mcp\mcp-2hackathon\Dockerfile


### Step 2: Update GitHub Actions Workflow

Update `.github/workflows/sync-to-hf.yml`:

```yaml
name: Sync to HF Space
on:
  push:
    branches: [main]
    paths:
      - 'public/**'
      - 'Dockerfile'
      - '.github/workflows/sync-to-hf.yml'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Push to HF Space
        run: |
          git remote add hf https://${{ secrets.HF_USERNAME }}:${{ secrets.HF_TOKEN }}@huggingface.co/spaces/${{ secrets.HF_USERNAME }}/${{ secrets.HF_SPACE_NAME }}
          git push hf HEAD:main --force

Step 3: Set GitHub Secrets

In GitHub repo → Settings → Secrets and variables → Actions:

HF_TOKEN
- Value: Your HF token
- Use the token from HF Settings
HF_USERNAME
- Value: Your HF username
- Example: NLarchive
HF_SPACE_NAME
- Value: Your HF Space name
- Example: my-webapp-hf
GEMINI_API_KEY (optional, if using in GitHub Actions)
GITHUB_TOKEN (GitHub provides automatically)

Step 4: Deploy

# Commit and push changes
git add .
git commit -m "feat: add ai agent to hf space"
git push origin main

GitHub Actions will automatically:

Build Docker image
Push to HF Space
Start the service on HF Spaces

Access at: https://huggingface.co/spaces/YourUsername/your-space

API Configuration

Base URL

Local: http://localhost:3000
HF Spaces: https://huggingface.co/spaces/YourUsername/your-space

Authentication

All API calls include Content-Type: application/json header.

Health Check

curl http://localhost:3000/health

Response:

{
  "status": "ok",
  "timestamp": "2024-11-17T...",
  "uptime": 123.45
}

Example: Send Chat Message

# 1. Start conversation
curl -X POST http://localhost:3000/api/chat/start

# Response:
# {
#   "success": true,
#   "sessionId": "session_1234_xyz"
# }

# 2. Send message
curl -X POST http://localhost:3000/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_1234_xyz",
    "message": "What is this project?"
  }'

# Response:
# {
#   "success": true,
#   "response": "Based on your project structure..."
# }

Example: Run Scanner

curl -X POST http://localhost:3000/api/scanner/scan

# Response:
# {
#   "success": true,
#   "report": {
#     "timestamp": "...",
#     "duration": 1234,
#     "issues": [...],
#     "analysis": {...},
#     "recommendations": [...]
#   }
# }

Troubleshooting

Port Already in Use

# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess

# Kill the process
Kill-Process -Id <PID> -Force

API Key Invalid

Error: API key not valid

Solution:

Verify key in .env file
Check key hasn't expired
Test key directly: curl https://generativelanguage.googleapis.com/v1/models/gemini-2.5-flash-lite:generateContent?key=YOUR_KEY

GitHub Connection Failed

Error: Failed to create GitHub issue

Solution:

Verify GITHUB_TOKEN in .env
Check token has repo and issues scope
Verify GITHUB_REPO format: owner/repo

Scanner Not Running

Scan failed: ...

Solution:

Check ENABLE_AUTO_FIX=true in .env
Verify GitHub token and permissions
Check server logs: npm run dev (development mode shows detailed logs)

Slow Responses

Chat timeout or slow responses

Solutions:

Check internet connection
Verify API keys are valid
Increase timeout: Edit src/config/env.js → increase timeouts
Use simpler prompts to reduce processing time

HF Space Build Failing

Check logs:

GitHub → Actions → View workflow run → HF Space build logs

Common issues:

npm install failing: Check package.json syntax
Port 7860 not exposed: Verify Dockerfile EXPOSE 7860
Environment variables missing: Check GitHub Secrets

Local Testing Before Deployment

# 1. Test with Docker locally
docker build -t ai-agent .
docker run -p 3000:7860 \
  -e GEMINI_API_KEY=your_key \
  -e GITHUB_TOKEN=your_token \
  ai-agent

# 2. Access at http://localhost:3000

# 3. Check container logs
docker logs <container_id>

Next Steps

✅ Set up local environment
✅ Configure API keys
✅ Test locally
✅ Deploy to HF Spaces
🔄 Monitor scanner results
🔄 Collect user feedback
🔄 Add custom scanners/commands

Support & Resources

Google Gemini: https://ai.google.dev/
GitHub API: https://docs.github.com/en/rest
HF Spaces: https://huggingface.co/docs/hub/spaces
Node.js: https://nodejs.org/docs/

Last Updated: November 17, 2024

AI Agent - Installation & Deployment Guide

Table of Contents

Local Development

Prerequisites

Step 1: Install Dependencies

Step 2: Configure Environment

Step 3: Start Development Server

Step 4: Test the App

Environment Setup

Getting API Keys

1. Google Gemini API Key

2. GitHub Authentication (Choose One)

Step 3: Set GitHub Secrets

Step 4: Deploy

API Configuration

Base URL

Authentication

Health Check

Example: Send Chat Message

Example: Run Scanner

Troubleshooting

Port Already in Use

API Key Invalid

GitHub Connection Failed

Scanner Not Running

Slow Responses

HF Space Build Failing

Local Testing Before Deployment

Next Steps

Support & Resources