Skip to content

Deployment & Operations

Jump to bottom
github-actions[bot] edited this page Jun 15, 2026 · 2 revisions

Deployment & Operations

**Referenced Files in This Document** - [compose.yaml](file://compose.yaml) - [Dockerfile](file://Dockerfile) - [Dockerfile.dev](file://Dockerfile.dev) - [scripts/env/create-env.sh](file://scripts/env/create-env.sh) - [scripts/deploy-generate-dev-secrets.py](file://scripts/deploy-generate-dev-secrets.py) - [scripts/deploy-dev-cli-ready.sh](file://scripts/deploy-dev-cli-ready.sh) - [helm/README.md](file://helm/README.md) - [helm/kairos-mcp/Chart.yaml](file://helm/kairos-mcp/Chart.yaml) - [helm/kairos-mcp/values.yaml](file://helm/kairos-mcp/values.yaml) - [helm/values.dev.yaml](file://helm/values.dev.yaml) - [helm/values.prod.yaml](file://helm/values.prod.yaml) - [helm/prerequisites/install-keycloak-operator.sh](file://helm/prerequisites/install-keycloak-operator.sh) - [helm/prerequisites/install-pg-operator.sh](file://helm/prerequisites/install-pg-operator.sh) - [helm/prerequisites/install-redis-operator.sh](file://helm/prerequisites/install-redis-operator.sh) - [helm/prerequisites/install-ngrok-operator.sh](file://helm/prerequisites/install-ngrok-operator.sh) - [helm/.dev/helm-deploy.sh](file://helm/.dev/helm-deploy.sh) - [helm/.dev/helm-update.sh](file://helm/.dev/helm-update.sh) - [helm/kairos-mcp/templates/operator-precheck-configmap.yaml](file://helm/kairos-mcp/templates/operator-precheck-configmap.yaml) - [helm/kairos-mcp/templates/operator-precheck-job.yaml](file://helm/kairos-mcp/templates/operator-precheck-job.yaml) - [helm/kairos-mcp/templates/gateway.yaml](file://helm/kairos-mcp/templates/gateway.yaml) - [helm/kairos-mcp/templates/_helpers.tpl](file://helm/kairos-mcp/templates/_helpers.tpl) - [helm/kairos-mcp/templates/kairos-mcp-deployment.yaml](file://helm/kairos-mcp/templates/kairos-mcp-deployment.yaml)

Update Summary

Changes Made

  • Updated Helm chart configurations with gateway security improvements and dependency management updates
  • Added operator precheck configuration and explicit Gateway API default fields
  • Updated image tags to 4.6.3 in Chart.yaml
  • Enhanced security context configurations with improved PodSecurity standards

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document provides comprehensive deployment and operations guidance for KAIROS MCP across Docker Compose and Kubernetes/Helm environments. It covers minimal and full stack deployments, environment configuration, secret management, scaling parameters, monitoring, container orchestration, service discovery, and operational procedures. It also includes troubleshooting steps for common deployment issues.

Project Structure

KAIROS MCP provides two primary deployment paths:

  • Docker Compose for local and simple deployments with optional profiles for full stack and UI.
  • Kubernetes/Helm for production-grade deployments with operator-driven infrastructure provisioning, gateway configuration, and monitoring.
graph TB
subgraph "Docker Compose"
C1["compose.yaml"]
D1["Dockerfile"]
D2["Dockerfile.dev"]
E1["scripts/env/create-env.sh"]
E2["scripts/deploy-generate-dev-secrets.py"]
end
subgraph "Helm"
H1["helm/README.md"]
H2["helm/kairos-mcp/Chart.yaml"]
H3["helm/kairos-mcp/values.yaml"]
H4["helm/values.dev.yaml"]
H5["helm/values.prod.yaml"]
P1["helm/prerequisites/install-keycloak-operator.sh"]
P2["helm/prerequisites/install-pg-operator.sh"]
P3["helm/prerequisites/install-redis-operator.sh"]
P4["helm/prerequisites/install-ngrok-operator.sh"]
F1["helm/.dev/helm-deploy.sh"]
F2["helm/.dev/helm-update.sh"]
OP1["Operator Precheck ConfigMap"]
OP2["Operator Precheck Job"]
GW["Gateway Configuration"]
SEC["Security Context Enhancements"]
end
C1 --> D1
C1 --> D2
E1 --> E2
H1 --> H2
H1 --> H3
H1 --> H4
H1 --> H5
H2 --> H3
H3 --> H4
H3 --> H5
P1 --> H3
P2 --> H3
P3 --> H3
P4 --> H3
F1 --> H3
F2 --> H3
OP1 --> H3
OP2 --> H3
GW --> H3
SEC --> H3
Loading

Diagram sources

  • compose.yaml:1-183
  • Dockerfile:1-76
  • Dockerfile.dev:1-68
  • scripts/env/create-env.sh:1-12
  • scripts/deploy-generate-dev-secrets.py:1-181
  • helm/README.md:1-18
  • helm/kairos-mcp/Chart.yaml:1-23
  • helm/kairos-mcp/values.yaml:1-279
  • helm/values.dev.yaml:1-83
  • helm/values.prod.yaml:1-94
  • helm/prerequisites/install-keycloak-operator.sh:1-17
  • helm/prerequisites/install-pg-operator.sh:1-16
  • helm/prerequisites/install-redis-operator.sh:1-16
  • helm/prerequisites/install-ngrok-operator.sh:1-38
  • helm/.dev/helm-deploy.sh:1-242
  • helm/.dev/helm-update.sh:1-15
  • helm/kairos-mcp/templates/operator-precheck-configmap.yaml:1-46
  • helm/kairos-mcp/templates/operator-precheck-job.yaml:1-42
  • helm/kairos-mcp/templates/gateway.yaml:1-46
  • helm/kairos-mcp/templates/kairos-mcp-deployment.yaml:72-81

Section sources

  • compose.yaml:1-183
  • helm/README.md:1-18

Core Components

  • Application container image and health checks configured in Dockerfiles.
  • Docker Compose services for Qdrant, optional Valkey/RedisInsight, Postgres, Keycloak, and the MCP application.
  • Helm chart for Kubernetes with configurable profiles and operator-driven infrastructure.
  • Scripts for environment generation, operator installation, and local Helm development.
  • Enhanced security contexts with improved PodSecurity standards and runtime defaults.

Section sources

  • Dockerfile:1-76
  • Dockerfile.dev:1-68
  • compose.yaml:10-183
  • helm/kairos-mcp/Chart.yaml:6
  • helm/kairos-mcp/values.yaml:1-279

Architecture Overview

High-level deployment architectures for Docker Compose and Kubernetes/Helm:

graph TB
subgraph "Docker Compose"
A1["App (mcp)"]
A2["Qdrant"]
A3["Valkey (optional)"]
A4["Postgres (optional)"]
A5["Keycloak (optional)"]
A6["RedisInsight (optional)"]
A1 --- A2
A1 --- A3
A5 --- A4
A6 --- A3
end
subgraph "Kubernetes/Helm"
B1["KAIROS MCP App"]
B2["Qdrant"]
B3["Valkey/RedisFailover"]
B4["PostgresCluster"]
B5["KeycloakInstance"]
B6["Gateway (ngrok/Traefik)"]
B7["Monitoring (ServiceMonitors/PrometheusRule)"]
B8["Operator Precheck"]
B9["Enhanced Security Context"]
B1 --- B2
B1 --- B3
B5 --- B4
B6 --> B1
B6 --> B5
B7 -.-> B1
B7 -.-> B2
B7 -.-> B3
B7 -.-> B4
B7 -.-> B5
B8 --> B1
B9 --> B1
end
Loading

Diagram sources

  • compose.yaml:10-183
  • helm/kairos-mcp/values.yaml:123-279
  • helm/values.dev.yaml:13-83
  • helm/values.prod.yaml:10-94
  • helm/kairos-mcp/templates/operator-precheck-configmap.yaml:1-46
  • helm/kairos-mcp/templates/kairos-mcp-deployment.yaml:72-81

Detailed Component Analysis

Docker Compose Deployment

  • Minimal stack: Qdrant + application.
  • Full stack: adds Valkey, Postgres, Keycloak; optional UI via RedisInsight.
  • Profiles:
    • Default (minimal): no profile flag.
    • Full stack: --profile fullstack.
    • Optional UI: --profile infra-ui (requires fullstack).
  • Environment and secrets:
    • .env is required for full stack; generated from a template with scripts.
    • KEY_VALUE_STORE_PASSWORD (or REDIS_PASSWORD) is mandatory for Valkey in full stack.
    • QDRANT_API_KEY is mandatory for Qdrant.
  • Volumes:
    • Named volumes for persistent data (Valkey, Qdrant, Postgres, RedisInsight).
    • Snapshot volume mounted for application backups.
  • Networking:
    • Services communicate over a single bridge network.
flowchart TD
Start(["Start Compose"]) --> ChooseProfile{"Profile?"}
ChooseProfile --> |None| Mini["Minimal: app + qdrant"]
ChooseProfile --> |"fullstack"| Full["Full Stack: app + qdrant + valkey + postgres + keycloak"]
ChooseProfile --> |"infra-ui"| UI["Optional UI: redisinsight"]
Mini --> EnvCheck["Load .env if present"]
Full --> EnvCheck
UI --> Full
EnvCheck --> Secrets{"Required secrets present?"}
Secrets --> |No| Abort["Abort startup"]
Secrets --> |Yes| Up["Start services with healthchecks"]
Up --> Done(["Ready"])
Loading

Diagram sources

  • compose.yaml:4-8
  • compose.yaml:10-183
  • scripts/env/create-env.sh:1-12
  • scripts/deploy-generate-dev-secrets.py:126-176

Section sources

  • compose.yaml:4-8
  • compose.yaml:10-183
  • scripts/env/create-env.sh:1-12
  • scripts/deploy-generate-dev-secrets.py:126-176

Kubernetes/Helm Deployment

  • Chart layout and quick start:
    • Operators, infrastructure, and application chart are organized under helm/.
    • Operators and ngrok infrastructure bootstrap are applied first.
  • Helm values overlays:
    • values.dev.yaml: local development with ngrok, optional Keycloak realm import, embedded Ollama.
    • values.prod.yaml: production overlay with HPA, resource requests/limits, and monitoring disabled by default.
  • Application configuration:
    • Image repository/tag, ports, auth realm/client/callback base URL, embedding provider configuration, and extra environment variables.
    • Horizontal Pod Autoscaling (HPA) and Vertical Pod Autoscaling (VPA) supported.
  • Infrastructure operators:
    • Keycloak, Postgres, Redis, and ngrok operators installed via OLM or scripts.
  • Gateway configuration:
    • GatewayClass "ngrok" is used; routes for MCP and Keycloak are configurable.
    • Enhanced with explicit Gateway API default fields and improved security contexts.
  • Monitoring:
    • ServiceMonitors and PrometheusRule are configurable; defaults disabled.
  • Operator Precheck:
    • New precheck configuration validates required CRDs before installation.
    • Automatic validation of Redis, Keycloak, and PostgreSQL operator availability.
sequenceDiagram
participant Ops as "Operator"
participant Helm as "Helm Release"
participant Precheck as "Operator Precheck"
participant App as "KAIROS MCP App"
participant Infra as "Infra Operators"
Ops->>Infra : Install Keycloak/PG/Redis/ngrok operators
Helm->>Precheck : Validate CRDs via ConfigMap/Job
Precheck-->>Helm : CRD validation results
Helm->>Infra : Provision PostgresCluster, Valkey/RedisFailover, Qdrant
Helm->>Helm : Apply Gateway (ngrok) with enhanced security
Helm->>App : Deploy MCP with improved security contexts
App-->>Helm : Health checks succeed
Loading

Diagram sources

  • helm/README.md:1-18
  • helm/kairos-mcp/values.yaml:176-279
  • helm/values.dev.yaml:13-83
  • helm/values.prod.yaml:10-94
  • helm/kairos-mcp/templates/operator-precheck-configmap.yaml:1-46
  • helm/kairos-mcp/templates/operator-precheck-job.yaml:1-42

Section sources

  • helm/README.md:1-18
  • helm/kairos-mcp/Chart.yaml:1-23
  • helm/kairos-mcp/values.yaml:1-279
  • helm/values.dev.yaml:1-83
  • helm/values.prod.yaml:1-94

Environment Configuration and Secret Management

  • Development:
    • Generate .env from template using Python script; supports verification and regeneration.
    • Creates secrets for embedding provider and optional Keycloak realm import.
  • Production:
    • Use Helm values overlays to reference existing secrets for embedding and configure OIDC groups allowlist.
    • Configure resource requests/limits and enable HPA/VPA for autoscaling.
flowchart TD
A["Start"] --> B["Check .env presence"]
B --> |Missing| C["Run create-env.sh"]
C --> D["deploy-generate-dev-secrets.py"]
D --> E{"Verify required keys"}
E --> |Pass| F["Proceed with deployment"]
E --> |Fail| G["Fix missing keys"]
F --> H["Helm values overlay"]
H --> I["Existing secrets or generated"]
I --> J["Deploy"]
Loading

Diagram sources

  • scripts/env/create-env.sh:1-12
  • scripts/deploy-generate-dev-secrets.py:126-176
  • helm/values.prod.yaml:42-47

Section sources

  • scripts/env/create-env.sh:1-12
  • scripts/deploy-generate-dev-secrets.py:126-176
  • helm/values.prod.yaml:42-47

Scaling Parameters

  • Kubernetes:
    • replicaCount for MCP app.
    • HPA with min/max replicas and CPU utilization target.
    • VPA for automatic resource tuning.
  • Docker Compose:
    • Not applicable; scale via external orchestrator or reverse proxy.

Section sources

  • helm/kairos-mcp/values.yaml:73-87
  • helm/values.prod.yaml:37-41

Monitoring Setup

  • ServiceMonitors and PrometheusRule are configurable under monitoring.
  • Defaults are disabled; enable and align with your Prometheus Operator installation.

Section sources

  • helm/kairos-mcp/values.yaml:245-279

Container Orchestration, Service Discovery, and Network Configuration

  • Docker Compose:
    • Bridge network for service communication.
    • Health checks for readiness.
  • Kubernetes:
    • GatewayClass "ngrok" with HTTPRoute/ReferenceGrant for routing.
    • Service discovery via Kubernetes DNS; MCP and Keycloak exposed via Gateway.
    • Enhanced security contexts with improved PodSecurity standards.

Section sources

  • compose.yaml:173-183
  • helm/kairos-mcp/values.yaml:88-122
  • helm/values.dev.yaml:41-59
  • helm/values.prod.yaml:53-71

Enhanced Security Contexts

  • Improved PodSecurity standards with runtime defaults and enhanced security configurations.
  • MCP application deployment includes comprehensive securityContext settings:
    • runAsNonRoot: true
    • runAsUser: 1000
    • allowPrivilegeEscalation: false
    • readOnlyRootFilesystem: true
    • capabilities: drop ALL
    • seccompProfile: RuntimeDefault
  • Operator precheck jobs also implement security best practices with restricted privileges.

Section sources

  • helm/kairos-mcp/templates/kairos-mcp-deployment.yaml:72-81
  • helm/kairos-mcp/templates/operator-precheck-job.yaml:24-32

Operator Precheck Configuration

  • New precheck system validates required CRDs before Helm installation.
  • ConfigMap-based precheck defines environment variables for Redis, Keycloak, and PostgreSQL checks.
  • Job-based execution runs kubectl commands to verify CRD availability.
  • Automatic cleanup of precheck resources after successful validation.

Section sources

  • helm/kairos-mcp/templates/operator-precheck-configmap.yaml:1-46
  • helm/kairos-mcp/templates/operator-precheck-job.yaml:1-42

Gateway Security Improvements

  • Enhanced Gateway API configuration with explicit default fields.
  • Improved security context for gateway components.
  • Better integration with ngrok operator and enhanced TLS handling.
  • Explicit hostname and port configurations for improved reliability.

Section sources

  • helm/kairos-mcp/templates/gateway.yaml:1-46
  • helm/kairos-mcp/templates/_helpers.tpl:1-59

Operational Procedures

  • Local development:
    • Build CLI, configure Keycloak realms, login via browser, and run a search test.
  • Helm development:
    • Single entry point script installs operators, provisions infrastructure, and deploys chart with staged values.
    • Update script for quick upgrades with wait and timeout.
  • Enhanced precheck procedures ensure operator readiness before deployment.

Section sources

  • scripts/deploy-dev-cli-ready.sh:1-24
  • helm/.dev/helm-deploy.sh:1-242
  • helm/.dev/helm-update.sh:1-15

Dependency Analysis

  • Docker Compose:
    • App depends on Qdrant; optional dependencies on Valkey, Postgres, Keycloak; optional UI depends on Valkey.
  • Kubernetes/Helm:
    • Chart depends on upstream Qdrant and Valkey Helm charts.
    • Operators provision PostgresCluster, RedisFailover, and Keycloak CRDs.
    • Enhanced with operator precheck dependencies for improved reliability.
graph LR
App["KAIROS MCP App"] --> Qdr["Qdrant"]
App --> R["Valkey/RedisFailover"]
KC["Keycloak"] --> PG["PostgresCluster"]
GW["Gateway (ngrok)"] --> App
GW --> KC
OP["Operator Precheck"] --> App
OP --> KC
OP --> PG
Loading

Diagram sources

  • compose.yaml:10-183
  • helm/kairos-mcp/Chart.yaml:14-23
  • helm/kairos-mcp/values.yaml:123-201
  • helm/kairos-mcp/templates/operator-precheck-configmap.yaml:1-46

Section sources

  • compose.yaml:10-183
  • helm/kairos-mcp/Chart.yaml:14-23
  • helm/kairos-mcp/values.yaml:123-201

Performance Considerations

  • Qdrant memory tuning and logging level are configurable in Docker Compose.
  • Kubernetes values include HPA and VPA for dynamic scaling and resource optimization.
  • Embedding provider selection impacts latency and throughput; configure accordingly.
  • Enhanced security contexts may have minor performance overhead but provide significantly improved security posture.

Section sources

  • compose.yaml:67-70
  • helm/kairos-mcp/values.yaml:73-87
  • helm/values.dev.yaml:30-37
  • helm/values.prod.yaml:42-47

Troubleshooting Guide

  • Docker Compose
    • Missing secrets: ensure KEY_VALUE_STORE_PASSWORD/REDIS_PASSWORD, QDRANT_API_KEY, and other required keys are set in .env.
    • Health checks failing: verify service ports and readiness endpoints.
    • Volume permissions: confirm named volumes exist and are writable.
  • Kubernetes/Helm
    • Operator installation: ensure CRDs are established and namespaces are correctly targeted.
    • Gateway not ready: verify GatewayClass acceptance and route configuration.
    • Missing embedding secret: when Ollama is not enabled, ensure kairos-mcp-embedding secret is created with OPENAI_API_KEY.
    • Local dev script failures: confirm CLI build, Keycloak realm configuration, and successful login/search.
    • Operator precheck failures: verify that required CRDs are installed before Helm deployment.
    • Security context issues: ensure cluster supports RuntimeDefault seccomp profiles and non-root user requirements.

Section sources

  • compose.yaml:16-19
  • compose.yaml:66
  • helm/prerequisites/install-keycloak-operator.sh:14
  • helm/prerequisites/install-pg-operator.sh:15
  • helm/prerequisites/install-redis-operator.sh:15
  • helm/prerequisites/install-ngrok-operator.sh:36
  • helm/.dev/helm-deploy.sh:214-233
  • scripts/deploy-dev-cli-ready.sh:18-22
  • helm/kairos-mcp/templates/operator-precheck-configmap.yaml:39-43

Conclusion

KAIROS MCP supports straightforward deployments via Docker Compose for local and simple environments and robust Kubernetes/Helm deployments for production with operator-driven infrastructure, gateway routing, and monitoring. Recent enhancements include improved security contexts, operator precheck validation, and enhanced gateway configurations. Proper environment configuration, secret management, and scaling parameters are essential for reliable operations.

Appendices

  • Docker Compose
    • Minimal: docker compose -p kairos-mcp up -d
    • Full stack: docker compose -p kairos-mcp --profile fullstack up -d
    • Optional UI: docker compose -p kairos-mcp --profile fullstack --profile infra-ui up -d
  • Kubernetes/Helm
    • Quick start: apply operators and infrastructure, then install the chart with desired overlay.
    • Development: use helm/.dev/helm-deploy.sh for staged setup and upgrades.
    • Enhanced security: ensure cluster supports RuntimeDefault seccomp profiles and non-root user requirements.
    • Precheck validation: operator precheck automatically verifies CRD availability before deployment.

Section sources

  • compose.yaml:4-8
  • helm/README.md:9-18
  • helm/.dev/helm-deploy.sh:1-242
  • helm/kairos-mcp/templates/operator-precheck-configmap.yaml:1-46
  • helm/kairos-mcp/templates/kairos-mcp-deployment.yaml:72-81

Clone this wiki locally