Docker Deployment Guide (Frontend Only)

This guide covers deploying AI Security Gateway using Docker for the frontend only. The API server now uses native Go binaries for optimal performance.

Docker Architecture Overview

┌──────────────────────┐
│   Frontend (Port 80)        │
│   Docker + Nginx           │
│   Serves Vue.js App        │
└──────────┬───────────┘
              │ Reverse Proxy
              │ /api/*, /ws
┌──────────┴───────────┐
│   API Server (Port 8080)    │
│   Native Go Binary         │
│   ./unified-admin          │
└──────────────────────┘

Quick Start with Docker Frontend

The recommended approach uses Docker only for serving the frontend, while the API server runs as a native binary:

bash

# 1. Download and start API server binary
wget https://github.com/syphon1c/ai-security-gateway/releases/latest/download/unified-admin-linux-amd64.tar.gz
tar -xzf unified-admin-linux-amd64.tar.gz
cp .env.example .env
nano .env  # Set JWT_SECRET and ENCRYPTION_KEY
./unified-admin &

# 2. Start Docker frontend
cp frontend/.env.example frontend/.env
nano frontend/.env  # Configure VITE_API_BASE_URL=http://localhost:8080
docker-compose -f docker-compose.frontend.yml up -d

Access the web interface at: http://localhost (port 80)

Current Architecture

The deployment now uses a hybrid approach:

✅ API Server: Native Go binary (optimal performance, no container overhead)
✅ Frontend: Docker container with Nginx (easy deployment, consistent serving)
✅ Simple Setup: One binary + one container

           ┌─────────────┐
           │   Port 80   │
           └──────┬──────┘
                  │
           ┌──────▼──────┐
           │    Nginx    │
           │  Container  │
           └──┬──────┬───┘
              │      │
    ┌─────────┘      └──────────┐
    │                           │
    ▼                           ▼
Frontend         API/WebSocket Proxy
(static)         (to binary:8080)

┌───────────────────────────────┐
│  Native API Server (Port 8080)   │
│  ./unified-admin (Go Binary)     │
└───────────────────────────────┘

Frontend Docker Deployment Options

Option 1: Docker Compose (Recommended)

Use the provided Docker Compose file for frontend:

bash

# 1. Ensure API server binary is running
./unified-admin &

# 2. Configure frontend environment
cp frontend/.env.example frontend/.env
nano frontend/.env  # Set VITE_API_BASE_URL=http://localhost:8080

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

# 4. Access web interface
# Frontend: http://localhost:80
# API: http://localhost:8080

Option 2: Manual Docker Run

If you prefer manual container management:

bash

# 1. Build frontend
cd frontend
npm install
npm run build
cd ..

# 2. Build frontend Docker image
docker build -f Dockerfile.frontend -t ai-gateway-frontend .

# 3. Run frontend container
docker run -d \
  --name ai-gateway-frontend \
  -p 80:80 \
  -v $(pwd)/frontend/.env:/app/config/.env:ro \
  -e BACKEND_HOST=host.docker.internal:8080 \
  ai-gateway-frontend

# 4. Add host networking for API server communication
docker run -d \
  --name ai-gateway-frontend \
  -p 80:80 \
  --add-host=host.docker.internal:host-gateway \
  ai-gateway-frontend

Multi-Architecture Support

The Docker images support multiple architectures:

linux/amd64 - Intel/AMD x86_64 processors
linux/arm64 - ARM 64-bit (Apple Silicon M1/M2/M3, Raspberry Pi 4+, AWS Graviton)

Docker automatically pulls the correct architecture for your system.

Docker Deployment Environment Variables

Docker Required Variables

Variable	Description	Example
`JWT_SECRET`	Secret key for JWT token signing	`your-super-secret-jwt-key`
`ENCRYPTION_KEY`	Encryption key for sensitive data	`your-super-secret-enc-key`

Optional Variables

Variable	Default	Description
`AUTH_ENABLED`	`true`	Enable/disable authentication
`JWT_EXPIRY`	`24h`	JWT token expiration time
`JWT_REFRESH_EXPIRY`	`168h`	Refresh token expiration (7 days)
`DATABASE_PATH`	`/app/data/ai-gateway-security.db`	SQLite database location
`CONFIG_PATH`	`/app/configs/config.yaml`	Configuration file path
`LOG_LEVEL`	`info`	Logging level (debug, info, warn, error)
`CORS_ALLOWED_ORIGINS`	`http://localhost:8080`	Comma-separated list of allowed origins

OAuth Variables (Optional)

Variable	Description
`OAUTH_GOOGLE_CLIENT_ID`	Google OAuth client ID
`OAUTH_GOOGLE_CLIENT_SECRET`	Google OAuth client secret
`OAUTH_GITHUB_CLIENT_ID`	GitHub OAuth app ID
`OAUTH_GITHUB_CLIENT_SECRET`	GitHub OAuth app secret

Volume Mounts

Data Persistence

Mount /app/data to persist the SQLite database:

bash

docker run -v gateway-data:/app/data ...

Or use a local directory:

bash

docker run -v ./data:/app/data ...

Custom Configuration

Mount custom configs directory:

bash

docker run -v ./my-configs:/app/configs:ro ...

Custom Policies

Mount custom security policies:

bash

docker run -v ./my-policies:/app/policies:ro ...

Complete Example with All Mounts

bash

docker run -d \
  --name ai-security-gateway \
  -p 8080:8080 \
  -v gateway-data:/app/data \
  -v ./configs:/app/configs:ro \
  -v ./policies:/app/policies:ro \
  -v ./.env:/app/.env:ro \
  ghcr.io/syphon1c/ai-security-gateway:latest

Health Checks

The Docker image includes built-in health checks:

bash

# Check container health
docker inspect --format='{{.State.Health.Status}}' ai-security-gateway

# View health check logs
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' ai-security-gateway

Health check endpoint: http://localhost:8080/api/v1/health

Networking

Port Mapping

The default port is 8080. Map to a different host port:

bash

docker run -p 3000:8080 ...  # Access via http://localhost:3000

Custom Network

Create a custom Docker network for multi-container setups:

bash

# Create network
docker network create gateway-net

# Run with custom network
docker run --network gateway-net ...

Docker Security Best Practices

1. Use Strong Secrets

Generate secure random secrets:

bash

# Generate JWT_SECRET (32+ characters)
openssl rand -base64 32

# Generate ENCRYPTION_KEY (32+ characters)
openssl rand -base64 32

2. Run as Non-Root

The container automatically runs as user gateway (UID 1000, GID 1000). No additional configuration needed.

3. Read-Only Mounts

Mount configs and policies as read-only:

bash

-v ./configs:/app/configs:ro
-v ./policies:/app/policies:ro

4. Limit Resources

Set memory and CPU limits:

bash

docker run \
  --memory="512m" \
  --cpus="1.0" \
  ...

In docker-compose.yml:

yaml

services:
  unified-admin:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.0'

5. Use Secrets Management

For production, use Docker secrets instead of environment variables:

bash

# Create secrets
echo "my-jwt-secret" | docker secret create jwt_secret -
echo "my-enc-key" | docker secret create enc_key -

# Reference in stack
docker stack deploy -c docker-compose.yml gateway

Building Custom Images

Extending Pre-Built Images

You can create custom images based on the official pre-built releases:

Build with Custom Configs

dockerfile

FROM ghcr.io/syphon1c/ai-security-gateway:latest

# Copy custom configs
COPY my-custom-configs/ /app/configs/
COPY my-custom-policies/ /app/policies/

Docker Deployment Troubleshooting

Container Won't Start

Check logs:

bash

docker logs ai-security-gateway

Common issues:

Missing JWT_SECRET or ENCRYPTION_KEY
Port 8080 already in use
Insufficient permissions on data volume

Database Locked Errors

Ensure only one container accesses the database:

bash

# Stop all instances
docker stop $(docker ps -q --filter ancestor=ghcr.io/syphon1c/ai-security-gateway)

# Start single instance
docker-compose up -d

Permission Denied on Volumes

Fix volume permissions:

bash

# Set correct ownership (UID 1000)
sudo chown -R 1000:1000 ./data

Health Check Failing

Test health endpoint manually:

bash

curl http://localhost:8080/api/v1/health

If unreachable:

Check if container is running: docker ps
Verify port mapping: docker port ai-security-gateway
Check firewall rules

Docker Deployment Production Deployment

Docker Swarm

bash

# Initialize swarm
docker swarm init

# Deploy stack
docker stack deploy -c docker-compose.yml gateway

# Scale service
docker service scale gateway_unified-admin=3

# View services
docker service ls

Kubernetes

Example Kubernetes deployment:

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ai-security-gateway
spec:
  replicas: 2
  selector:
    matchLabels:
      app: ai-security-gateway
  template:
    metadata:
      labels:
        app: ai-security-gateway
    spec:
      containers:
      - name: gateway
        image: ghcr.io/syphon1c/ai-security-gateway:latest
        ports:
        - containerPort: 8080
        env:
        - name: JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: gateway-secrets
              key: jwt-secret
        - name: ENCRYPTION_KEY
          valueFrom:
            secretKeyRef:
              name: gateway-secrets
              key: encryption-key
        volumeMounts:
        - name: data
          mountPath: /app/data
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: gateway-data

Reverse Proxy (Nginx)

nginx

upstream gateway {
    server localhost:8080;
}

server {
    listen 443 ssl http2;
    server_name gateway.example.com;

    ssl_certificate /etc/ssl/certs/gateway.crt;
    ssl_certificate_key /etc/ssl/private/gateway.key;

    location / {
        proxy_pass http://gateway;
        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;
    }
}

Docker Deployment Monitoring

Container Stats

bash

# Real-time stats
docker stats ai-security-gateway

# CPU and memory usage
docker stats --no-stream ai-security-gateway

Docker Log Aggregation

Send logs to external system:

bash

docker run \
  --log-driver=syslog \
  --log-opt syslog-address=udp://logserver:514 \
  ...

Prometheus Metrics

The application exposes metrics at /api/v1/metrics (when enabled in config).

Updates

Pull Latest Image

bash

# Pull latest
docker pull ghcr.io/syphon1c/ai-security-gateway:latest

# Restart with new image
docker-compose down
docker-compose up -d

Backup Before Update

bash

# Backup database
docker exec ai-security-gateway cp /app/data/ai-gateway-security.db /app/data/backup.db

# Or copy to host
docker cp ai-security-gateway:/app/data/ai-gateway-security.db ./backup.db

Docker Deployment Support

Documentation: https://github.com/syphon1c/ai-security-gateway/tree/main/docs
Issues: https://github.com/syphon1c/ai-security-gateway/issues
Discussions: https://github.com/syphon1c/ai-security-gateway/discussions

Docker Deployment Guide (Frontend Only) ​

Docker Architecture Overview ​

Quick Start with Docker Frontend ​

Current Architecture ​

Frontend Docker Deployment Options ​

Option 1: Docker Compose (Recommended) ​

Option 2: Manual Docker Run ​

Multi-Architecture Support ​

Docker Deployment Environment Variables ​

Docker Required Variables ​

Optional Variables ​

OAuth Variables (Optional) ​

Volume Mounts ​

Data Persistence ​

Custom Configuration ​

Custom Policies ​

Complete Example with All Mounts ​

Health Checks ​

Networking ​

Port Mapping ​

Custom Network ​

Docker Security Best Practices ​

1. Use Strong Secrets ​

2. Run as Non-Root ​

3. Read-Only Mounts ​

4. Limit Resources ​

5. Use Secrets Management ​

Building Custom Images ​

Extending Pre-Built Images ​

Build with Custom Configs ​

Docker Deployment Troubleshooting ​

Container Won't Start ​

Database Locked Errors ​

Permission Denied on Volumes ​

Health Check Failing ​

Docker Deployment Production Deployment ​

Docker Swarm ​

Kubernetes ​

Reverse Proxy (Nginx) ​

Docker Deployment Monitoring ​

Container Stats ​

Docker Log Aggregation ​

Prometheus Metrics ​

Updates ​

Pull Latest Image ​

Backup Before Update ​

Docker Deployment Support ​

Docker Deployment Guide (Frontend Only)

Docker Architecture Overview

Quick Start with Docker Frontend

Current Architecture

Frontend Docker Deployment Options

Option 1: Docker Compose (Recommended)

Option 2: Manual Docker Run

Multi-Architecture Support

Docker Deployment Environment Variables

Docker Required Variables

Optional Variables

OAuth Variables (Optional)

Volume Mounts

Data Persistence

Custom Configuration

Custom Policies

Complete Example with All Mounts

Health Checks

Networking

Port Mapping

Custom Network

Docker Security Best Practices

1. Use Strong Secrets

2. Run as Non-Root

3. Read-Only Mounts

4. Limit Resources

5. Use Secrets Management

Building Custom Images

Extending Pre-Built Images

Build with Custom Configs

Docker Deployment Troubleshooting

Container Won't Start

Database Locked Errors

Permission Denied on Volumes

Health Check Failing

Docker Deployment Production Deployment

Docker Swarm

Kubernetes

Reverse Proxy (Nginx)

Docker Deployment Monitoring

Container Stats

Docker Log Aggregation

Prometheus Metrics

Updates

Pull Latest Image

Backup Before Update

Docker Deployment Support