feat: Add metrics server

Dockerfile

@@ -39,7 +39,7 @@ RUN mkdir -p $BIN_DIR \
   && mkdir -p $DATA_DIR \
   && mkdir -p $DATA_DIR/logs
 
-COPY entrypoint.py pyproject.toml uv.lock README.md $APP_DIR/
+COPY entrypoint.py pyproject.toml uv.lock README.md alembic.ini $APP_DIR/
 COPY webhook_server $APP_DIR/webhook_server/
 COPY scripts $APP_DIR/scripts/
 

alembic.ini

@@ -0,0 +1,94 @@
+# Alembic configuration for GitHub Webhook Server metrics database
+# See: https://alembic.sqlalchemy.org/en/latest/tutorial.html
+
+[alembic]
+# Path to migration scripts directory
+script_location = webhook_server/migrations
+
+# Template used to generate migration files
+# %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
+# Example: 20250123_1430_abc123def456_add_metrics_table
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
+
+# Prepends given value to alembic.script_location
+# prepend_sys_path = .
+
+# Timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python-dateutil library.
+# timezone = UTC
+
+# Max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# Set to 'true' to run the environment during the 'revision' command
+# revision_environment = false
+
+# Set to 'true' to allow .pyc and .pyo files without a .py file to be detected
+# sourceless = false
+
+# Version table name - should match across all databases
+version_table = alembic_version
+
+# Version location specification
+# Determines where Alembic stores version information
+# IMPORTANT: This value is OVERRIDDEN dynamically in env.py
+# env.py sets version_locations based on WEBHOOK_SERVER_DATA_DIR environment variable
+# Default: {WEBHOOK_SERVER_DATA_DIR}/migrations/versions
+# Container default: /home/podman/data/migrations/versions
+# This placeholder is kept for reference only - actual path is set in env.py
+version_locations = migrations/versions
+
+# Version path separator (used if version_locations is specified)
+# version_path_separator = os  # Use os.pathsep. Default is ':'
+
+# Database URL - loaded dynamically from config.yaml via env.py
+# IMPORTANT: Do NOT set sqlalchemy.url here - it's loaded from config.yaml
+# sqlalchemy.url =
+
+# Logging configuration for Alembic migrations
+# This section controls Alembic's own logging during migration operations
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S
+
+# Metrics-specific sections
+# These are custom sections for webhook server metrics feature
+
+[metrics]
+# Feature flags for metrics migration
+enable_postgres = true
+
+# Migration behavior configuration
+auto_migrate_on_startup = false
+validate_schema_on_startup = true

entrypoint.py

@@ -1,4 +1,5 @@
 import asyncio
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -41,10 +42,66 @@ def run_podman_cleanup() -> None:
         print(f"ℹ️  Podman cleanup script not found at {cleanup_script}")
 
 
