Docker Deployment Commands Reference

Quick reference for deploying AI Security Gateway with Docker.

Multi-Container Setup (Recommended for Production)

Network Modes: Host vs Bridge

AI Security Gateway supports two networking modes:

Host Networking (Default - Linux only):

✅ Automatic exposure of all proxy ports
✅ No port configuration needed
✅ Best performance
⚠️ Linux only (not fully supported on macOS/Windows Docker Desktop)

Bridge Networking (Alternative - All platforms):

✅ Works on macOS, Windows, and Linux
✅ Network isolation
⚠️ Requires predefined port range for proxies (default: 8040-8100)

Choose the appropriate docker-compose.yml for your platform:

Linux: Use default docker-compose.yml (host networking)
macOS/Windows: Use docker-compose.bridge.yml (bridge networking)

Using Docker Compose (Linux - Host Networking)

Prerequisites:

docker-compose.yml file
.env file with JWT_SECRET and ENCRYPTION_KEY

bash

# Download configuration files
curl -LO https://raw.githubusercontent.com/syphon1c/ai-security-gateway/main/docker-compose.yml
curl -LO https://raw.githubusercontent.com/syphon1c/ai-security-gateway/main/.env.example

# Configure environment variables
cp .env.example .env
nano .env  # Set JWT_SECRET and ENCRYPTION_KEY

# Start all services (backend + frontend)
docker-compose up -d

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f nginx
docker-compose logs -f ai-security-gateway-backend

# Stop services
docker-compose down

# Update to latest version
docker-compose pull
docker-compose up -d

# Check service status
docker-compose ps

Access:

Web Interface: http://localhost (port 80)
API: http://localhost:8080
Proxy ports: Any port configured via API is automatically accessible

Using Docker Compose (macOS/Windows - Bridge Networking)

Prerequisites:

docker-compose.bridge.yml file
.env file with JWT_SECRET, ENCRYPTION_KEY, optional PROXY_PORT_START, PROXY_PORT_END

bash

# Download configuration files
curl -LO https://raw.githubusercontent.com/syphon1c/ai-security-gateway/main/docker-compose.bridge.yml
curl -LO https://raw.githubusercontent.com/syphon1c/ai-security-gateway/main/.env.example

# Rename to docker-compose.yml
mv docker-compose.bridge.yml docker-compose.yml

# Configure environment variables
cp .env.example .env
nano .env
# Set JWT_SECRET and ENCRYPTION_KEY
# Optional: PROXY_PORT_START=8040, PROXY_PORT_END=8100

# Start all services (backend + frontend)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Update to latest version
docker-compose pull
docker-compose up -d

# Check service status
docker-compose ps

Access:

Web Interface: http://localhost (port 80)
API: http://localhost:8080
Proxy ports: http://localhost:8040-8100 (default range, configurable in .env)

Note: When creating proxies via API, ensure the port is within your configured range (PROXY_PORT_START to PROXY_PORT_END).

Standalone Container Setup

Backend Only

bash

# Run backend container
docker run -d \
  --name unify-backend \
  -p 8080:8080 \
  -e JWT_SECRET=your-secret-key-here \
  -e ENCRYPTION_KEY=your-encryption-key-here \
  -e AUTH_ENABLED=true \
  -v gateway-data:/app/data \
  ghcr.io/syphon1c/ai-security-gateway:latest

# View logs
docker logs -f unify-backend

# Stop container
docker stop unify-backend
docker rm unify-backend

Access API: http://localhost:8080/api/v1/health

Frontend Only (Connecting to External Backend)

bash

# Run frontend container pointing to backend on host machine
docker run -d \
  --name unify-frontend \
  -p 80:80 \
  -e BACKEND_HOST=host.docker.internal:8080 \
  ghcr.io/syphon1c/ai-security-gateway-frontend:latest

# Or point to remote backend
docker run -d \
  --name unify-frontend \
  -p 80:80 \
  -e BACKEND_HOST=192.168.1.100:8080 \
  ghcr.io/syphon1c/ai-security-gateway-frontend:latest

# View logs
docker logs -f unify-frontend

# Stop container
docker stop unify-frontend
docker rm unify-frontend

Access: http://localhost

Backend + Frontend Together (Standalone Test)

bash

# Create a Docker network
docker network create gateway-net

# Run backend
docker run -d \
  --name unify-backend \
  --network gateway-net \
  -e JWT_SECRET=your-secret-key-here \
  -e ENCRYPTION_KEY=your-encryption-key-here \
  -v gateway-data:/app/data \
  ghcr.io/syphon1c/ai-security-gateway:latest

