#!/usr/bin/env bash
#───────────────────────────────────────────────────────────────────────────────
# Script : run-granian.sh
# Author : Mihai Criveti
# Purpose: Launch the MCP Gateway API under Granian (Rust-based ASGI server)
#
# Description:
# This script provides a robust way to launch a production API server using
# Granian with the following features:
#
# - Rust-based HTTP server (Hyper + Tokio) for high performance
# - Native HTTP/2 support
# - Native WebSocket support
# - Native mTLS support
# - Portable Python detection across different distros
# - Virtual environment handling
# - Configurable via environment variables for CI/CD pipelines
# - Optional TLS/SSL support for secure connections
# - Process lock to prevent duplicate instances
# - Auto-detection of optimal worker count based on CPU cores
#
# Environment Variables:
# PYTHON : Path to Python interpreter (optional)
# VIRTUAL_ENV : Path to active virtual environment (auto-detected)
# HOST : Bind host (default: 0.0.0.0)
# PORT : Bind port (default: 4444)
# GRANIAN_WORKERS : Number of worker processes (default: "auto" = CPU cores, max 16)
# GRANIAN_RUNTIME_MODE : Runtime mode: auto, mt, st (default: mt for >8 workers, else st)
# GRANIAN_RUNTIME_THREADS : Runtime threads per worker (default: 1)
# GRANIAN_BLOCKING_THREADS : Blocking threads per worker (default: 1)
# GRANIAN_HTTP : HTTP version: auto, 1, 2 (default: auto)
# GRANIAN_LOOP : Event loop: uvloop, asyncio, rloop (default: uvloop)
# GRANIAN_TASK_IMPL : Task implementation: asyncio, rust (default: auto-detect)
# GRANIAN_HTTP1_PIPELINE_FLUSH : Enable HTTP/1 pipeline flush (default: true)
# GRANIAN_HTTP1_BUFFER_SIZE : HTTP/1 buffer size in bytes (default: 524288)
# GRANIAN_BACKLOG : Connection backlog (default: 2048)
# GRANIAN_BACKPRESSURE : Max concurrent requests per worker (default: 512)
# GRANIAN_RESPAWN_FAILED : Respawn failed workers (default: true)
# GRANIAN_DEV_MODE : Enable hot reload (default: false, requires granian[reload])
# GRANIAN_LOG_LEVEL : Log level: debug, info, warning, error (default: info)
# SSL : Enable TLS/SSL (true/false, default: false)
# CERT_FILE : Path to SSL certificate (default: certs/cert.pem)
# KEY_FILE : Path to SSL private key (default: certs/key.pem)
# FORCE_START : Force start even if another instance is running (default: false)
# DISABLE_ACCESS_LOG : Disable access logging for performance (default: true)
#
# Usage:
# ./run-granian.sh # Run with defaults
# SSL=true ./run-granian.sh # Run with TLS enabled
# GRANIAN_WORKERS=16 ./run-granian.sh # Run with 16 workers
# GRANIAN_HTTP=2 ./run-granian.sh # Force HTTP/2
# GRANIAN_DEV_MODE=true ./run-granian.sh # Run with hot reload
# FORCE_START=true ./run-granian.sh # Force start (bypass lock check)
#
# Tuning Profiles (adjust based on workload):
# # High-throughput (fewer workers, more threads per worker)
# GRANIAN_WORKERS=4 GRANIAN_RUNTIME_THREADS=4 ./run-granian.sh
#
# # High-concurrency (more workers, max backpressure)
# GRANIAN_WORKERS=16 GRANIAN_BACKPRESSURE=1024 GRANIAN_BACKLOG=4096 ./run-granian.sh
#
# # Memory-constrained (fewer workers)
# GRANIAN_WORKERS=2 ./run-granian.sh
#───────────────────────────────────────────────────────────────────────────────
# Exit immediately on error, undefined variable, or pipe failure
set -euo pipefail
#────────────────────────────────────────────────────────────────────────────────
# SECTION 1: Script Location Detection
#────────────────────────────────────────────────────────────────────────────────
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "${SCRIPT_DIR}" || {
echo "❌ FATAL: Cannot change to script directory: ${SCRIPT_DIR}"
exit 1
}
#────────────────────────────────────────────────────────────────────────────────
# SECTION 2: Process Lock Check
#────────────────────────────────────────────────────────────────────────────────
LOCK_FILE="/tmp/mcpgateway-granian.lock"
FORCE_START=${FORCE_START:-false}
check_existing_process() {
if [[ -f "${LOCK_FILE}" ]]; then
local pid
pid=$(<"${LOCK_FILE}")
if kill -0 "${pid}" 2>/dev/null; then
echo "⚠️ WARNING: Another instance of MCP Gateway appears to be running (PID: ${pid})"
if ps -p "${pid}" -o comm= | grep -q granian; then
if [[ "${FORCE_START}" != "true" ]]; then
echo "❌ FATAL: MCP Gateway is already running!"
echo " To stop it: kill ${pid}"
echo " To force start anyway: FORCE_START=true $0"
exit 1
else
echo "⚠️ Force starting despite existing process..."
fi
else
echo "🔧 Lock file exists but process ${pid} is not granian. Cleaning up..."
rm -f "${LOCK_FILE}"
fi
else
echo "🔧 Stale lock file found. Cleaning up..."
rm -f "${LOCK_FILE}"
fi
fi
}
cleanup() {
if [[ -f "${LOCK_FILE}" ]] && [[ "$(<"${LOCK_FILE}")" == "$$" ]]; then
rm -f "${LOCK_FILE}"
echo "🔧 Cleaned up lock file"
fi
}
trap cleanup INT TERM
check_existing_process
echo $$ > "${LOCK_FILE}"
#────────────────────────────────────────────────────────────────────────────────
# SECTION 3: Virtual Environment Activation
#────────────────────────────────────────────────────────────────────────────────
if [[ -z "${VIRTUAL_ENV:-}" ]]; then
if [[ -f "${HOME}/.venv/mcpgateway/bin/activate" ]]; then
echo "🔧 Activating virtual environment: ${HOME}/.venv/mcpgateway"
# shellcheck disable=SC1090
source "${HOME}/.venv/mcpgateway/bin/activate"
elif [[ -f "${SCRIPT_DIR}/.venv/bin/activate" ]]; then
echo "🔧 Activating virtual environment in script directory"
# shellcheck disable=SC1090
source "${SCRIPT_DIR}/.venv/bin/activate"
else
echo "⚠️ WARNING: No virtual environment found!"
echo " Consider creating one with: python3 -m venv ~/.venv/mcpgateway"
fi
else
echo "✓ Virtual environment already active: ${VIRTUAL_ENV}"
fi
#────────────────────────────────────────────────────────────────────────────────
# SECTION 4: Python Interpreter Detection
#────────────────────────────────────────────────────────────────────────────────
if [[ -z "${PYTHON:-}" ]]; then
if [[ -n "${VIRTUAL_ENV:-}" && -x "${VIRTUAL_ENV}/bin/python" ]]; then
PYTHON="${VIRTUAL_ENV}/bin/python"
echo "🐍 Using Python from virtual environment"
else
if command -v python3 &> /dev/null; then
PYTHON="$(command -v python3)"
echo "🐍 Found system Python3: ${PYTHON}"
elif command -v python &> /dev/null; then
PYTHON="$(command -v python)"
echo "🐍 Found system Python: ${PYTHON}"
else
PYTHON=""
fi
fi
fi
if [[ -z "${PYTHON}" ]] || [[ ! -x "${PYTHON}" ]]; then
echo "❌ FATAL: Could not locate a Python interpreter!"
exit 1
fi
PY_VERSION="$("${PYTHON}" --version 2>&1)"
echo "📋 Python version: ${PY_VERSION}"
if ! "${PYTHON}" -c "import sys; sys.exit(0 if sys.version_info[0] >= 3 else 1)" 2>/dev/null; then
echo "❌ FATAL: Python 3.x is required!"
exit 1
fi
#────────────────────────────────────────────────────────────────────────────────
# SECTION 5: Display Application Banner
#────────────────────────────────────────────────────────────────────────────────
cat <<'EOF'
███╗ ███╗ ██████╗██████╗ ██████╗ █████╗ ████████╗███████╗██╗ ██╗ █████╗ ██╗ ██╗
████╗ ████║██╔════╝██╔══██╗ ██╔════╝ ██╔══██╗╚══██╔══╝██╔════╝██║ ██║██╔══██╗╚██╗ ██╔╝
██╔████╔██║██║ ██████╔╝ ██║ ███╗███████║ ██║ █████╗ ██║ █╗ ██║███████║ ╚████╔╝
██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║██╔══██║ ██║ ██╔══╝ ██║███╗██║██╔══██║ ╚██╔╝
██║ ╚═╝ ██║╚██████╗██║ ╚██████╔╝██║ ██║ ██║ ███████╗╚███╔███╔╝██║ ██║ ██║
╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝ ╚══╝╚══╝ ╚═╝ ╚═╝ ╚═╝
⚡ Powered by Granian
EOF
#────────────────────────────────────────────────────────────────────────────────
# SECTION 6: Configure Granian Settings
#────────────────────────────────────────────────────────────────────────────────
# Host and port configuration
HOST=${HOST:-0.0.0.0}
PORT=${PORT:-4444}
# Worker configuration
if [[ -z "${GRANIAN_WORKERS:-}" || "${GRANIAN_WORKERS}" == "auto" ]]; then
if command -v nproc &>/dev/null; then
CPU_COUNT=$(nproc)
elif command -v sysctl &>/dev/null && sysctl -n hw.ncpu &>/dev/null; then
CPU_COUNT=$(sysctl -n hw.ncpu)
else
CPU_COUNT=4
fi
# Granian recommends 1 worker per CPU core (it's more efficient than Gunicorn)
GRANIAN_WORKERS=$((CPU_COUNT > 16 ? 16 : CPU_COUNT))
echo "🔧 Auto-detected CPU cores: ${CPU_COUNT} → Workers: ${GRANIAN_WORKERS}"
fi
# Threading configuration
GRANIAN_RUNTIME_THREADS=${GRANIAN_RUNTIME_THREADS:-1}
GRANIAN_BLOCKING_THREADS=${GRANIAN_BLOCKING_THREADS:-1}
# Runtime mode: auto, mt (multi-threaded), st (single-threaded)
# mt mode scales better with many CPUs (>8 cores)
if [[ -z "${GRANIAN_RUNTIME_MODE:-}" ]]; then
if [[ "${GRANIAN_WORKERS}" -gt 8 ]]; then
GRANIAN_RUNTIME_MODE="mt"
else
GRANIAN_RUNTIME_MODE="st"
fi
fi
# HTTP version: auto, 1, 2
GRANIAN_HTTP=${GRANIAN_HTTP:-auto}
# Event loop: auto, asyncio, uvloop, rloop
# uvloop provides best performance on Linux/macOS (installed via granian[uvloop])
GRANIAN_LOOP=${GRANIAN_LOOP:-uvloop}
# Task implementation: asyncio or rust
# rust provides faster async task scheduling but only works on Python < 3.12
# Auto-detect: use rust on Python < 3.12, asyncio otherwise
if [[ -z "${GRANIAN_TASK_IMPL:-}" ]]; then
PY_MINOR=$("${PYTHON}" -c "import sys; print(sys.version_info.minor)")
if [[ "${PY_MINOR}" -lt 12 ]]; then
GRANIAN_TASK_IMPL="rust"
else
GRANIAN_TASK_IMPL="asyncio"
fi
fi
# HTTP/1 optimizations
GRANIAN_HTTP1_PIPELINE_FLUSH=${GRANIAN_HTTP1_PIPELINE_FLUSH:-true}
GRANIAN_HTTP1_BUFFER_SIZE=${GRANIAN_HTTP1_BUFFER_SIZE:-524288}
# Backlog and backpressure for high concurrency
GRANIAN_BACKLOG=${GRANIAN_BACKLOG:-2048}
GRANIAN_BACKPRESSURE=${GRANIAN_BACKPRESSURE:-512}
# Developer mode with hot reload (requires granian[reload])
GRANIAN_DEV_MODE=${GRANIAN_DEV_MODE:-false}
# Respawn failed workers automatically (recommended for production)
GRANIAN_RESPAWN_FAILED=${GRANIAN_RESPAWN_FAILED:-true}
# Log level
GRANIAN_LOG_LEVEL=${GRANIAN_LOG_LEVEL:-info}
echo "📊 Granian Configuration:"
echo " Host: ${HOST}:${PORT}"
echo " Workers: ${GRANIAN_WORKERS}"
echo " Runtime mode: ${GRANIAN_RUNTIME_MODE}"
echo " Runtime threads per worker: ${GRANIAN_RUNTIME_THREADS}"
echo " Blocking threads: ${GRANIAN_BLOCKING_THREADS}"
echo " HTTP version: ${GRANIAN_HTTP}"
echo " Event loop: ${GRANIAN_LOOP}"
echo " Task implementation: ${GRANIAN_TASK_IMPL}"
echo " HTTP/1 pipeline flush: ${GRANIAN_HTTP1_PIPELINE_FLUSH}"
echo " HTTP/1 buffer size: ${GRANIAN_HTTP1_BUFFER_SIZE}"
echo " Backlog: ${GRANIAN_BACKLOG}"
echo " Backpressure: ${GRANIAN_BACKPRESSURE}"
echo " Respawn failed workers: ${GRANIAN_RESPAWN_FAILED}"
echo " Developer Mode: ${GRANIAN_DEV_MODE}"
echo " Log Level: ${GRANIAN_LOG_LEVEL}"
#────────────────────────────────────────────────────────────────────────────────
# SECTION 7: Configure TLS/SSL Settings
#────────────────────────────────────────────────────────────────────────────────
SSL=${SSL:-false}
CERT_FILE=${CERT_FILE:-certs/cert.pem}
KEY_FILE=${KEY_FILE:-certs/key.pem}
if [[ "${SSL}" == "true" ]]; then
echo "🔐 Configuring TLS/SSL..."
if [[ ! -f "${CERT_FILE}" ]]; then
echo "❌ FATAL: SSL certificate file not found: ${CERT_FILE}"
exit 1
fi
if [[ ! -f "${KEY_FILE}" ]]; then
echo "❌ FATAL: SSL private key file not found: ${KEY_FILE}"
exit 1
fi
echo "✓ TLS enabled - using:"
echo " Certificate: ${CERT_FILE}"
echo " Private Key: ${KEY_FILE}"
else
echo "🔓 Running without TLS (HTTP only)"
fi
#────────────────────────────────────────────────────────────────────────────────
# SECTION 8: Verify Granian Installation
#────────────────────────────────────────────────────────────────────────────────
if ! command -v granian &> /dev/null; then
echo "❌ FATAL: granian command not found!"
echo " Please install it with: pip install 'mcpgateway[granian]'"
echo " Or: pip install granian"
exit 1
fi
GRANIAN_VERSION=$(granian --version 2>&1 || echo "unknown")
echo "✓ Granian found: $(command -v granian) (${GRANIAN_VERSION})"
#────────────────────────────────────────────────────────────────────────────────
# SECTION 9: Launch Granian Server
#────────────────────────────────────────────────────────────────────────────────
echo "🚀 Starting Granian server..."
echo "─────────────────────────────────────────────────────────────────────"
# Build command array with performance-optimized settings
cmd=(
granian
--interface asgi
--host "${HOST}"
--port "${PORT}"
--workers "${GRANIAN_WORKERS}"
--runtime-mode "${GRANIAN_RUNTIME_MODE}"
--runtime-threads "${GRANIAN_RUNTIME_THREADS}"
--blocking-threads "${GRANIAN_BLOCKING_THREADS}"
--loop "${GRANIAN_LOOP}"
--task-impl "${GRANIAN_TASK_IMPL}"
--http "${GRANIAN_HTTP}"
--http1-buffer-size "${GRANIAN_HTTP1_BUFFER_SIZE}"
--backlog "${GRANIAN_BACKLOG}"
--backpressure "${GRANIAN_BACKPRESSURE}"
--log-level "${GRANIAN_LOG_LEVEL}"
)
# HTTP/1 pipeline flush (experimental - aggregates flushes for pipelined responses)
if [[ "${GRANIAN_HTTP1_PIPELINE_FLUSH}" == "true" ]]; then
cmd+=( --http1-pipeline-flush )
fi
# Process naming (optional - requires granian[pname] and setproctitle)
if "${PYTHON}" -c "import setproctitle" 2>/dev/null; then
cmd+=( --process-name "mcpgateway" )
echo "✓ Process naming enabled"
fi
# WebSocket support (enabled by default)
cmd+=( --ws )
# Respawn failed workers (recommended for production)
if [[ "${GRANIAN_RESPAWN_FAILED}" == "true" ]]; then
cmd+=( --respawn-failed-workers )
fi
# Access logging
DISABLE_ACCESS_LOG=${DISABLE_ACCESS_LOG:-true}
if [[ "${DISABLE_ACCESS_LOG}" == "true" ]]; then
cmd+=( --no-access-log )
echo "🚫 Access logging disabled for performance"
else
cmd+=( --access-log )
fi
# Developer mode with hot reload (requires granian[reload])
if [[ "${GRANIAN_DEV_MODE}" == "true" ]]; then
cmd+=( --reload )
echo "🔧 Developer mode enabled - hot reload active"
# In dev mode, reduce workers for better debugging
if [[ "${GRANIAN_WORKERS}" -gt 2 ]]; then
echo " Reducing workers to 2 for developer mode (was ${GRANIAN_WORKERS})"
# Update workers in command array
for i in "${!cmd[@]}"; do
if [[ "${cmd[$i]}" == "--workers" ]]; then
cmd[$((i+1))]=2
break
fi
done
fi
fi
# SSL/TLS configuration
if [[ "${SSL}" == "true" ]]; then
cmd+=( --ssl-certificate "${CERT_FILE}" --ssl-keyfile "${KEY_FILE}" )
fi
# Add the application module (Granian uses module:app format)
cmd+=( "mcpgateway.main:app" )
# Display final command for debugging
echo "📋 Command: ${cmd[*]}"
echo "─────────────────────────────────────────────────────────────────────"
# Launch Granian
trap - EXIT
exec "${cmd[@]}"
