AegisGitea-MCP/DEPLOYMENT.md

# AegisGitea MCP Deployment Guide

This guide walks you through deploying AegisGitea MCP in a production environment.

---

## Prerequisites

1. **Self-hosted Gitea instance** (running and accessible)
2. **Docker and Docker Compose** installed on your server
3. **Reverse proxy** (Traefik, Caddy, or Nginx) for TLS termination
4. **Bot user account** created in Gitea with read-only access

---

## Step 1: Create Gitea Bot User

1. Log into your Gitea instance as an admin
2. Create a new user account (e.g., `aegis-bot`)
3. **Important**: Do NOT grant admin privileges to this user
4. Generate an access token:
   - Go to Settings > Applications
   - Generate new token with `read:repository` scope only
   - Save the token securely (you'll need it in Step 3)

---

## Step 2: Grant Repository Access

The bot user can only see repositories where it has been explicitly granted access:

### Method 1: Add as Collaborator (for individual repos)

1. Go to repository Settings > Collaborators
2. Add `aegis-bot` user
3. Set permission to **Read** only

### Method 2: Add to Organization Team (for multiple repos)

1. Create an organization team (e.g., "AI Reviewers")
2. Add `aegis-bot` to the team
3. Grant team **Read** access to desired repositories

**Result**: Only repositories where the bot is a collaborator are AI-visible.

---

## Step 3: Configure AegisGitea MCP

Clone the repository and set up environment:

```bash
# Clone repository
git clone https://your-gitea.com/your-org/AegisGitea-MCP.git
cd AegisGitea-MCP

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env
```

### Required Configuration

```bash
# Gitea instance URL (must be accessible from Docker container)
GITEA_URL=https://gitea.example.com

# Bot user token from Step 1
GITEA_TOKEN=your-bot-token-here

# MCP server configuration
MCP_HOST=0.0.0.0
MCP_PORT=8080

# Logging
LOG_LEVEL=INFO
AUDIT_LOG_PATH=/var/log/aegis-mcp/audit.log
```

### Optional Security Configuration

```bash
# File size limit (bytes)
MAX_FILE_SIZE_BYTES=1048576  # 1MB

# API request timeout (seconds)
REQUEST_TIMEOUT_SECONDS=30

# Rate limiting (requests per minute)
RATE_LIMIT_PER_MINUTE=60
```

---

## Step 4: Deploy with Docker Compose

```bash
# Build and start container
docker-compose up -d

# Check logs
docker-compose logs -f aegis-mcp

# Verify health
curl http://localhost:8080/health
```

Expected output:
```json
{"status": "healthy"}
```

---

## Step 5: Configure Reverse Proxy

**Never expose the MCP server directly to the internet without TLS.**

### Example: Traefik

```yaml
# docker-compose.yml (add to aegis-mcp service)
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.aegis-mcp.rule=Host(`mcp.example.com`)"
  - "traefik.http.routers.aegis-mcp.entrypoints=websecure"
  - "traefik.http.routers.aegis-mcp.tls.certresolver=letsencrypt"
  - "traefik.http.services.aegis-mcp.loadbalancer.server.port=8080"
```

### Example: Caddy

```caddyfile
# Caddyfile
mcp.example.com {
    reverse_proxy aegis-mcp:8080
}
```

### Example: Nginx

```nginx
# /etc/nginx/sites-available/aegis-mcp
server {
    listen 443 ssl http2;
    server_name mcp.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # SSE support
        proxy_buffering off;
        proxy_cache off;
        proxy_set_header Connection '';
        chunked_transfer_encoding off;
    }
}
```

---

## Step 6: Register with ChatGPT

1. Go to ChatGPT Settings > MCP Servers
2. Add new MCP server:
   - **Name**: AegisGitea MCP
   - **URL**: `https://mcp.example.com`
   - **Type**: SSE (Server-Sent Events)

3. Test connection by asking ChatGPT:
   ```
   List my Gitea repositories
   ```

---

## Verification Checklist

- [ ] Bot user created in Gitea
- [ ] Bot user has read-only token
- [ ] Bot user added as collaborator to desired repositories
- [ ] `.env` file configured with correct values
- [ ] Docker container running and healthy
- [ ] Reverse proxy configured with TLS
- [ ] MCP server accessible via HTTPS
- [ ] ChatGPT successfully connects to MCP server
- [ ] Audit logs are being written

---

## Security Best Practices

### 1. Token Management

- **Rotate tokens quarterly** or when team members leave
- Store tokens in a secrets manager (Vault, 1Password, etc.)
- Never commit tokens to version control

### 2. Network Security

- Use a firewall to restrict MCP server access
- Only allow HTTPS connections (port 443)
- Consider VPN or IP allowlisting for extra security

### 3. Monitoring

Monitor audit logs for unexpected activity:

```bash
# View recent audit events
docker-compose exec aegis-mcp tail -f /var/log/aegis-mcp/audit.log

# Search for specific repository access
docker-compose exec aegis-mcp grep "repository-name" /var/log/aegis-mcp/audit.log
```

### 4. Access Control

- Review bot user permissions monthly
- Remove access from archived repositories
- Audit which repositories are AI-visible

### 5. Updates

```bash
# Pull latest changes
git pull

# Rebuild container
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

---

## Troubleshooting

### Container won't start

```bash
# Check logs for errors
docker-compose logs aegis-mcp

# Verify environment variables
docker-compose config
```

### Authentication errors

```bash
# Test Gitea connection manually
curl -H "Authorization: token YOUR_TOKEN" https://gitea.example.com/api/v1/user

# If 401: Token is invalid or expired
# If 403: Token lacks necessary permissions
```

### ChatGPT can't connect

1. Verify reverse proxy is working:
   ```bash
   curl https://mcp.example.com/health
   ```

2. Check firewall rules:
   ```bash
   sudo ufw status
   ```

3. Review reverse proxy logs

### No repositories visible

- Verify bot user has been added as collaborator
- Check repository is not archived
- Confirm bot user permissions in Gitea UI

---

## Rollback Plan

If something goes wrong:

```bash
# Stop container
docker-compose down

# Remove container and volumes
docker-compose down -v

# Restore previous configuration
git checkout HEAD~1 .env

# Restart
docker-compose up -d
```

To completely disable AI access:

1. Remove bot user token in Gitea
2. Stop MCP container: `docker-compose down`

**The system is designed to be reversible.**

---

## Production Checklist

Before going live:

- [ ] All sensitive data in `.env` (not hardcoded)
- [ ] TLS configured and tested
- [ ] Audit logging enabled and accessible
- [ ] Resource limits set in docker-compose.yml
- [ ] Monitoring and alerting configured
- [ ] Backup strategy for audit logs
- [ ] Incident response plan documented
- [ ] Team trained on emergency procedures

---

## Support

For deployment issues:

1. Check logs: `docker-compose logs -f`
2. Review audit logs for access patterns
3. Open an issue in Gitea repository
4. Include sanitized logs (remove tokens!)

---

**Remember**: This system prioritizes security over convenience. When in doubt, restrict access first and expand gradually.