+def run_database_migrations() -> None:
+    """Run Alembic database migrations.
+
+    Only runs if ENABLE_METRICS_SERVER environment variable is set to "true".
+    Applies pending migrations with 'alembic upgrade head'.
+
+    Note: Migrations must be generated manually by developers:
+        alembic revision --autogenerate -m "Description"
+
+    Raises:
+        SystemExit: If migration fails (fail-fast behavior)
+    """
+    metrics_enabled = os.environ.get("ENABLE_METRICS_SERVER") == "true"
+
+    if not metrics_enabled:
+        print("ℹ️  Metrics server disabled - skipping database migrations")
+        return
+
+    try:
+        alembic_ini = Path(__file__).parent / "alembic.ini"
+        versions_dir = Path(_config.data_dir) / "migrations" / "versions"
+
+        # Ensure versions directory exists (required for Alembic)
+        versions_dir.mkdir(parents=True, exist_ok=True)
+
+        print("⬆️  Applying database migrations...")
+        result = subprocess.run(
+            ["uv", "run", "alembic", "-c", str(alembic_ini), "upgrade", "head"],
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=60,
+            cwd=Path(__file__).parent,
+        )
+        print(result.stdout)
+        if result.stderr:
+            print(result.stderr, file=sys.stderr)
+        print("✅ Database migrations completed successfully")
+    except subprocess.CalledProcessError as e:
+        print(f"❌ FATAL: Database migration failed: {e}", file=sys.stderr)
+        if e.stdout:
+            print(f"stdout: {e.stdout}", file=sys.stderr)
+        if e.stderr:
+            print(f"stderr: {e.stderr}", file=sys.stderr)
+        sys.exit(1)
+    except subprocess.TimeoutExpired:
+        print("❌ FATAL: Database migration timed out after 60 seconds", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"❌ FATAL: Unexpected error during database migration: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
 if __name__ == "__main__":
     # Run Podman cleanup before starting the application
     run_podman_cleanup()
 
+    # Run database migrations if metrics server is enabled
+    run_database_migrations()
+
     result = asyncio.run(repository_and_webhook_settings(webhook_secret=_webhook_secret))
 
     # Logging Configuration:

eslint.config.js

@@ -4,7 +4,7 @@ module.exports = [
     files: ["webhook_server/web/static/**/*.js"],
     languageOptions: {
       ecmaVersion: 2022,
-      sourceType: "script",
+      sourceType: "module",
       globals: {
         // Browser environment globals
         window: "readonly",
@@ -23,6 +23,12 @@ module.exports = [
         clearInterval: "readonly",
         URLSearchParams: "readonly",
         AbortController: "readonly",
+        URL: "readonly",
+        Blob: "readonly",
+        // CommonJS globals for conditional exports
+        module: "readonly",
+        // Chart.js global
+        Chart: "readonly",
       },
     },
     rules: {

examples/config.yaml

@@ -4,8 +4,36 @@ log-level: INFO # Set global log level, change take effect immediately without s
 log-file: webhook-server.log # Set global log file, change take effect immediately without server restart
 mcp-log-file: mcp_server.log # Set global MCP log file, change take effect immediately without server restart
 logs-server-log-file: logs_server.log # Set global Logs Server log file, change take effect immediately without server restart
+metrics-server-log-file: metrics_server.log # Set global Metrics Server log file, change take effect immediately without server restart
 mask-sensitive-data: true # Mask sensitive data in logs (default: true). Set to false for debugging (NOT recommended in production)
 
+# Metrics Server Configuration (requires ENABLE_METRICS_SERVER=true environment variable)
+# Provides PostgreSQL-based historical analytics and AI-powered natural language queries
+# NOTE: For docker-compose deployments, use service name as hostname:
+#   - metrics-database host: github-webhook-server-postgres (defined in examples/docker-compose.yaml)
+#
+# ⚠️  SECURITY WARNING - TRUSTED NETWORK ONLY ⚠️
+# The metrics dashboard and API endpoints (/api/v1/metrics/*) are UNAUTHENTICATED.
+# These endpoints expose sensitive webhook data including user activity and repository statistics.
+# REQUIREMENTS:
+#   - Deploy ONLY on trusted/private networks (VPN, internal network, localhost)
+#   - NEVER expose metrics endpoints directly to the public internet
+#   - Use a reverse proxy with authentication (OAuth, API keys) for external access
+#   - Enable SSL/TLS connections to PostgreSQL (sslmode=require) in production
+metrics-database:
+  host: localhost  # PostgreSQL server hostname (use 'github-webhook-server-postgres' in docker-compose)
+  port: 5432  # PostgreSQL server port
+  database: webhook_metrics  # Database name for metrics
+  username: webhook_user  # Database username
+  password: <DATABASE_PASSWORD>  # Database password
+  pool-size: 20  # Connection pool size (default: 20)
+
+# AI Query Configuration (optional - enables natural language queries in dashboard)
+# Requires a valid Gemini API key - set ai-query-enabled to true only after configuring the key
+# WARNING: Enabling ai-query-enabled without a valid gemini-api-key will cause AI query failures
+gemini-api-key: <GEMINI_API_KEY>  # Google Gemini API key for AI queries
+ai-query-enabled: false  # Enable AI-powered queries (default: false, requires valid API key)
+
 # Server configuration
 disable-ssl-warnings: true # Disable SSL warnings (useful in production to reduce log noise from SSL certificate issues)
 

examples/docker-compose.yaml

@@ -1,4 +1,34 @@
+# ⚠️  SECURITY WARNING - TRUSTED NETWORK ONLY ⚠️
+# The metrics dashboard and API endpoints (/api/v1/metrics/*) are UNAUTHENTICATED.
+# These endpoints expose sensitive webhook data including user activity and repository statistics.
+# REQUIREMENTS:
+#   - Deploy ONLY on trusted/private networks (VPN, internal network, localhost)
+#   - NEVER expose metrics endpoints directly to the public internet
+#   - Use a reverse proxy with authentication (OAuth, API keys) for external access
+#   - Consider using Docker network isolation to restrict access to metrics endpoints
+
 services:
+  # PostgreSQL database for metrics storage
+  github-webhook-server-postgres:
+    image: postgres:16-alpine
+    container_name: github-webhook-server-postgres
+    environment:
+      - POSTGRES_DB=webhook_metrics
+      - POSTGRES_USER=webhook_user
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}  # Set POSTGRES_PASSWORD in .env or environment
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    ports:
+      # Bind to localhost only - prevents external network access to database
+      # For production, consider removing ports entirely and using Docker network only
+      - "127.0.0.1:5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U webhook_user -d webhook_metrics"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
   github-webhook-server:
     container_name: github-webhook-server
     build: ghcr.io/myk-org/github-webhook-server:latest
@@ -18,7 +48,15 @@ services:
       - VERIFY_CLOUDFLARE_IPS=1 # Verify hook request is from Cloudflare IPs
       - ENABLE_LOG_SERVER=true # Enable log viewer endpoints (default: false)
       - ENABLE_MCP_SERVER=false # Enable MCP server for AI agent integration (default: false)
+      - ENABLE_METRICS_SERVER=true # Enable metrics server with PostgreSQL (default: false)
     ports:
       - "5000:5000"
     privileged: true
+    depends_on:
+      github-webhook-server-postgres:
+        condition: service_healthy
     restart: unless-stopped
+
+volumes:
+  postgres-data:
+    driver: local

pyproject.toml

@@ -18,7 +18,7 @@ output-format = "grouped"
 select = ["E", "F", "W", "I", "B", "UP", "PLC0415", "ARG", "RUF059"]
 
 [tool.ruff.lint.per-file-ignores]
-"webhook_server/tests/*" = ["ARG"]
+"webhook_server/tests/*" = ["ARG", "PLC0415"]
 
 [tool.ruff.format]
 exclude = [".git", ".venv", ".mypy_cache", ".tox", "__pycache__"]
@@ -75,6 +75,11 @@ dependencies = [
   "pydantic>=2.8.0",
   "psutil>=7.0.0",
   "fastapi-mcp>=0.4.0",
+  "asyncpg>=0.29.0",
+  "alembic>=1.13.0",
+  "sqlalchemy[asyncio]>=2.0.0",
+  "google-genai>=0.1.0",
+  "aiosqlite>=0.21.0",
 ]
 
 [[project.authors]]
@@ -90,8 +95,6 @@ homepage = "https://github.com/myakove/github-webhook-server"
 repository = "https://github.com/myakove/github-webhook-server"
 "Bug Tracker" = "https://github.com/myakove/github-webhook-server/issues"
 
-[project.optional-dependencies]
-tests = ["pytest-asyncio>=0.26.0", "pytest-xdist>=3.7.0"]
 
 [build-system]
 requires = ["hatchling"]

tox.toml

@@ -18,7 +18,7 @@ commands = [
   [
     "uv",
     "run",
-    "--extra",
+    "--group",
     "tests",
     "pytest",
     "-n",