# Run frontend (using backend container name)
docker run -d \
  --name unify-frontend \
  --network gateway-net \
  -p 80:80 \
  -e BACKEND_HOST=unify-backend:8080 \
  ghcr.io/syphon1c/ai-security-gateway-frontend:latest

# View logs
docker logs -f unify-backend
docker logs -f unify-frontend

# Stop and cleanup
docker stop unify-backend unify-frontend
docker rm unify-backend unify-frontend
docker network rm gateway-net

Access: http://localhost

Combined Single-Container Setup

Using Dockerfile.combined (All-in-One)

Build and run both backend and frontend in a single container:

bash

# Build the combined image
docker build -f Dockerfile.combined -t ai-security-gateway-combined .

# Run the combined container
docker run -d \
  --name unify-gateway \
  -p 80:80 \
  -e JWT_SECRET=your-secret-key-here \
  -e ENCRYPTION_KEY=your-encryption-key-here \
  -v gateway-data:/app/data \
  ai-security-gateway-combined

# View logs (shows both backend and nginx)
docker logs -f unify-gateway

# Stop container
docker stop unify-gateway
docker rm unify-gateway

Access: http://localhost

Pros:

Single container deployment
Simpler networking
Good for development/testing

Cons:

Can't scale frontend/backend independently
Mixed logs

Common Operations

View Container Logs

bash

# Follow logs in real-time
docker logs -f <container-name>

# View last 100 lines
docker logs --tail 100 <container-name>

# View logs with timestamps
docker logs -t <container-name>

Execute Commands in Container

bash

# Open shell in running container
docker exec -it <container-name> sh

# Check backend health
docker exec unify-backend wget -qO- http://localhost:8080/api/v1/health

# View nginx config in frontend container
docker exec unify-frontend cat /etc/nginx/nginx.conf

Data Management

bash

# List volumes
docker volume ls

# Inspect volume
docker volume inspect gateway-data

# Backup database
docker run --rm \
  -v gateway-data:/app/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/gateway-backup.tar.gz -C /app/data .

# Restore database
docker run --rm \
  -v gateway-data:/app/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/gateway-backup.tar.gz -C /app/data

Cleanup

bash

# Stop all containers
docker stop $(docker ps -q)

# Remove all stopped containers
docker container prune

# Remove unused images
docker image prune

# Remove unused volumes
docker volume prune

# Complete cleanup (WARNING: removes all unused Docker resources)
docker system prune -a --volumes

Docker Environment Variables

Backend Container Variables

Variable	Required	Default	Description
`JWT_SECRET`	Yes	-	Secret key for JWT token signing
`ENCRYPTION_KEY`	Yes	-	Encryption key for sensitive data
`AUTH_ENABLED`	No	`true`	Enable/disable authentication
`JWT_EXPIRY`	No	`24h`	JWT token expiration time
`JWT_REFRESH_EXPIRY`	No	`168h`	Refresh token expiration (7 days)
`DATABASE_PATH`	No	`/app/data/ai-gateway-security.db`	SQLite database location
`LOG_LEVEL`	No	`info`	Logging level (debug, info, warn, error)
`CORS_ALLOWED_ORIGINS`	No	`http://localhost:8080`	Comma-separated CORS origins

Frontend Container Variables

Variable	Required	Default	Description
`BACKEND_HOST`	No	`ai-security-gateway-backend:8080`	Backend server address

Docker Troubleshooting

Frontend shows "host not found" error

Problem: Frontend can't connect to backend

Solution: Set BACKEND_HOST environment variable:

bash

# For backend on host machine
docker run -d -p 80:80 \
  -e BACKEND_HOST=host.docker.internal:8080 \
  ghcr.io/syphon1c/ai-security-gateway-frontend:latest

# For backend in Docker network
docker run -d -p 80:80 \
  --network gateway-net \
  -e BACKEND_HOST=unify-backend:8080 \
  ghcr.io/syphon1c/ai-security-gateway-frontend:latest

Backend won't start

Problem: Missing required environment variables

Solution: Ensure JWT_SECRET and ENCRYPTION_KEY are set:

bash

docker run -d -p 8080:8080 \
  -e JWT_SECRET=$(openssl rand -base64 32) \
  -e ENCRYPTION_KEY=$(openssl rand -base64 32) \
  ghcr.io/syphon1c/ai-security-gateway:latest

