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:

# 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

# 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

# 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

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

{"status": "healthy"}

---

Step 5: Configure Reverse Proxy

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

Example: Traefik

# 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
mcp.example.com {
    reverse_proxy aegis-mcp:8080
}

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

# 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

# Pull latest changes
git pull

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

---

Troubleshooting

Container won't start

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

# Verify environment variables
docker-compose config

Authentication errors

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

   curl https://mcp.example.com/health
   

2. Check firewall rules:

   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:

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