Release on new jan-server (#267)

- Consolidated Makefile structure (single file with 10 sections)
- Hybrid development mode for faster iteration
- MCP (Model Context Protocol) provider integration
- Full observability stack (Prometheus, Jaeger, Grafana)
- OpenTelemetry integration
- Guest authentication with Keycloak token exchange
- Comprehensive testing suite with jan-cli api-test
- Documentation for all major features

Author: locnguyen1986

.env.template

@@ -0,0 +1,246 @@
+# ============================================================================
+# Jan Server Environment Configuration Template
+# ============================================================================
+# Copy this file to .env and customize for your environment
+# 
+# Quick Start:
+#   make env-create              # Creates .env from this template
+#   make env-switch ENV=hybrid   # Switch to hybrid development mode
+#
+# Available Environments:
+#   - development  (all services in Docker)      - config/development.env
+#   - hybrid       (native services + Docker)    - config/hybrid.env
+#   - testing      (integration testing)         - config/testing.env
+#   - production   (production deployment)       - config/production.env.example
+#
+# Documentation: See config/README.md for detailed environment guide
+# ============================================================================
+
+# ============================================================================
+# Docker Compose Configuration
+# ============================================================================
+# Profile selection for docker-compose services
+# Profiles are comma-separated and control which services start:
+#   infra - Infrastructure (PostgreSQL, Keycloak, Kong) - always needed
+#   api   - API services (llm-api, media-api, response-api) - always needed
+#   mcp   - MCP Tools and Vector Store - always included
+#   full  - Includes vLLM GPU inference (for local GPU provider)
+# 
+# Examples:
+#   COMPOSE_PROFILES=infra,api,mcp,full  - Local vLLM (full setup with GPU)
+#   COMPOSE_PROFILES=infra,api,mcp       - Remote API provider (no vLLM)
+COMPOSE_PROFILES=infra,api,mcp,full
+
+# ============================================================================
+# REQUIRED: Secrets & API Keys
+# ============================================================================
+# You MUST set these values before running the services
+
+# HuggingFace API token (required for model downloads). The local vLLM provider needs this token.
+# If you plan to use a remote provider instead, comment this out and edit
+# services/llm-api/config/providers.yml to point at the provider you want.
+# Get from: https://huggingface.co/settings/tokens
+HF_TOKEN=your_huggingface_token_here
+
+# Serper API key (required for MCP google_search tool)
+# Get from: https://serper.dev
+SERPER_API_KEY=your_serper_api_key_here
+
+# Security secrets (CHANGE THESE in production!)
+POSTGRES_PASSWORD=jan_password
+KEYCLOAK_ADMIN_PASSWORD=admin
+BACKEND_CLIENT_SECRET=backend-secret
+MODEL_PROVIDER_SECRET=jan-model-provider-secret-2024
+VLLM_INTERNAL_KEY=changeme
+
+# ============================================================================
+# PostgreSQL Database
+# ============================================================================
+POSTGRES_USER=jan_user
+POSTGRES_DB=jan_llm_api
+POSTGRES_PORT=5432
+KEYCLOAK_DB_PORT=5433
+
+# Database connection (varies by environment)
+# Development:  postgres://jan_user:password@api-db:5432/jan_llm_api
+# Hybrid:       postgres://jan_user:password@localhost:5432/jan_llm_api
+DB_DSN=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@api-db:5432/${POSTGRES_DB}?sslmode=disable
+DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@api-db:5432/${POSTGRES_DB}?sslmode=disable
+
+# ============================================================================
+# LLM API Service
+# ============================================================================
+HTTP_PORT=8080
+LOG_LEVEL=info
+LOG_FORMAT=json
+AUTO_MIGRATE=true
+
+# ============================================================================
+# Authentication (Keycloak)
+# ============================================================================
+# Note: JWKS_URL uses internal Docker hostname, ISSUER uses localhost for external clients
+KEYCLOAK_ADMIN=admin
+KEYCLOAK_HTTP_PORT=8085
+KEYCLOAK_REALM=jan
+
+# OAuth/OIDC Configuration (varies by environment)
+# Development (inside Docker): http://keycloak:8085
+# External/Hybrid: set KEYCLOAK_PUBLIC_HOST to your host (e.g., localhost or LAN IP) and KEYCLOAK_PUBLIC_PORT to the exposed port.
+KEYCLOAK_BASE_URL=http://keycloak:8085
+KEYCLOAK_PUBLIC_HOST=localhost
+KEYCLOAK_PUBLIC_PORT=${KEYCLOAK_HTTP_PORT:-8085}
+KEYCLOAK_PUBLIC_URL=http://${KEYCLOAK_PUBLIC_HOST}:${KEYCLOAK_PUBLIC_PORT}
+KEYCLOAK_ADMIN_URL=http://${KEYCLOAK_PUBLIC_HOST}:${KEYCLOAK_PUBLIC_PORT}
+JWKS_URL=http://keycloak:8085/realms/jan/protocol/openid-connect/certs
+ISSUER=${KEYCLOAK_PUBLIC_URL}/realms/${KEYCLOAK_REALM}
+AUDIENCE=account
+REFRESH_JWKS_INTERVAL=5m
+
+# OAuth2 redirect URI (must match Keycloak client configuration)
+# This is where Keycloak redirects after authentication
+OAUTH_REDIRECT_URI=http://localhost:8000/auth/callback
+
+# Guest provisioning
+BACKEND_CLIENT_ID=backend
+TARGET_CLIENT_ID=jan-client
+GUEST_ROLE=guest
+
+# ============================================================================
+# API Gateway (Kong)
+# ============================================================================
+KONG_HTTP_PORT=8000
+
+# ============================================================================
+# Inference (vLLM)
+# ============================================================================
+VLLM_PORT=8101
+VLLM_MODEL=Qwen/Qwen2.5-0.5B-Instruct
+VLLM_SERVED_NAME=qwen2.5-0.5b-instruct
+VLLM_GPU_UTIL=0.66
+VLLM_TOOL_SUPPORT=false
+# Model provider configuration
+JAN_PROVIDER_CONFIGS=true
+JAN_PROVIDER_CONFIGS_FILE=config/providers.yml
+JAN_PROVIDER_CONFIG_SET=default
+# Legacy fallback (single provider) - leave disabled unless needed
+# JAN_DEFAULT_NODE_SETUP=true
+# JAN_DEFAULT_NODE_URL=http://vllm-jan-gpu:8001/v1
+# JAN_DEFAULT_NODE_API_KEY=${VLLM_INTERNAL_KEY}
+
+# ============================================================================
+# MCP Tools Service
+# ============================================================================
+MCP_TOOLS_HTTP_PORT=8091
+
+# Search engine configuration
+SEARCH_ENGINE=serper                 # Options: serper, searxng
+SERPER_DOMAIN_FILTER=                # Optional: domain filter for search results
+SERPER_LOCATION_HINT=                # Optional: location hint for search
+SERPER_OFFLINE_MODE=false            # Set true for offline testing
+
+# MCP Provider URLs (vary by environment)
+# Development:  http://searxng:8080
+# Hybrid:       http://localhost:8086
+SEARXNG_PORT=8086
+SEARXNG_URL=http://searxng:8080
+VECTOR_STORE_PORT=3015
+VECTOR_STORE_URL=http://vector-store:3015
+SANDBOXFUSION_PORT=3010
+SANDBOXFUSION_URL=http://sandboxfusion:3010
+SANDBOX_FUSION_REQUIRE_APPROVAL=true
+MCP_ENABLE_PYTHON_EXEC=true
+MCP_ENABLE_MEMORY_RETRIEVE=true
+
+# Browser automation & code execution
+CODE_SANDBOX_ENABLED=true
+CODE_SANDBOX_URL=http://code-sandbox-mcp:3000/mcp
+PLAYWRIGHT_ENABLED=true
+PLAYWRIGHT_URL=http://playwright-mcp:3000
+
+# MCP debugging
+MCP_PROVIDER_DEBUG=false
+
+# ============================================================================
+# Observability (OpenTelemetry, Prometheus, Jaeger, Grafana)
+# ============================================================================
+OTEL_ENABLED=false                   # Enable telemetry collection
+OTEL_SERVICE_NAME=llm-api
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_HTTP_PORT=4318
+OTEL_GRPC_PORT=4317
+
+# Monitoring stack ports
+PROMETHEUS_PORT=9090
+JAEGER_UI_PORT=16686
+GRAFANA_PORT=3001
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=admin
+
+# ============================================================================
+# Media API Configuration
+# ============================================================================
+MEDIA_API_ENABLED=true
+MEDIA_API_PORT=8285
+MEDIA_SERVICE_KEY=changeme-media-key
+MEDIA_API_KEY=changeme-media-key
+
+# Storage backend selection: "s3" or "local"
+MEDIA_STORAGE_BACKEND=local
+
+# Local Storage Configuration (used when MEDIA_STORAGE_BACKEND=local)
+MEDIA_LOCAL_STORAGE_PATH=./media-data
+MEDIA_LOCAL_STORAGE_BASE_URL=http://localhost:8285/v1/files
+
+# S3 Storage Configuration (used when MEDIA_STORAGE_BACKEND=s3)
+# MEDIA_S3_ENDPOINT=https://s3.menlo.ai
+# MEDIA_S3_PUBLIC_ENDPOINT=
+# MEDIA_S3_REGION=us-west-2
+# MEDIA_S3_BUCKET=platform-dev
+# MEDIA_S3_ACCESS_KEY_ID=7N33WPTUI1KN99MFILQS
+# MEDIA_S3_SECRET_ACCESS_KEY=ppxQsHpnfDSewYZD065aGjQeEQ0nTFA7c2aHNPz5
+# MEDIA_S3_USE_PATH_STYLE=true
+# MEDIA_S3_PRESIGN_TTL=5m
+
+# Media service URLs
+MEDIA_API_URL=http://media-api:8285
+MEDIA_RESOLVE_URL=http://media-api:8285/v1/media/resolve
+MEDIA_RESOLVE_TIMEOUT=5s
+
+# Media processing settings
+MEDIA_MAX_BYTES=20971520
+MEDIA_PROXY_DOWNLOAD=true
+MEDIA_RETENTION_DAYS=30
+MEDIA_REMOTE_FETCH_TIMEOUT=15s
+
+# ============================================================================
+# Template API (copy when running the scaffold locally)
+# ============================================================================
+# TEMPLATE_DATABASE_URL=postgres://postgres:postgres@localhost:5432/template_api?sslmode=disable
+# SERVICE_NAME=template-api
+# ENVIRONMENT=development
+# HTTP_PORT=8185
+# LOG_LEVEL=info
+# ENABLE_TRACING=false
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+# SHUTDOWN_TIMEOUT=10s
+# DB_MAX_IDLE_CONNS=5
+# DB_MAX_OPEN_CONNS=15
+# DB_CONN_MAX_LIFETIME=30m
+# AUTH_ENABLED=false
+# AUTH_ISSUER=http://localhost:8080/realms/jan
+# AUTH_AUDIENCE=account
+# AUTH_JWKS_URL=http://localhost:8080/realms/jan/protocol/openid-connect/certs
+
+# ============================================================================
+# Environment-Specific Overrides
+# ============================================================================
+# The above values work for Docker development (all services in containers)
+# 
+# For other environments, use:
+#   make env-switch ENV=hybrid      # Run services natively
+#   make env-switch ENV=testing     # Integration testing
+#
+# Or manually copy from config/<environment>.env to .env
+#
+# See config/README.md for detailed environment configuration guide
+# ============================================================================