Can't access frontend at http://localhost

Problem: Port already in use

Solution: Use different port:

bash

# Use port 8888 instead
docker run -d -p 8888:80 \
  -e BACKEND_HOST=host.docker.internal:8080 \
  ghcr.io/syphon1c/ai-security-gateway-frontend:latest

# Access at http://localhost:8888

Database is lost after restart

Problem: Not using volume for data persistence

Solution: Always mount /app/data volume:

bash

docker run -d -p 8080:8080 \
  -v gateway-data:/app/data \
  -e JWT_SECRET=your-secret \
  -e ENCRYPTION_KEY=your-key \
  ghcr.io/syphon1c/ai-security-gateway:latest

Production Deployment Tips

Use Docker Compose

Always use docker-compose.yml for production - it handles networking, volumes, and environment variables automatically.

Set Strong Secrets

Generate strong random secrets:

bash

# Add to .env file
echo "JWT_SECRET=$(openssl rand -base64 32)" >> .env
echo "ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env

Enable HTTPS

For production, run behind a reverse proxy (Nginx, Traefik, Caddy) with TLS certificates.

Monitor Health

Use health checks:

bash

# Check backend health
curl http://localhost:8080/api/v1/health

# Check frontend health
curl http://localhost/health

Backup Regularly

Automate database backups:

bash

#!/bin/bash
# backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
docker run --rm \
  -v gateway-data:/app/data \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/gateway-$DATE.tar.gz -C /app/data .

Resource Limits

Set CPU and memory limits:

yaml

# docker-compose.yml
services:
  ai-security-gateway-backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          memory: 512M

Quick Reference Card

Task	Command
Start services	`docker-compose up -d`
Stop services	`docker-compose down`
View logs	`docker-compose logs -f`
Update images	`docker-compose pull && docker-compose up -d`
Backend health	`curl http://localhost:8080/api/v1/health`
Frontend health	`curl http://localhost/health`
Shell access	`docker exec -it <container> sh`
Backup database	`docker run --rm -v gateway-data:/data -v $(pwd):/backup alpine tar czf /backup/db.tar.gz -C /data .`
Generate secret	`openssl rand -base64 32`

Docker Commands Support

Documentation: https://github.com/syphon1c/ai-security-gateway/tree/main/docs
Issues: https://github.com/syphon1c/ai-security-gateway/issues
Docker Hub: https://github.com/syphon1c/ai-security-gateway/pkgs/container/ai-security-gateway

Docker Deployment Commands Reference ​

Multi-Container Setup (Recommended for Production) ​

Network Modes: Host vs Bridge ​

Using Docker Compose (Linux - Host Networking) ​

Using Docker Compose (macOS/Windows - Bridge Networking) ​

Standalone Container Setup ​

Backend Only ​

Frontend Only (Connecting to External Backend) ​

Backend + Frontend Together (Standalone Test) ​

Combined Single-Container Setup ​

Using Dockerfile.combined (All-in-One) ​

Common Operations ​

View Container Logs ​

Execute Commands in Container ​

Data Management ​

Cleanup ​

Docker Environment Variables ​

Backend Container Variables ​

Frontend Container Variables ​

Docker Troubleshooting ​

Frontend shows "host not found" error ​

Backend won't start ​

Can't access frontend at http://localhost ​

Database is lost after restart ​

Production Deployment Tips ​

Use Docker Compose ​

Set Strong Secrets ​

Enable HTTPS ​

Monitor Health ​

Backup Regularly ​

Resource Limits ​

Quick Reference Card ​

Docker Commands Support ​

Docker Deployment Commands Reference

Multi-Container Setup (Recommended for Production)

Network Modes: Host vs Bridge

Using Docker Compose (Linux - Host Networking)

Using Docker Compose (macOS/Windows - Bridge Networking)

Standalone Container Setup

Backend Only

Frontend Only (Connecting to External Backend)

Backend + Frontend Together (Standalone Test)

Combined Single-Container Setup

Using Dockerfile.combined (All-in-One)

Common Operations

View Container Logs

Execute Commands in Container

Data Management

Cleanup

Docker Environment Variables

Backend Container Variables

Frontend Container Variables

Docker Troubleshooting

Frontend shows "host not found" error

Backend won't start

Can't access frontend at http://localhost

Database is lost after restart

Production Deployment Tips

Use Docker Compose

Set Strong Secrets

Enable HTTPS

Monitor Health

Backup Regularly

Resource Limits

Quick Reference Card

Docker Commands Support