Hybrid Deployment Architecture

This document describes the recommended hybrid deployment architecture for AI Security Gateway, which combines native Go binaries with Dockerized frontend for optimal performance and ease of deployment.

🎯 Hybrid Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     User's Machine                           │
│                                                               │
│  ┌────────────────────────┐      ┌────────────────────────┐ │
│  │  Native Go Backend     │      │  Docker Frontend       │ │
│  │  (unified-admin)       │◄─────┤  (Nginx + Vue.js)     │ │
│  │  Port: 8080            │      │  Port: 80              │ │
│  │                        │      │                        │ │
│  │  • REST API            │      │  • Serves Vue.js app   │ │
│  │  • WebSocket           │      │  • Proxies to backend  │ │
│  │  • Proxy Management    │      │  • Volume-mapped .env  │ │
│  │  • SQLite Database     │      │                        │ │
│  └────────────────────────┘      └────────────────────────┘ │
│                                                               │
└─────────────────────────────────────────────────────────────┘

🚀 Why This Architecture?

Native Go Backend

Advantages:

• ✅ Maximum Performance - No container overhead
• ✅ Direct System Access - Can bind to any port without port mapping
• ✅ Easier Debugging - Direct process access, native logging
• ✅ Lower Resource Usage - ~50MB RAM vs. container runtime overhead
• ✅ Simpler Deployment - Single binary, no Docker needed for core functionality
• ✅ Better for Proxy Mode - Dynamic port allocation works seamlessly

Why Not Docker for Backend?

