Web Server Deployment Guide

This guide covers deploying the AI Security Gateway frontend to traditional web servers (Nginx, Apache) with the API server running as a native binary.

Web Server Architecture Overview

┌─────────────────────────────────────┐
│         Web Server (Port 80/443)    │
│         Nginx / Apache               │
│  ┌─────────────┐  ┌─────────────────┐│
│  │ Static      │  │ Reverse Proxy   ││
│  │ Files       │  │ /api/* -> :8080 ││
│  │ (Vue.js)    │  │ /ws -> :8080    ││
│  └─────────────┘  └─────────────────┘│
└─────────────────┬───────────────────┘
                  │ Proxy requests
┌─────────────────▼───────────────────┐
│    API Server (Port 8080)           │
│    ./unified-admin (Go Binary)      │
│    Native performance, no Docker    │
└─────────────────────────────────────┘

Benefits:

✅ Maximum Performance: Native binary + optimized web server
✅ Production Ready: SSL termination, gzip compression, caching
✅ Scalable: Load balancing, multiple API server instances
✅ Familiar: Standard web server deployment patterns

Nginx Deployment

Step 1: Build and Deploy Frontend

bash

# Clone repository and build frontend
git clone https://github.com/syphon1c/ai-security-gateway.git
cd ai-security-gateway/frontend

# Install dependencies and build
npm install
npm run build

# Deploy to web server
sudo cp -r dist/* /var/www/ai-security-gateway/
sudo chown -R www-data:www-data /var/www/ai-security-gateway/
sudo chmod -R 755 /var/www/ai-security-gateway/

Step 2: Configure Nginx

Create /etc/nginx/sites-available/ai-security-gateway:

nginx

# AI Security Gateway - Nginx Configuration
server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com;  # Replace with your domain

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Frontend static files (Vue.js app)
    location / {
        root /var/www/ai-security-gateway;
        try_files $uri $uri/ /index.html;
        
        # Cache static assets
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
            expires 1y;
            add_header Cache-Control "public, no-transform";
        }
        
        # No cache for HTML files
        location ~* \.(html)$ {
            expires -1;
            add_header Cache-Control "no-cache, no-store, must-revalidate";
        }
    }

    # API reverse proxy
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
        proxy_cache_bypass $http_upgrade;
        
        # Timeouts
        proxy_connect_timeout 10s;
        proxy_send_timeout 10s;
        proxy_read_timeout 10s;
    }

    # WebSocket proxy
    location /ws {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
        
        # WebSocket timeouts
        proxy_read_timeout 86400;
    }

    # Health check for load balancers
    location /health {
        proxy_pass http://127.0.0.1:8080/api/v1/health;
        access_log off;
    }

    # Logging
    access_log /var/log/nginx/ai-gateway-access.log;
    error_log /var/log/nginx/ai-gateway-error.log;
}

Step 3: SSL Configuration (Production)

Add SSL configuration for production:

bash

# Install Certbot for Let's Encrypt SSL
sudo apt-get install certbot python3-certbot-nginx

# Obtain SSL certificate
sudo certbot --nginx -d your-domain.com

# This will modify your nginx config to add SSL

The SSL-enabled config will look like:

nginx

# SSL Configuration (added by Certbot)
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name your-domain.com;
    
    # SSL certificates (managed by Certbot)
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # ... rest of configuration same as above ...
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

Step 4: Enable and Test Nginx

bash

# Enable site
sudo ln -s /etc/nginx/sites-available/ai-security-gateway /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

# Enable auto-start
sudo systemctl enable nginx

Apache Deployment

Step 1: Deploy Frontend Files

bash

# Build frontend (same as Nginx)
cd ai-security-gateway/frontend
npm run build

# Deploy to Apache document root
sudo cp -r dist/* /var/www/html/ai-security-gateway/
sudo chown -R www-data:www-data /var/www/html/ai-security-gateway/
sudo chmod -R 755 /var/www/html/ai-security-gateway/

Step 2: Configure Apache Virtual Host

Create /etc/apache2/sites-available/ai-security-gateway.conf:

apache

# AI Security Gateway - Apache Configuration
<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/html/ai-security-gateway

    # Security headers
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-Content-Type-Options "nosniff"
    Header always set X-XSS-Protection "1; mode=block"
    Header always set Referrer-Policy "strict-origin-when-cross-origin"

    # Frontend static files (Vue.js SPA)
    <Directory "/var/www/html/ai-security-gateway">
        AllowOverride All
        Require all granted
        
        # Handle Vue.js routing
        RewriteEngine On
        RewriteBase /
        
        # Handle client-side routing
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteCond %{REQUEST_URI} !^/api/
        RewriteCond %{REQUEST_URI} !^/ws
        RewriteRule . /index.html [L]
    </Directory>

    # Cache static assets
    <LocationMatch "\.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$">
        ExpiresActive On
        ExpiresDefault "access plus 1 year"
        Header set Cache-Control "public, no-transform"
    </LocationMatch>

    # No cache for HTML
    <LocationMatch "\.html$">
        ExpiresActive On
        ExpiresDefault "access minus 1 second"
        Header set Cache-Control "no-cache, no-store, must-revalidate"
    </LocationMatch>

    # API reverse proxy
    ProxyPreserveHost On
    ProxyRequests Off
    
    # API endpoints
    ProxyPass /api/ http://127.0.0.1:8080/api/
    ProxyPassReverse /api/ http://127.0.0.1:8080/api/
    
    # WebSocket proxy
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/ws$ "ws://127.0.0.1:8080/ws" [P,L]
    
    # Health check
    ProxyPass /health http://127.0.0.1:8080/api/v1/health
    ProxyPassReverse /health http://127.0.0.1:8080/api/v1/health

    # Logging
    ErrorLog ${APACHE_LOG_DIR}/ai-gateway-error.log
    CustomLog ${APACHE_LOG_DIR}/ai-gateway-access.log combined
</VirtualHost>

Step 3: Enable Required Apache Modules

bash

# Enable required modules
sudo a2enmod rewrite
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_wstunnel
sudo a2enmod headers
sudo a2enmod expires

# Enable site
sudo a2ensite ai-security-gateway

# Test configuration
sudo apache2ctl configtest

# Restart Apache
sudo systemctl restart apache2

Step 4: SSL with Apache (Production)

bash

# Install Certbot for Apache
sudo apt-get install certbot python3-certbot-apache

# Enable SSL module
sudo a2enmod ssl

# Obtain SSL certificate
sudo certbot --apache -d your-domain.com

# This will create an SSL version of your virtual host automatically

API Server Setup (Both Nginx & Apache)

Step 1: Install API Server Binary

bash

# Download latest release
wget https://github.com/syphon1c/ai-security-gateway/releases/latest/download/unified-admin-linux-amd64.tar.gz

# Extract and install
tar -xzf unified-admin-linux-amd64.tar.gz
sudo cp unified-admin /usr/local/bin/
sudo chmod +x /usr/local/bin/unified-admin

Step 2: Create System Service

Create /etc/systemd/system/ai-security-gateway.service:

ini

[Unit]
Description=AI Security Gateway API Server
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/opt/ai-security-gateway
EnvironmentFile=/opt/ai-security-gateway/.env
ExecStart=/usr/local/bin/unified-admin
Restart=always
RestartSec=10

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/ai-security-gateway

[Install]
WantedBy=multi-user.target

Step 3: Configure Environment

bash

# Create application directory
sudo mkdir -p /opt/ai-security-gateway/data
sudo chown -R www-data:www-data /opt/ai-security-gateway

# Create environment file
sudo tee /opt/ai-security-gateway/.env > /dev/null <<EOF
# API Server Configuration
JWT_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -base64 32 | cut -c1-32)
ENVIRONMENT=production
SERVER_PORT=8080
LOG_LEVEL=info

# Database
DATABASE_PATH=/opt/ai-security-gateway/data/security.db

# CORS (adjust for your domain)
ALLOWED_ORIGINS=https://your-domain.com,https://www.your-domain.com
EOF

sudo chmod 600 /opt/ai-security-gateway/.env
sudo chown www-data:www-data /opt/ai-security-gateway/.env

Step 4: Start and Enable Service

bash

# Start service
sudo systemctl daemon-reload
sudo systemctl start ai-security-gateway
sudo systemctl enable ai-security-gateway

# Check status
sudo systemctl status ai-security-gateway

# View logs
sudo journalctl -u ai-security-gateway -f

Production Optimizations

Nginx Optimizations

Add to /etc/nginx/nginx.conf:

nginx

http {
    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/javascript
        application/xml+rss
        application/json;

    # Rate limiting for API
    limit_req_zone $binary_remote_addr zone=api:10m rate=100r/m;
    
    # Security headers (global)
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
}

Then in your server block:

nginx

# Apply rate limiting to API
location /api/ {
    limit_req zone=api burst=20 nodelay;
    # ... rest of proxy configuration
}

Load Balancing Multiple API Instances

For high availability, run multiple API server instances:

nginx

# Define upstream servers
upstream api_backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
    server 127.0.0.1:8082;
}

# Update proxy_pass in location /api/
location /api/ {
    proxy_pass http://api_backend;
    # ... rest of configuration
}

Start multiple API servers on different ports:

bash

# Instance 1 (port 8080)
SERVER_PORT=8080 /usr/local/bin/unified-admin &

# Instance 2 (port 8081)  
SERVER_PORT=8081 /usr/local/bin/unified-admin &

# Instance 3 (port 8082)
SERVER_PORT=8082 /usr/local/bin/unified-admin &

Testing the Deployment

1. Test Frontend

bash

# Should return HTML
curl http://your-domain.com/

# Should return Vue.js app JavaScript
curl http://your-domain.com/assets/index.js

2. Test API Proxy

bash

# Should return API health check
curl http://your-domain.com/api/v1/health

# Expected response:
{
  "status": "ok",
  "version": "2.1",
  "timestamp": "2025-11-16T..."
}

3. Test WebSocket

bash

# Test WebSocket connection (requires wscat or similar)
wscat -c ws://your-domain.com/ws

4. Test HTTPS (if configured)

bash

# Should redirect to HTTPS
curl -I http://your-domain.com/

# Should return 200 OK with SSL
curl -I https://your-domain.com/

Web Server Deployment Troubleshooting

Web Server Deployment Common Issues

1. 502 Bad Gateway

Check if API server is running: sudo systemctl status ai-security-gateway
Verify port 8080 is listening: netstat -tlnp | grep 8080
Check logs: sudo journalctl -u ai-security-gateway -f

2. WebSocket Connection Failed

Ensure WebSocket proxy is configured correctly
Check if websocket upgrade headers are being passed
Verify no firewall blocking WebSocket connections

3. Static Files Not Loading

Verify frontend files are in correct directory
Check file permissions (should be readable by www-data)
Ensure web server can serve static files

4. CORS Errors

Update ALLOWED_ORIGINS in .env file to include your domain
Restart API server after changing environment variables
Check browser developer tools for specific CORS errors

Web Server Log Locations

Nginx: /var/log/nginx/ai-gateway-*.log
Apache: /var/log/apache2/ai-gateway-*.log
API Server: sudo journalctl -u ai-security-gateway
Frontend Build: Check browser developer tools console

Performance Monitoring

bash

# Monitor API server resource usage
top -p $(pgrep unified-admin)

# Monitor web server connections
ss -tuln | grep :80
ss -tuln | grep :443

# Check response times
curl -w "@curl-format.txt" -o /dev/null -s http://your-domain.com/api/v1/health

Create curl-format.txt:

     time_namelookup:  %{time_namelookup}\n
        time_connect:  %{time_connect}\n
     time_appconnect:  %{time_appconnect}\n
    time_pretransfer:  %{time_pretransfer}\n
       time_redirect:  %{time_redirect}\n
  time_starttransfer:  %{time_starttransfer}\n
                     ----------\n
          time_total:  %{time_total}\n

Web Server Deployment Security Considerations

SSL/TLS: Always use HTTPS in production
Firewall: Only expose ports 80/443 to public, keep 8080 internal
Updates: Regularly update web server and API server binaries
Monitoring: Set up monitoring for both web server and API server
Backups: Regular backups of database and configuration files
Logs: Monitor logs for suspicious activity and errors

This deployment method provides optimal performance by combining:

Native Go binary performance for the API server
Optimized web server for static file serving and reverse proxy
Production-ready SSL termination and security headers
Familiar deployment patterns for system administrators

Web Server Deployment Guide ​

Web Server Architecture Overview ​

Nginx Deployment ​

Step 1: Build and Deploy Frontend ​

Step 2: Configure Nginx ​

Step 3: SSL Configuration (Production) ​

Step 4: Enable and Test Nginx ​

Apache Deployment ​

Step 1: Deploy Frontend Files ​

Step 2: Configure Apache Virtual Host ​

Step 3: Enable Required Apache Modules ​

Step 4: SSL with Apache (Production) ​

API Server Setup (Both Nginx & Apache) ​

Step 1: Install API Server Binary ​

Step 2: Create System Service ​

Step 3: Configure Environment ​

Step 4: Start and Enable Service ​

Production Optimizations ​

Nginx Optimizations ​

Load Balancing Multiple API Instances ​

Testing the Deployment ​

1. Test Frontend ​

2. Test API Proxy ​

3. Test WebSocket ​

4. Test HTTPS (if configured) ​

Web Server Deployment Troubleshooting ​

Web Server Deployment Common Issues ​

Web Server Log Locations ​

Performance Monitoring ​

Web Server Deployment Security Considerations ​

Web Server Deployment Guide

Web Server Architecture Overview

Nginx Deployment

Step 1: Build and Deploy Frontend

Step 2: Configure Nginx

Step 3: SSL Configuration (Production)

Step 4: Enable and Test Nginx

Apache Deployment

Step 1: Deploy Frontend Files

Step 2: Configure Apache Virtual Host

Step 3: Enable Required Apache Modules

Step 4: SSL with Apache (Production)

API Server Setup (Both Nginx & Apache)

Step 1: Install API Server Binary

Step 2: Create System Service

Step 3: Configure Environment

Step 4: Start and Enable Service

Production Optimizations

Nginx Optimizations

Load Balancing Multiple API Instances

Testing the Deployment

1. Test Frontend

2. Test API Proxy

3. Test WebSocket

4. Test HTTPS (if configured)

Web Server Deployment Troubleshooting

Web Server Deployment Common Issues

Web Server Log Locations

Performance Monitoring

Web Server Deployment Security Considerations