DEPLOYMENT.md

# 🚀 Deployment Guide

This guide covers deploying the EU AI Act Compliance Suite for the MCP 1st Birthday Hackathon.

## 📋 Table of Contents

- [Deployment Options](#deployment-options)
- [Hugging Face Spaces (Recommended)](#hugging-face-spaces-recommended)
- [Manual Deployment](#manual-deployment)
- [GitHub Actions CI/CD](#github-actions-cicd)
- [Environment Variables](#environment-variables)
- [Hackathon Submission Checklist](#hackathon-submission-checklist)

---

## 🎯 Deployment Options

| Option | Best For | Difficulty |
|--------|----------|------------|
| **Hugging Face Spaces** | Hackathon submission, public demos | ⭐ Easy |
| **Docker** | Self-hosted, production | ⭐⭐ Medium |
| **Local Development** | Testing, development | ⭐ Easy |

---

## 🤗 Hugging Face Spaces (Recommended)

The easiest way to deploy for the hackathon is using **Hugging Face Spaces**.

### Method 1: Automated Deployment (GitHub Actions)

1. **Fork this repository** to your GitHub account

2. **Add GitHub Secrets:**
   - Go to your repo → Settings → Secrets and variables → Actions
   - Add `HF_TOKEN`: Your Hugging Face token with write access
   
   ```bash
   # Get your HF token from: https://huggingface.co/settings/tokens
   # Required scopes: write access to spaces
   ```

3. **Join the Hackathon Organization:**
   - Go to [MCP-1st-Birthday](https://huggingface.co/MCP-1st-Birthday)
   - Click "Request to join this org"
   - Wait for approval

4. **Trigger Deployment:**
   - Push to `main` branch (auto-deploys on changes to `spaces/` directory)
   - Or manually trigger via GitHub Actions → "Deploy to Hugging Face Spaces" → "Run workflow"

5. **Configure Space Secrets:**
   - Go to your Space settings: `https://huggingface.co/spaces/MCP-1st-Birthday/eu-ai-act-compliance/settings`
   - Add secrets:
     - `XAI_API_KEY` (required) - Get from [x.ai](https://x.ai/)
     - `TAVILY_API_KEY` (optional) - Get from [tavily.com](https://app.tavily.com/)

### Method 2: Manual Upload

1. **Create a new Space:**
   ```bash
   # Install huggingface_hub
   pip install huggingface_hub
   
   # Login
   huggingface-cli login
   
   # Create space
   huggingface-cli repo create eu-ai-act-compliance --type space --space-sdk gradio
   ```

2. **Upload files:**
   ```bash
   cd spaces/eu-ai-act-compliance
   
   # Clone the space
   git clone https://huggingface.co/spaces/YOUR_USERNAME/eu-ai-act-compliance
   
   # Copy files
   cp -r . eu-ai-act-compliance/
   
   # Push
   cd eu-ai-act-compliance
   git add .
   git commit -m "Initial deployment"
   git push
   ```

3. **Transfer to hackathon org** (for submission):
   - Go to Space Settings → Transfer
   - Transfer to `MCP-1st-Birthday` organization

### Method 3: Using the Deploy Script

```bash
# Run the deployment script
./scripts/deploy-hf.sh

# With custom org/name
./scripts/deploy-hf.sh --org MCP-1st-Birthday --name eu-ai-act-compliance
```

---

## 🐳 Docker Deployment

### Build and Run

```bash
# Build the image
docker build -t eu-ai-act-compliance -f Dockerfile .

# Run with environment variables
docker run -p 7860:7860 \
  -e XAI_API_KEY=your-key \
  -e TAVILY_API_KEY=your-key \
  eu-ai-act-compliance
```

### Docker Compose

```yaml
version: '3.8'
services:
  eu-ai-act-agent:
    build: .
    ports:
      - "7860:7860"
    environment:
      - XAI_API_KEY=${XAI_API_KEY}
      - TAVILY_API_KEY=${TAVILY_API_KEY}
    restart: unless-stopped
```

---

## 🔧 Manual Deployment

### Prerequisites

- Node.js 18+
- Python 3.9+
- pnpm 8+

### Steps

```bash
# 1. Clone the repository
git clone https://github.com/your-org/eu-ai-act-compliance.git
cd eu-ai-act-compliance

# 2. Install dependencies
pnpm install

# 3. Set up environment variables
cp .env.example .env
# Edit .env and add your API keys

# 4. Build the MCP server
pnpm --filter @eu-ai-act/mcp-server build

# 5. Start the agent (API + Gradio)
cd apps/eu-ai-act-agent
./start.sh
```

### Production Mode

```bash
# Build everything
pnpm build

# Start in production
cd apps/eu-ai-act-agent
NODE_ENV=production node dist/server.js &
python src/gradio_app.py
```

---

## 🔄 GitHub Actions CI/CD

### Workflows

| Workflow | Trigger | Purpose |
|----------|---------|---------|
| `ci.yml` | Push/PR | Lint, typecheck, build |
| `deploy-hf-space.yml` | Push to main + `spaces/` changes | Deploy to HF Spaces |

### Required Secrets

| Secret | Required | Description |
|--------|----------|-------------|
| `HF_TOKEN` | Yes | Hugging Face token with write access |

### Manual Deployment Trigger

1. Go to Actions → "Deploy to Hugging Face Spaces"
2. Click "Run workflow"
3. Select branch and environment
4. Click "Run workflow"

---

## 🔐 Environment Variables

### Required

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `XAI_API_KEY` | xAI API key for Grok model | [console.x.ai](https://console.x.ai/) |

### Optional

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `TAVILY_API_KEY` | Tavily API for web research | [app.tavily.com](https://app.tavily.com/) |
| `PORT` | API server port (default: 3001) | - |

### Setting Secrets in Hugging Face Spaces

1. Go to your Space: `https://huggingface.co/spaces/ORG/SPACE_NAME`
2. Click ⚙️ Settings
3. Scroll to "Repository secrets"
4. Add each secret:
   - Name: `XAI_API_KEY`
   - Value: Your API key
   - Click "Add"

---

## ✅ Hackathon Submission Checklist

### Before Submission (Nov 30, 2025 11:59 PM UTC)

- [ ] **Join the organization**: [Request to join MCP-1st-Birthday](https://huggingface.co/MCP-1st-Birthday)
- [ ] **Deploy your Space**: Make sure it's running and accessible
- [ ] **Configure secrets**: Add `XAI_API_KEY` (and optionally `TAVILY_API_KEY`)
- [ ] **Test the demo**: Verify all features work

### README Requirements

Your Space README must include:

- [ ] **Hackathon tags** in frontmatter:
  ```yaml
  tags:
    - mcp
    - agents
    - track-1-mcp-servers
    - track-2-agentic-applications
  ```

- [ ] **Social media link**: Share your project and include the link
  ```markdown
  [🐦 Twitter Post](https://twitter.com/your-post-link)
  ```

### Track Tags

| Track | Tags |
|-------|------|
| Track 1: Building MCP | `track-1-mcp-servers`, `mcp` |
| Track 2: MCP in Action | `track-2-agentic-applications`, `agents` |

### Social Media Post Template

```
🇪🇺 Excited to share my #MCPHackathon submission!

EU AI Act Compliance Agent - AI-powered compliance assessment with MCP tools

✅ Discover organization profiles
✅ Classify AI systems by risk
✅ Generate compliance documentation

Try it: [HF Space Link]

#MCP #AIAct #Gradio @huggingface
```

---

## 🔍 Troubleshooting

### Space Not Building

1. Check `requirements.txt` for valid packages
2. Verify Python version compatibility
3. Check build logs in Space settings

### API Key Errors

1. Verify secrets are set in Space settings
2. Check secret names match exactly (case-sensitive)
3. Ensure API keys are valid and have required permissions

### Deployment Failing

1. Check GitHub Actions logs
2. Verify `HF_TOKEN` has write access
3. Ensure you're a member of the target organization

### Space Sleeping

Free HF Spaces sleep after inactivity. To wake:
1. Visit the Space URL
2. Wait for it to build/start
3. Consider upgrading for persistent uptime

---

## 📞 Support

- **Hackathon Discord**: [#agents-mcp-hackathon-winter25🏆](https://discord.gg/huggingface)
- **GitHub Issues**: [Create an issue](https://github.com/your-org/eu-ai-act-compliance/issues)
- **Email**: gradio-team@huggingface.co

---

## 📚 Additional Resources

- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Gradio Deployment Guide](https://www.gradio.app/guides/sharing-your-app)
- [MCP Course](https://huggingface.co/learn/mcp-course)
- [Hackathon Page](https://huggingface.co/MCP-1st-Birthday)

---

<div align="center">

**Good luck with your submission! 🎂**

</div>