• MCP/LLM proxies need to bind to dynamic ports (configured by user)
• Docker port mapping is complex for dynamic proxy instances
• Native binaries provide better performance for security scanning
• No need for container isolation for the backend API
• I didnt feel like spending too much time for something Im not gonna use (:

Dockerized Frontend

Advantages:

• ✅ Consistent Environment - Node.js + Nginx versions locked
• ✅ Easy Updates - Pull new image, restart container
• ✅ No Node.js Installation - Users don't need npm/node on host
• ✅ Configuration Flexibility - Volume-mapped .env for runtime changes
• ✅ Portable - Same image works across all platforms
• ✅ Isolation - Frontend dependencies isolated from host

Why Docker for Frontend?

• Vue.js apps benefit from consistent build environment
• Nginx configuration can be templated with environment variables
• Frontend doesn't need host system access
• Users can edit .env without rebuilding images

📦 Release Package Structure

Each release package contains:

ai-security-gateway-{platform}/
├── unified-admin-{platform}              # Native Go binary
├── frontend/
│   ├── dist/                              # Pre-built Vue.js app
│   ├── Dockerfile.frontend                # Frontend Docker image definition
│   └── .env                               # Configuration (volume-mapped)
├── docker-compose.frontend.yml            # Deployment orchestration
├── configs/
│   └── config.example.yaml                # Backend configuration template
├── policies/
│   ├── critical-security.json
│   ├── standard-security.json
│   ├── mcp-advanced-security.json
│   └── ... (7 policy files total)
├── .env.example                           # Environment variables template
├── LICENSE
├── README.md                              # Full documentation
└── QUICKSTART.md                          # Getting started guide

🛠️ Building Release Packages

For Maintainers

# Build complete release packages for all platforms
make release-packages

# Generate SHA256 checksums
make release-checksums

# Output directory: build/packages/
# Files created:
#   - ai-security-gateway-linux-amd64.tar.gz
#   - ai-security-gateway-linux-arm64.tar.gz
#   - ai-security-gateway-darwin-amd64.tar.gz
#   - ai-security-gateway-darwin-arm64.tar.gz
#   - ai-security-gateway-windows-amd64.zip
#   - SHA256SUMS

What make release-packages Does

1. Builds Go binaries for all platforms (Linux, macOS, Windows, amd64/arm64)
2. Builds Vue.js frontend (npm run build → frontend/dist/)
3. Creates package structure for each platform
4. Copies all necessary files:
   • Binary
   • Frontend dist
   • Docker configuration (Dockerfile, docker-compose)
   • Configs and policies
   • Documentation
5. Generates QUICKSTART.md with platform-specific instructions
6. Compresses packages (.tar.gz for Unix, .zip for Windows)

👥 User Deployment Workflow

Step 1: Download Release Package

# Linux AMD64 (not available in public beta)
curl -LO https://github.com/syphon1c/ai-security-gateway/releases/download/v2026.x.x/ai-security-gateway-linux-amd64.tar.gz
tar -xzf ai-security-gateway-linux-amd64.tar.gz
cd ai-security-gateway-linux-amd64

# macOS Apple Silicon (M1/M2/M3) (not available in public beta)
curl -LO https://github.com/syphon1c/ai-security-gateway/releases/download/v2026.x.x/ai-security-gateway-darwin-arm64.tar.gz
tar -xzf ai-security-gateway-darwin-arm64.tar.gz
cd ai-security-gateway-darwin-arm64

# Windows
# Download ai-security-gateway-windows-amd64.zip
# Extract to folder

Step 2: Start Native Backend

# Linux/macOS
chmod +x unified-admin-*
./unified-admin-*

# Windows
.\unified-admin-windows-amd64.exe

Backend starts on http://localhost:8080 with embedded web UI.

Step 3: Configure Frontend (Optional)

Edit frontend/.env to customize:

# Point to native backend (default works for local development)
BACKEND_HOST=host.docker.internal:8080
VITE_API_BASE_URL=http://localhost:8080

Important: Changes to .env take effect immediately—no rebuild needed!

Step 4: Start Frontend Docker Container

docker-compose -f docker-compose.frontend.yml up -d

Access web interface at http://localhost

Step 5: Access Application

• Via Frontend Container: http://localhost (recommended for production)
• Via Backend Directly: http://localhost:8080 (development/testing)

🔧 Hybrid Configuration

Backend Configuration

Method 1: Environment Variables

export JWT_SECRET=your-secret-key
export DATABASE_PATH=./data/ai-gateway.db
./unified-admin

Method 2: Config File

cp configs/config.example.yaml configs/config.yaml
# Edit configs/config.yaml
./unified-admin

Hybrid Frontend Configuration

Edit frontend/.env (volume-mapped, no rebuild required):

# Local development (backend on host)
BACKEND_HOST=host.docker.internal:8080
VITE_API_BASE_URL=http://localhost:8080

# Remote server deployment
BACKEND_HOST=host.docker.internal:8080
VITE_API_BASE_URL=http://server.example.com:8080

# Custom backend port
BACKEND_HOST=host.docker.internal:9090
VITE_API_BASE_URL=http://localhost:9090

Apply changes:

docker-compose -f docker-compose.frontend.yml restart

🌐 Deployment Scenarios

Scenario 1: Local Development (Default)

#  Terminal 1: Start backend
./unified-admin

#  Terminal 2: Start frontend
docker-compose -f docker-compose.frontend.yml up -d

# Access: http://localhost

Configuration: Default .env values work out of the box.

Scenario 2: Remote Server Deployment

# On server (example.com)
./unified-admin

# Edit frontend/.env
BACKEND_HOST=host.docker.internal:8080
VITE_API_BASE_URL=http://example.com:8080

# Start frontend
docker-compose -f docker-compose.frontend.yml up -d

# Access: http://example.com

Scenario 3: Custom Ports

# Start backend on port 9090
./unified-admin --addr :9090

# Edit frontend/.env
BACKEND_HOST=host.docker.internal:9090
VITE_API_BASE_URL=http://localhost:9090

# Start frontend
docker-compose -f docker-compose.frontend.yml up -d

Scenario 4: Backend Only (No Docker)

# Just run the native binary
./unified-admin

# Access embedded web UI: http://localhost:8080

Use case: Quick testing, development, or when Docker isn't available.

🐳 Docker Commands Reference

# Start frontend container
docker-compose -f docker-compose.frontend.yml up -d

# Stop frontend container
docker-compose -f docker-compose.frontend.yml down

# View logs
docker-compose -f docker-compose.frontend.yml logs -f

# Restart after .env changes
docker-compose -f docker-compose.frontend.yml restart

# Rebuild frontend image (after dist changes)
cd frontend
docker build -f Dockerfile.frontend -t ai-security-gateway-frontend:local ..

📊 Resource Usage Comparison

Component	Native	Docker	Savings
Backend	~50MB RAM	~150MB RAM	100MB
Frontend	N/A (requires Node.js)	~30MB RAM	Worth it for consistency
Total	~50MB + Node.js	~180MB	Cleaner for users

🔒 Security Considerations

Backend (Native Binary)

• ✅ No container escape vulnerabilities
• ✅ Direct system authentication
• ✅ Native file permissions
• ⚠️ Ensure binary is from trusted source (verify SHA256)

Frontend (Docker)

• ✅ Isolated from host system
• ✅ Non-root user inside container
• ✅ Read-only volume mounts for config
• ✅ Health checks enabled

Communication

• Backend and frontend communicate via host.docker.internal
• Frontend uses extra_hosts for Docker-to-host connectivity
• JWT tokens for API authentication
• HTTPS recommended for production (use reverse proxy like Traefik/Nginx)

🆘 Troubleshooting

Backend Issues

Problem: Backend won't start

# Check if port 8080 is in use
lsof -i :8080  # macOS/Linux
netstat -ano | findstr :8080  # Windows

# Start on different port
./unified-admin --addr :9090

Problem: Permission denied

chmod +x unified-admin-*

Frontend Issues

Problem: Can't connect to backend

# Edit frontend/.env
BACKEND_HOST=host.docker.internal:8080
VITE_API_BASE_URL=http://localhost:8080

# Restart container
docker-compose -f docker-compose.frontend.yml restart

Problem: Docker container fails to start

# Check if port 80 is available
sudo lsof -i :80  # macOS/Linux

# View logs
docker-compose -f docker-compose.frontend.yml logs

# Try different port (edit docker-compose.frontend.yml)
ports:
  - "8888:80"

Network Issues

Problem: CORS errors in browser console

# Backend must allow frontend origin
# Edit configs/config.yaml or set environment variable:
export CORS_ALLOWED_ORIGINS="http://localhost,http://localhost:80"
./unified-admin

📚 Hybrid Deployment Resources

• Architecture Overview
• API Documentation
• Configuration Guide
• Docker Deployment (Full Stack)
• Security Audit Guide

🎯 Recommended Setup for Production

# 1. Use systemd (Linux) or launchd (macOS) for backend
sudo systemctl enable ai-security-gateway

# 2. Use Docker for frontend with restart policy
docker-compose -f docker-compose.frontend.yml up -d

# 3. Use reverse proxy for HTTPS
# Example with Nginx:
server {
    listen 443 ssl;
    server_name gateway.example.com;
    
    location / {
        proxy_pass http://localhost:80;  # Frontend container
    }
}

# 4. Configure firewall
sudo ufw allow 80/tcp   # Frontend
sudo ufw allow 443/tcp  # HTTPS
# Do NOT expose 8080 (backend) to external traffic

💡 Key Advantages of This Approach

1. Best of Both Worlds

   • Native performance for backend
   • Containerized consistency for frontend

2. User-Friendly

   • No Docker required for core functionality
   • Optional Docker for enhanced frontend experience

3. Easy Configuration

   • Volume-mapped .env for instant changes
   • No image rebuilds needed

4. Flexible Deployment

   • Works in dev, staging, production
   • Scales to enterprise needs

5. Lower Barrier to Entry

   • Users without Docker can still use the app
   • Docker users get enhanced experience

🔄 Migration from Full Docker Setup

If you were previously using the full Docker setup (backend + frontend), migrate to hybrid:

# 1. Stop old containers
docker-compose down

# 2. Extract data from Docker volume
docker cp ai-security-gateway-backend:/app/data ./data

# 3. Start native backend
./unified-admin

# 4. Start new frontend container
docker-compose -f docker-compose.frontend.yml up -d

Your data and configuration are preserved.