.
This commit is contained in:
343
DEPLOYMENT.md
Normal file
343
DEPLOYMENT.md
Normal file
@@ -0,0 +1,343 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user