Update mkdocs with security policy, security guide and linking roadmap on frontpage (#550)

crivetimihai · web-flow · commit 259fa042c9bc · 2025-07-20T17:43:49.000+01:00
Signed-off-by: Mihai Criveti &lt;crivetimihai@gmail.com&gt;
diff --git a/docs/docs/.pages b/docs/docs/.pages
@@ -6,7 +6,7 @@ nav:
   - "🛡️ Manage": manage
   - "💻 Develop": development
   - "🧪 Test": testing
-  - "📐 Architecture": architecture
+  - "📐 Design & Roadmap": architecture
   - "📰 Media": media
   - "📖 Tutorials": tutorials
   - "❓ FAQ": faq
diff --git a/docs/docs/deployment/.pages b/docs/docs/deployment/.pages
@@ -13,4 +13,3 @@ nav:
   - aws.md
   - azure.md
   - fly-io.md
-  - tutorials
diff --git a/docs/docs/deployment/index.md b/docs/docs/deployment/index.md
@@ -4,6 +4,17 @@ This section explains how to deploy MCP Gateway in various environments - from l
 
 ---
 
+## 🔐 Security First
+
+**Before deploying to production**, review our [Security Guide](securing.md) for:
+- Critical security configurations
+- Production hardening checklist
+- Authentication and authorization setup
+- Network security best practices
+- Container security requirements
+
+---
+
 ## 🗺 Deployment Options
 
 MCP Gateway supports multiple deployment strategies:
@@ -19,6 +30,7 @@ MCP Gateway supports multiple deployment strategies:
 | [IBM Code Engine](ibm-code-engine.md) | Serverless container build & run on IBM Cloud                                             |
 | [AWS](aws.md)                         | Deploy on ECS Fargate, EKS, or EC2-hosted containers                                      |
 | [Azure](azure.md)                     | Run on Azure Container Apps, App Service, or AKS                                          |
+| [**Security Guide**](securing.md)     | **Essential security configurations and best practices for production deployments**        |
 
 ---
 
@@ -30,6 +42,8 @@ MCP Gateway loads configuration from:
 - Environment variables (overrides `.env`)
 - CLI flags (e.g., via `run.sh`)
 
+⚠️ **Security Note**: Never store sensitive credentials directly in environment variables. Use a secrets management system in production. See the [Security Guide](securing.md#secrets-management) for details.
+
 ---
 
 ## 🧪 Health Checks
@@ -54,3 +68,5 @@ The default container image:
 * Uses `.env` for all settings
 
 > For Kubernetes, you can mount a ConfigMap or Secret as `.env`.
+
+**Important**: For production deployments, ensure you follow the container hardening guidelines in our [Security Guide](securing.md#container-security).
diff --git a/docs/docs/deployment/securing.md b/docs/docs/deployment/securing.md
@@ -0,0 +1,222 @@
+# Securing MCP Gateway
+
+This guide provides essential security configurations and best practices for deploying MCP Gateway in production environments.
+
+## ⚠️ Critical Security Notice
+
+**MCP Gateway is currently in early beta (v0.3.1)** and requires careful security configuration for production use:
+
+- The **Admin UI is development-only** and must be disabled in production
+- MCP Gateway is **not a standalone product** - it's an open source component to integrate into your solution
+- **No official support** is provided - security is your responsibility
+- Expect **breaking changes** between versions until 1.0 release
+- Do not use it with insecure MCP servers.
+
+## 🚨 Production Security Checklist
+
+### 1. Disable Development Features
+
+```bash
+# Required for production - disable all admin interfaces
+MCPGATEWAY_UI_ENABLED=false
+MCPGATEWAY_ADMIN_API_ENABLED=false
+
+# Disable unused features
+MCPGATEWAY_ENABLE_ROOTS=false    # If not using roots
+MCPGATEWAY_ENABLE_PROMPTS=false  # If not using prompts
+MCPGATEWAY_ENABLE_RESOURCES=false # If not using resources
+```
+
+### 2. Enable Authentication
+
+```bash
+# Configure strong authentication
+MCPGATEWAY_AUTH_ENABLED=true
+MCPGATEWAY_AUTH_USERNAME=custom-username  # Change from default
+MCPGATEWAY_AUTH_PASSWORD=strong-password-here  # Use secrets manager
+```
+
+### 3. Network Security
+
+- [ ] Configure TLS/HTTPS with valid certificates
+- [ ] Implement firewall rules and network policies
+- [ ] Use internal-only endpoints where possible
+- [ ] Configure appropriate CORS policies
+- [ ] Set up rate limiting per endpoint/client
+
+### 4. Container Security
+
+```bash
+# Run containers with security constraints
+docker run \
+  --read-only \
+  --user 1001:1001 \
+  --cap-drop ALL \
+  --security-opt no-new-privileges \
+  mcpgateway:latest
+```
+
+- [ ] Use minimal base images (UBI Micro)
+- [ ] Run as non-root user
+- [ ] Enable read-only filesystem
+- [ ] Set resource limits (CPU, memory)
+- [ ] Scan images for vulnerabilities
+
+### 5. Secrets Management
+
+- [ ] **Never store secrets in environment variables directly**
+- [ ] Use a secrets management system (Vault, AWS Secrets Manager, etc.)
+- [ ] Rotate credentials regularly
+- [ ] Restrict container access to secrets
+- [ ] Never commit `.env` files to version control
+
+### 6. MCP Server Validation
+
+Before connecting any MCP server:
+
+- [ ] Verify server authenticity and source code
+- [ ] Review server permissions and data access
+- [ ] Test in isolated environment first
+- [ ] Monitor server behavior for anomalies
+- [ ] Implement rate limiting for untrusted servers
+
+### 7. Database Security
+
+- [ ] Use TLS for database connections
+- [ ] Configure strong passwords
+- [ ] Restrict database access by IP/network
+- [ ] Enable audit logging
+- [ ] Regular backups with encryption
+
+### 8. Monitoring & Logging
+
+- [ ] Set up structured logging without sensitive data
+- [ ] Configure log rotation and secure storage
+- [ ] Implement monitoring and alerting
+- [ ] Set up anomaly detection
+- [ ] Create incident response procedures
+
+### 9. Integration Security
+
+MCP Gateway should be integrated with:
+
+- [ ] API Gateway for auth and rate limiting
+- [ ] Web Application Firewall (WAF)
+- [ ] Identity and Access Management (IAM)
+- [ ] SIEM for security monitoring
+- [ ] Load balancer with TLS termination
+
+### 10. Downstream Application Security
+
+Applications consuming MCP Gateway data must:
+
+- [ ] Validate all inputs from the gateway
+- [ ] Implement context-appropriate sanitization
+- [ ] Use Content Security Policy (CSP) headers
+- [ ] Escape data for output context (HTML, JS, SQL)
+- [ ] Implement their own authentication/authorization
+
+## 🔐 Environment Variables Reference
+
+### Security-Critical Settings
+
+```bash
+# Core Security
+MCPGATEWAY_UI_ENABLED=false              # Must be false in production
+MCPGATEWAY_ADMIN_API_ENABLED=false       # Must be false in production
+MCPGATEWAY_AUTH_ENABLED=true             # Enable authentication
+MCPGATEWAY_AUTH_USERNAME=custom-user     # Change from default
+MCPGATEWAY_AUTH_PASSWORD=<from-secrets>  # Use secrets manager
+
+# Feature Flags (disable unused features)
+MCPGATEWAY_ENABLE_ROOTS=false
+MCPGATEWAY_ENABLE_PROMPTS=false
+MCPGATEWAY_ENABLE_RESOURCES=false
+
+# Network Security
+MCPGATEWAY_CORS_ALLOWED_ORIGINS=https://your-domain.com
+MCPGATEWAY_RATE_LIMIT_ENABLED=true
+MCPGATEWAY_RATE_LIMIT_PER_MINUTE=100
+
+# Logging (no sensitive data)
+MCPGATEWAY_LOG_LEVEL=INFO               # Not DEBUG in production
+MCPGATEWAY_LOG_SENSITIVE_DATA=false     # Never log sensitive data
+```
+
+## 🚀 Deployment Architecture
+
+### Recommended Production Architecture
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│                 │     │                 │     │                 │
+│   WAF/CDN       │────▶│  Load Balancer │────▶│   API Gateway   │
+│                 │     │   (TLS Term)    │     │  (Auth/Rate)    │
+└─────────────────┘     └─────────────────┘     └────────┬────────┘
+                                                          │
+                                                          ▼
+                                                 ┌─────────────────┐
+                                                 │                 │
+                                                 │  MCP Gateway    │
+                                                 │  (Internal)     │
+                                                 └────────┬────────┘
+                                                          │
+                              ┌───────────────────────────┼───────────────────────────┐
+                              │                           │                           │
+                              ▼                           ▼                           ▼
+                     ┌─────────────────┐        ┌─────────────────┐        ┌─────────────────┐
+                     │                 │        │                 │        │                 │
+                     │  Trusted MCP    │        │    Database     │        │     Redis       │
+                     │    Servers      │        │   (TLS/Auth)    │        │   (TLS/Auth)    │
+                     └─────────────────┘        └─────────────────┘        └─────────────────┘
+```
+
+## 🔍 Security Validation
+
+### Pre-Production Checklist
+
+1. **Run Security Scans**
+   ```bash
+   make security-all        # Run all security tools
+   make security-report     # Generate security report
+   make trivy              # Scan container vulnerabilities
+   ```
+
+2. **Validate Configuration**
+   - Review all environment variables
+   - Confirm admin features disabled
+   - Verify authentication enabled
+   - Check TLS configuration
+
+3. **Test Security Controls**
+   - Attempt unauthorized access
+   - Verify rate limiting works
+   - Test input validation
+   - Check error handling
+
+4. **Review Dependencies**
+   ```bash
+   make pip-audit          # Check Python dependencies
+   make sbom              # Generate software bill of materials
+   ```
+
+## 📚 Additional Resources
+
+- [Security Policy](https://github.com/IBM/mcp-context-forge/blob/main/SECURITY.md) - Full security documentation
+- [Deployment Options](index.md) - Various deployment methods
+- [Environment Variables](../configuration/environment-variables.md) - Complete configuration reference
+
+## ⚡ Quick Start Security Commands
+
+```bash
+# Development (with security checks)
+make security-all && make test && make run
+
+# Production build
+make docker-prod
+
+# Security audit
+make security-report
+```
+
+Remember: **Security is a shared responsibility**. MCP Gateway provides *some* security controls, but you must properly configure and integrate it within a comprehensive security architecture.
diff --git a/docs/docs/deployment/tutorials/.pages b/docs/docs/deployment/tutorials/.pages
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -10,6 +10,8 @@ A flexible FastAPI-based gateway and router for **Model Context Protocol (MCP)**
 
 ![MCP Gateway](images/mcpgateway.gif)
 
+**⚠️ Important**: MCP Gateway is not a standalone product - it is an open source component with **NO OFFICIAL SUPPORT** from IBM or its affiliates that can be integrated into your own solution architecture. If you choose to use it, you are responsible for evaluating its fit, securing the deployment, and managing its lifecycle. See [SECURITY.md](https://github.com/IBM/mcp-context-forge/blob/main/SECURITY.md) for more details, and the [roadmap](architecture/roadmap.md) for upcoming features.
+
 ---
 
 ## What it Does
diff --git a/docs/docs/tutorials/.pages b/docs/docs/tutorials/.pages
@@ -1,2 +1,4 @@
 nav:
+  - index.md
+  - argocd-helm-deployment-ibm-cloud-iks.md
   - openwebui-tutorial.md
diff --git a/docs/docs/tutorials/argocd-helm-deployment-ibm-cloud-iks.md b/docs/docs/tutorials/argocd-helm-deployment-ibm-cloud-iks.md
diff --git a/docs/docs/tutorials/index.md b/docs/docs/tutorials/index.md
@@ -0,0 +1,44 @@
+# 📚 Tutorials
+
+> Step-by-step guides to help you deploy and integrate MCP Gateway and related components using both **cloud-native** and **local containerized** environments.
+
+---
+
+## 🚀 Cloud Deployment with Argo CD and IBM Cloud Kubernetes Service
+
+This guide walks you through deploying the **MCP Gateway Stack** on **IBM Cloud Kubernetes Service (IKS)** using **Helm** and **Argo CD** for GitOps-based lifecycle management. You'll learn how to:
+
+- Build and push container images to IBM Container Registry
+- Provision an IKS cluster with VPC-native networking
+- Deploy the full MCP Gateway Helm chart via Argo CD
+- Configure services like PostgreSQL, Redis, and TLS
+- Connect AI clients like VS Code Copilot and LangChain Agent
+
+👉 [Read the full guide](argocd-helm-deployment-ibm-cloud-iks.md)
+
+---
+
+## 🧠 Local Deployment of OpenWebUI + MCP Tools
+
+This tutorial helps you set up **OpenWebUI** integrated with **Ollama**, **LiteLLM**, **MCPO**, and the **MCP Gateway** in a local containerized environment using Docker. It covers:
+
+- Running LLMs locally via Ollama
+- Using LiteLLM as a proxy for unified model access
+- Bridging MCP tools through MCPO to OpenWebUI
+- Managing MCP servers with the MCP Gateway
+- Connecting it all through Docker networks
+
+Perfect for experimenting on your workstation or air-gapped environments.
+
+👉 [View the tutorial](openwebui-tutorial.md)
+
+---
+
+
+## 📦 Additional Resources
+
+- [MCP Gateway GitHub](https://github.com/ibm/mcp-context-forge)
+- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
+- [OpenWebUI Documentation](https://docs.openwebui.com/)
+
+Stay tuned for more guides on CI/CD, hybrid federation, observability, and secure API operations.
