Deployment Guide

This guide covers deploying MIRADOR-CORE in various environments.

Prerequisites

• Kubernetes cluster (v1.19+)

• Helm 3.x

• Docker registry access

• PostgreSQL database

• Valkey cache

• LDAP/AD for authentication (optional)

Quick Start with Helm

# Add the MIRADOR-CORE Helm repository
helm repo add mirador-core https://charts.mirador-core.io
helm repo update

# Install with default configuration
helm install mirador-core mirador-core/mirador-core

# Install with custom values
helm install mirador-core mirador-core/mirador-core \
  --values custom-values.yaml \
  --namespace observability

Configuration

Basic Configuration

# custom-values.yaml
global:
  imageRegistry: "your-registry.com"
  imagePullSecrets:
    - name: registry-secret

config:
  database:
    host: "postgresql.observability.svc.cluster.local"
    port: 5432
    database: "mirador_core"
    username: "mirador_user"

  valkey:
    host: "valkey.observability.svc.cluster.local"
    port: 6379

  auth:
    provider: "ldap"  # ldap, oauth2, or local
    ldap:
      url: "ldaps://ldap.company.com"
      baseDN: "dc=company,dc=com"
      userSearchFilter: "(sAMAccountName=%s)"

  features:
    rca_enabled: true
    predict_enabled: true
    unified_query_enabled: true

Advanced Configuration

# Advanced configuration with resource limits
config:
  metrics:
    retention: "90d"
    resolution: "15s"

  logs:
    retention: "30d"
    compression: "gzip"

  traces:
    retention: "7d"
    sampling:
      rate: 0.1

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: mirador-core.company.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: mirador-core-tls
      hosts:
        - mirador-core.company.com

resources:
  requests:
    memory: "2Gi"
    cpu: "1000m"
  limits:
    memory: "4Gi"
    cpu: "2000m"

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80

Environment-Specific Deployments

Development Environment

# Deploy to local Kubernetes (e.g., minikube, k3s)
helm install mirador-core ./deployments/chart \
  --values dev-values.yaml \
  --namespace mirador-dev \
  --create-namespace

Production Environment

# Production deployment with high availability
helm install mirador-core ./deployments/chart \
  --values prod-values.yaml \
  --namespace mirador-prod \
  --create-namespace \
  --wait \
  --timeout 10m

Docker Compose (Local Development)

For local development without Kubernetes:

# docker-compose.override.yml
version: '3.8'
services:
  mirador-core:
    image: mirador-core:latest
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgresql://user:pass@postgres:5432/mirador_core
      - VALKEY_URL=valkey://valkey:6379
    depends_on:
      - postgres
      - valkey

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=mirador_core
      - POSTGRES_USER=mirador_user
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data

  valkey:
    image: valkey:latest
    volumes:
      - redis_data:/data

Database Setup

PostgreSQL

-- Create database and user
CREATE DATABASE mirador_core;
CREATE USER mirador_user WITH ENCRYPTED PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE mirador_core TO mirador_user;

-- Enable required extensions
\c mirador_core;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pg_stat_statements";
CREATE EXTENSION IF NOT EXISTS "timescaledb";

Schema Initialization

The application will automatically create and migrate the database schema on startup. For manual KPI management:

# Run schema migrations
kubectl exec -it deployment/mirador-core -- ./bin/migrate up

# Check migration status
kubectl exec -it deployment/mirador-core -- ./bin/migrate status

MariaDB (Tenant Data Integration)

MIRADOR-CORE can optionally connect to a MariaDB instance (shared with mirador-ui) to read tenant data sources and KPIs. See MariaDB Integration for full documentation.

Kubernetes Deployment with MariaDB

# values.yaml - MariaDB configuration
config:
  mariadb:
    enabled: true
    host: "mariadb.database.svc.cluster.local"
    port: 3306
    database: "tenant_acme"
    username: "mirador_core_rw"  # Read-write for bootstrap
    bootstrap:
      enabled: true
      create_tables_if_missing: true
      sync_datasources_from_config: true
    sync:
      enabled: true
      interval: "5m"

# Secrets for MariaDB credentials
secrets:
  mariadb:
    password: ""  # Set via kubectl create secret

Creating MariaDB Secrets

# Create the MariaDB password secret
kubectl create secret generic mirador-core-mariadb \
  --namespace mirador-prod \
  --from-literal=password='your-secure-password'

Helm Values Example

# prod-values.yaml with MariaDB
config:
  mariadb:
    enabled: true
    host: "mariadb-primary.database.svc"
    port: 3306
    database: "tenant_production"
    username: "mirador_core_rw"  # Read-write for bootstrap
    max_open_conns: 20
    max_idle_conns: 10
    conn_max_lifetime: "10m"
    bootstrap:
      enabled: true                      # Enable automatic setup
      create_tables_if_missing: true     # Create tables on first run
      sync_datasources_from_config: true # Sync config.yaml to MariaDB
    sync:
      enabled: true
      interval: "5m"
      batch_size: 100

env:
  - name: MARIADB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: mirador-core-mariadb
        key: password

Post-Bootstrap Read-Only Configuration

After initial bootstrap completes, you can switch to a read-only user:

# prod-values-readonly.yaml - After bootstrap
config:
  mariadb:
    enabled: true
    host: "mariadb-replica.database.svc"  # Read replica
    username: "mirador_core_ro"           # Read-only user
    bootstrap:
      enabled: false  # Disable after initial sync

Read Replica Configuration

For high availability, connect to a MariaDB read replica:

config:
  mariadb:
    enabled: true
    host: "mariadb-replica.database.svc"  # Read replica
    # ... other settings

Monitoring and Observability

Prometheus Metrics

MIRADOR-CORE exposes Prometheus metrics at /metrics:

# prometheus-config.yaml
scrape_configs:
  - job_name: 'mirador-core'
    static_configs:
      - targets: ['mirador-core:8080']
    scrape_interval: 15s

Health Checks

# Health endpoint
curl http://mirador-core.company.com/api/v1/health

# Readiness endpoint
curl http://mirador-core.company.com/api/v1/ready

# Deep health check
curl http://mirador-core.company.com/api/v1/health/deep

Backup and Recovery

Database Backup

# Create backup
kubectl exec -it deployment/postgres -- pg_dump -U mirador_user mirador_core > backup.sql

# Restore from backup
kubectl exec -it deployment/postgres -- psql -U mirador_user mirador_core < backup.sql

Configuration Backup

# Backup Helm release
helm get values mirador-core > mirador-core-backup.yaml

# Restore from backup
helm upgrade mirador-core ./deployments/chart --values mirador-core-backup.yaml

Troubleshooting

Common Issues

1. Database Connection Failed

   # Check database connectivity
   kubectl exec -it deployment/mirador-core -- nc -zv postgres 5432
   

2. Redis Connection Failed

   # Check Redis connectivity
   kubectl exec -it deployment/mirador-core -- redis-cli -h redis ping
   

3. Pod Crashing

   # Check pod logs
   kubectl logs -f deployment/mirador-core
   
   # Check pod events
   kubectl describe pod -l app=mirador-core
   

4. High Memory Usage

   # Check memory usage
   kubectl top pods -l app=mirador-core
   
   # Adjust resource limits
   kubectl patch deployment mirador-core --type='json' -p='[{"op": "replace", "path": "/spec/template/spec/containers/0/resources/limits/memory", "value":"8Gi"}]'
   

Logs and Debugging

# View application logs
kubectl logs -f deployment/mirador-core -c mirador-core

# View system logs
kubectl logs -f deployment/mirador-core -c sidecar

# Enable debug logging
kubectl set env deployment/mirador-core LOG_LEVEL=DEBUG

# Access pod for debugging
kubectl exec -it deployment/mirador-core -- /bin/bash

Security Considerations

Network Policies

# network-policy.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: mirador-core-policy
spec:
  podSelector:
    matchLabels:
      app: mirador-core
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: ingress-nginx
    ports:
    - protocol: TCP
      port: 8080
  egress:
  - to:
    - podSelector:
        matchLabels:
          app: postgres
    ports:
    - protocol: TCP
      port: 5432
  - to:
    - podSelector:
        matchLabels:
          app: redis
    ports:
    - protocol: TCP
      port: 6379

TLS Configuration

# Enable TLS
ingress:
  enabled: true
  tls:
    - secretName: mirador-core-tls
      hosts:
        - mirador-core.company.com

# Certificate management with cert-manager
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: mirador-core-tls
spec:
  secretName: mirador-core-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
  - mirador-core.company.com

Performance Tuning

Resource Optimization

# Optimized resource configuration
resources:
  requests:
    memory: "4Gi"
    cpu: "2000m"
  limits:
    memory: "8Gi"
    cpu: "4000m"

# JVM tuning for Java-based components
env:
  - name: JAVA_OPTS
    value: "-Xmx6g -Xms2g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

Scaling Configuration

# Horizontal Pod Autoscaler
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80

Upgrading

Helm Upgrade

# Check for available updates
helm repo update
helm search repo mirador-core

# Upgrade to latest version
helm upgrade mirador-core mirador-core/mirador-core

# Upgrade with custom values
helm upgrade mirador-core mirador-core/mirador-core --values custom-values.yaml

Rolling Updates

# Perform rolling update
kubectl rollout restart deployment/mirador-core

# Monitor rollout status
kubectl rollout status deployment/mirador-core

# Rollback if needed
kubectl rollout undo deployment/mirador-core

Support

For deployment issues or questions:

1. Check the troubleshooting guide

2. Review GitHub Issues

3. Contact the platform team at platform@company.com