CHAI™

Infrastructure & Deployment Reference Guide
AWS Architecture · High Availability · Disaster Recovery · External Integrations · DORA Compliance
Prepared for: General Distribution
Prepared by: CloudHedge Technologies Inc.
Classification: Confidential
Version: 1.0 · March 2026
DORA Alignment: EU Regulation 2022/2554 — Digital Operational Resilience Act
"Migrate Anything. Modernize Everything. Break Nothing."

Document History

Version Date Author Changes
1.0 March 2026 CloudHedge Technologies Inc. Initial release — AWS architecture, HA, DR, integrations, DORA compliance, operational runbook

How to Use This Document

This guide is the authoritative reference for deploying, operating, and maintaining the CHAI platform on AWS. It is designed to be self-sufficient — no additional infrastructure documentation is required.

For end-user workflows (running assessments, triggering transformations, managing projects), refer to the CHAI User Guide.

If you are a... Start with... Key sections
Infrastructure / DevOps Engineer deploying CHAI for the first time Appendix C (Deployment Checklist) Sections 2, 3, 4, 5, Appendix A.2
Infrastructure Engineer operating an existing deployment Section 11 (Operational Runbook) Sections 5, 6, 7, 11
Security Architect reviewing CHAI for compliance approval Section 10 (Security & DORA) Sections 4.2, 10, Appendix D
Application Team Lead integrating CHAI with your SCM and CI/CD Section 8 (External Integrations) Sections 8, 9
Cloud Architect evaluating deployment topology options Section 2.1 (Deployment Architecture) Sections 2, 5, 6, Appendix B
Compliance Officer assessing DORA alignment Section 10.1 (DORA Matrix) Section 10

1. Executive Summary

CHAI™ (Context Rich Harness) is CloudHedge's flagship AI-powered modernization platform, purpose-built to accelerate enterprise application migration to AWS at scale. Deployed as a self-contained appliance on Amazon EC2, CHAI orchestrates 17 containerized microservices — coordinating AI-driven discovery, deep application assessment, code transformation, and cloud infrastructure provisioning — all within a single hardened deployment unit. This document provides the authoritative infrastructure and deployment reference for the CHAI platform as deployed in support of enterprise workloads, covering AWS architecture, high availability, disaster recovery, external integrations, and alignment with the EU Digital Operational Resilience Act (DORA).

The CHAI appliance runs on RHEL 8.10 or Amazon Linux 2023, uses Podman for rootless container orchestration, and persists all stateful data — including MongoDB 7.0.12 document storage — to Amazon EFS for decoupled, multi-AZ durability. The platform integrates natively with AWS Bedrock (Claude, Titan, Llama), AWS Transform, Bitbucket, GitHub, Jenkins, and all major container registries. The current production release is ch-rel-2.1.6-13 (February 25, 2026), distributed via AWS Marketplace and the CloudHedge ECR registry at 720029083713.dkr.ecr.us-east-1.amazonaws.com.

This document is DORA-aligned per EU Regulation 2022/2554. It addresses ICT risk management, operational resilience testing, cross-region disaster recovery (RTO < 30 minutes, RPO < 1 hour), incident classification and reporting, third-party risk through SBOM management, and IAM least-privilege access control. All operational teams — infrastructure engineers, security architects, application owners, and compliance officers — will find actionable reference material in the sections that follow.

Platform Key Facts
Release: CHAI v2.1.6-x (latest: ch-rel-2.1.6-13, Feb 25 2026)  |  OS: RHEL 8.10 / Amazon Linux 2023  |  Container Runtime: Podman (rootless)  |  Database: MongoDB 7.0.12  |  Services: 17 microservices  |  Primary Region: us-east-1  |  DR Region: us-west-1  |  DORA Alignment: EU Regulation 2022/2554

Companion Document: For end-user workflows — running DART assessments, configuring transformation pipelines, managing projects and tenants, and using AI-powered recommendations — see the CHAI User Guide.

Operational Responsibility Matrix

Area CloudHedge Customer
CHAI microservice container images (builds, security patches, updates) Owns — publishes updated images to ECR per release cycle Pulls updated images and restarts appliance via sudo chctl upgrade
Host OS patching (RHEL 8.10 / Amazon Linux 2023) Provides compatible AMI updates Owns — applies OS patches per organizational patching policy
ALB TLS certificate renewal N/A Owns — managed via AWS Certificate Manager (auto-renewal)
DR failover activation Provides procedure (Section 6.3) and on-call support Owns — executes failover procedure or engages CloudHedge support
CloudWatch alarm configuration Provides recommended alarm definitions (Section 11.3) Owns — configures SNS topics and integrates with internal alerting
MongoDB backup and restore Provides EFS-based durability architecture and procedure (Section 7) Owns — manages EFS backup policies and validates restore procedures
AWS IAM policy management Provides minimum IAM policy reference (Section 10.4) Owns — creates and assigns IAM roles per organizational policy
Security vulnerability response Publishes security advisories and patched images Owns — applies updates within organizational SLA; reviews SBOM
Bedrock model access and cost N/A Owns — enables models in AWS console; manages Bedrock usage costs
License management Issues and validates license keys Owns — ensures license is current; contacts CloudHedge for renewal

For support engagement, incident escalation, and SLA terms, refer to the applicable CloudHedge Enterprise Support Agreement.


2. Infrastructure Overview

2.1 Deployment Architecture

CHAI™ supports three primary deployment topologies, each suited to different organizational requirements for scalability, cost, and operational complexity. All three topologies use the same AMI, the same microservice configuration, and the same EFS-backed persistent storage — ensuring consistency across environments.

Deployment Option Description Pros Cons
Single EC2 (Standard) One EC2 instance running all 17 microservices behind an ALB. ASG maintains desired capacity of 1 for auto-recovery. Lowest cost; simplest to operate; fastest to provision; suitable for most enterprise workloads No active-active redundancy; brief downtime during AMI-based instance replacement (~5–10 min)
Multi-AZ Active-Standby Primary EC2 in AZ-1; pre-warmed standby EC2 in AZ-2. ALB health checks trigger failover automatically within 60–90 seconds. Fast automated failover; supports planned maintenance windows with zero downtime Higher cost (two running instances); requires EFS-backed shared storage to synchronize state
Full HA with Blue/Green Two ASGs (blue and green) behind a single ALB. Deployments shift traffic between environments via weighted target groups. Zero-downtime deployments; instant rollback capability; supports canary traffic splitting Highest complexity; requires CI/CD pipeline integration; approximately 2× EC2 cost during deployment windows

The recommended standard deployment uses the Single EC2 with ALB and ASG model, with EFS providing persistent multi-AZ storage durability and daily AMI snapshots enabling rapid instance replacement with no data loss.

Choosing a Deployment Topology: Most organizations start with the Single EC2 model for its simplicity and lowest cost, then upgrade to Multi-AZ Active-Standby when production SLAs require automated failover. The Blue/Green model is recommended for organizations with mature CI/CD pipelines that require zero-downtime deployments. All three topologies use the same AMI, the same microservice configuration, and the same EFS-backed storage — upgrading between topologies requires no application changes.

flowchart LR classDef userNode fill:#ffffff,stroke:#435ef8,stroke-width:2.5px,color:#2020a0,font-weight:700 classDef coreNode fill:#2020a0,stroke:#6222ff,stroke-width:3px,color:#ffffff,font-weight:700 classDef awsNode fill:#435ef8,stroke:#2020a0,stroke-width:2px,color:#ffffff classDef storageNode fill:#6222ff,stroke:#8d00fc,stroke-width:2px,color:#ffffff classDef aiNode fill:#8d00fc,stroke:#ff0bf9,stroke-width:2px,color:#ffffff classDef buildNode fill:#3a4fc4,stroke:#435ef8,stroke-width:1.5px,color:#ffffff classDef extNode fill:#f1f2f2,stroke:#a7a9ac,stroke-width:2px,color:#414042,font-style:italic U(["Users / Enterprise Network"]):::userNode subgraph VPC[" AWS VPC · us-east-1 "] direction TB subgraph PubSub["Public Subnet"] ALB["Application Load Balancer\n HTTPS :443 → HTTP :8080 \nACM Certificate · Health Check /api/health"]:::awsNode end subgraph PrivSub["Private Subnet"] EC2["CHAI Platform — EC2\nRHEL 8.10 · Amazon Linux 2023\nPodman + 17 Microservices\nEBS 75–150 GB"]:::coreNode ASG["Auto Scaling Group\nDesired: 1 · Min: 1 · Max: 1\nLaunch Template: CHAI AMI"]:::awsNode end EFS["Amazon EFS\n/mnt/efs/mongodb — MongoDB data\n/mnt/efs/shared — App shared files\n/mnt/efs/nginx — Config + TLS certs"]:::storageNode subgraph BuildInfra["Build Infrastructure — Private Subnet"] LBB["Linux Build Box\nRHEL 8.10 + Podman"]:::buildNode WBB["Windows Build Box\nServer 2022 + containerd"]:::buildNode end end subgraph Managed[" AWS Managed Services "] direction TB ECR["AWS ECR\nContainer Registry"]:::awsNode Bedrock["AWS Bedrock\nClaude Sonnet / Opus / Haiku\nTitan · Llama 3"]:::aiNode Transform["AWS Transform\nCode Modernization"]:::awsNode end Repos(["Source Repositories\nBitbucket · GitHub · GitLab"]):::extNode U -->|"HTTPS :443"| ALB ALB -->|"HTTP :8080"| EC2 ASG -. "monitors & recovers" .-> EC2 EC2 <-->|"NFS :2049 bi-directional"| EFS EC2 -->|"SSH :22"| LBB EC2 -->|"WinRM :5986"| WBB EC2 -->|"PrivateLink :443"| ECR EC2 -->|"PrivateLink :443"| Bedrock EC2 -->|"HTTPS :443"| Transform EC2 -->|"HTTPS :443"| Repos

2.2 AWS Services Used

AWS Service Purpose Configuration Notes
EC2 Hosts the CHAI appliance and all 17 microservices m7i.xlarge (recommended production) or t3.large (dev/staging); RHEL 8.10 or Amazon Linux 2023 AMI
Application Load Balancer (ALB) TLS termination, HTTP/HTTPS routing, health checks HTTPS :443 listener → Target Group :8080; ACM certificate; stickiness enabled
Auto Scaling Group (ASG) Automatic instance recovery and lifecycle management Desired: 1, Min: 1, Max: 1 (standard); uses Launch Template with IAM instance profile
Amazon EFS Multi-AZ NFS persistent storage for MongoDB data and shared application files General Purpose performance mode; Bursting throughput; encryption at rest (AES-256); mount targets in each AZ
AWS ECR Private container image registry for all CHAI microservice images Account: 720029083713; region: us-east-1; image scanning enabled; lifecycle policies configured
AWS Bedrock Foundation model inference for AI-powered assessment, code transformation, and recommendations Accessed via VPC Endpoint (PrivateLink) or NAT Gateway; models: Claude Sonnet/Opus/Haiku, Titan, Llama 3
AWS Transform Automated code modernization service integrated with CHAI transform pipelines HTTPS :443; requires IAM permissions for transform:StartJob, transform:GetJob
AWS Certificate Manager (ACM) TLS/SSL certificate provisioning for ALB HTTPS listeners Public certificate for customer domain; auto-renewal managed by ACM
Amazon Route 53 DNS routing, health checks, and failover between primary and DR regions Failover routing policy; health check on ALB endpoint; TTL: 60 seconds
AWS IAM Identity and access management for EC2 instance role and human operators Instance profile with least-privilege policy; no embedded credentials in containers
Amazon CloudWatch Metrics, log aggregation, alarms, and operational dashboards Log groups per microservice; custom metrics via PutMetricData; 8 key alarms configured
AWS CloudTrail API audit logging for all AWS API calls across the account Multi-region trail; S3 bucket retention 90 days; CloudWatch Logs integration
AWS Systems Manager (SSM) Secure parameter storage for secrets and configuration; optional session manager access Parameter Store for ECR credentials, Bedrock endpoint config, license keys
Amazon S3 CloudTrail log archive; optional report export destination; AMI snapshot staging Server-side encryption (SSE-S3); versioning enabled on audit buckets
AWS VPC Network isolation, subnet segmentation, security group enforcement /16 CIDR; public subnet for ALB; private subnet for EC2, EFS, build boxes
VPC Endpoints (PrivateLink) Private connectivity to ECR, Bedrock, S3, SSM — no internet traversal Interface endpoints for ECR API, ECR DKR, Bedrock Runtime; Gateway endpoint for S3
AWS Marketplace CHAI appliance AMI distribution and subscription management SKU: 5xtx6bcy9hcg3lj48z84f2li9; billing through AWS account

2.3 Compute & Storage Specifications

Resource Minimum (Dev/Staging) Recommended (Production) Notes
EC2 Instance Type t3.large (2 vCPU, 8 GB RAM) m7i.xlarge (4 vCPU, 16 GB RAM) 16 GB RAM required for concurrent AI inference workloads
EC2 vCPU 2 vCPU 4 vCPU Podman parallel container startup benefits from 4+ cores
EC2 RAM 8 GB 16 GB MongoDB 7 + Node.js services + Podman overhead = ~12 GB active
EBS Root Volume 75 GB gp3 150 GB gp3 Container images, OS, Podman layer cache; 3000 IOPS baseline
Amazon EFS 20 GB (burst) 100+ GB (General Purpose) Auto-scales; MongoDB data + shared files + Nginx config
Linux Build Box EC2 t3.medium (2 vCPU, 4 GB) t3.large (2 vCPU, 8 GB) Runs Podman for Linux container build; SSH :22 access from CHAI EC2
Windows Build Box EC2 t3.medium (2 vCPU, 4 GB) t3.large (2 vCPU, 8 GB) Windows Server 2022 + containerd; WinRM :5986 access from CHAI EC2
Network Bandwidth Up to 5 Gbps Up to 12.5 Gbps (m7i.xlarge) Required for ECR image pulls during startup (~8–12 GB total images)
ALB 1 ALB (shared) 1 ALB (dedicated) 1 listener, 1 target group, 1 ACM certificate
EFS Mount Targets 1 AZ 3 AZ (all in region) Mount targets in each AZ ensure availability during AZ failure

3. Microservices Architecture

3.1 Service Inventory & Ports

CHAI™ is composed of 17 containerized microservices plus MongoDB, all orchestrated by Podman and managed via the chctl appliance lifecycle tool. Each service runs on the cloudhedge Podman network (10.90.0.0/16, IPv6 fd00:db8:2::/64) and communicates via internal service discovery. Only webapp is exposed through the ALB.

# Service Name Internal Port External Exposure Technology Description
1 webapp 8080 (HTTP), 8443 (HTTPS) ALB :443 → :8080 React 18.2.x + Nginx 1.22.x Primary web UI; serves the CHAI frontend application and proxies API calls to backend services
2 auth-gateway-service 3000 Internal only Node.js 18.x + Express 4.18.x + Passport-SAML 3.1.x Authentication and authorization gateway; validates JWT tokens, handles SAML SSO, issues session tokens to all downstream services
3 core-engine 3001 Internal only Node.js 18.x + Express 4.18.x Central orchestration engine; dispatches assessment, discovery, and transformation jobs to downstream microservices; interfaces directly with AWS Bedrock for AI inference
4 cloud-infra-service 3002 Internal only Node.js 18.x Cloud infrastructure provisioning service; manages EC2, EKS, ECS resource creation and configuration as part of migration execution
5 notification-service 3005 Internal only Node.js 18.x Email and webhook notification delivery for job completion, alerts, and DORA incident reporting events
6 vault-service 3006 Internal only Node.js 18.x + bcrypt 5.1.x Secrets management service; stores and retrieves encrypted credentials for source repositories, build systems, and cloud provider accounts; backed by MongoDB
7 activity-service 3007 Internal only Node.js 18.x Audit log service; records all user actions, job events, and system changes to MongoDB; primary data source for DORA incident and activity reporting
8 report-service 3009 Internal only Node.js 18.x Report generation service; produces CHAI DART™ Tri-Vector assessment reports, 6R rationalization outputs, PDF exports, and compliance artifacts
9 license-service 3011 Internal only Node.js 18.x License validation and entitlement enforcement; verifies appliance license key on startup and periodically during operation
10 cruize-service 3012 Internal only Go >=1.10.x High-performance AI orchestration service; manages Bedrock model invocations, prompt chaining, and result aggregation for complex transformation workflows
11 aws-lift-shift 4005 Internal only Node.js 18.x AWS lift-and-shift migration executor; automates re-hosting of applications to EC2, ECS, or EKS with minimal code change
12 discover-service-linux 5001 Internal only Python 3.6.x + Go Linux application discovery agent coordinator; manages remote discovery sessions on Linux source hosts via SSH
13 transform-service-linux 5003 Internal only Python 3.6.x + Go Linux container transformation service; converts Linux application workloads to container images using AI-assisted Dockerfile generation
14 transform-service-windows 5004 Internal only Go >=1.10.x Windows container transformation service; converts Windows application workloads to Windows Server containers via the Windows Build Box
15 discover-service-windows 5005 Internal only Go >=1.10.x Windows application discovery agent coordinator; manages remote discovery sessions on Windows source hosts via WinRM
16 discover-service-aix 5006 Internal only Python 3.6.x AIX/UNIX application discovery agent coordinator; manages remote discovery on IBM AIX systems via SSH
17 ch-user-guide 8001 Internal only Nginx 1.22.x (static) In-product documentation and user guide; serves static HTML documentation accessible from within the CHAI UI
18 db-service (MongoDB) 27017 Internal only MongoDB 7.0.12 Primary document database; stores all application metadata, assessment results, user data, audit logs, and configuration; data persisted to EFS /mnt/efs/mongodb
graph LR subgraph External["External"] ALB["ALB :443"] end subgraph CHAI_Services["CHAI Platform Microservices — cloudhedge network"] WA["webapp\n:8080/:8443"] AG["auth-gateway\n:3000"] CE["core-engine\n:3001"] CI["cloud-infra\n:3002"] NS["notification\n:3005"] VS["vault\n:3006"] AS["activity\n:3007"] RS["report\n:3009"] LS["license\n:3011"] CS["cruize\n:3012"] AL["aws-lift-shift\n:4005"] DL["discover-linux\n:5001"] TL["transform-linux\n:5003"] TW["transform-windows\n:5004"] DW["discover-windows\n:5005"] DA["discover-aix\n:5006"] UG["ch-user-guide\n:8001"] DB["MongoDB\n:27017"] end ALB --> WA WA --> AG AG --> CE CE --> CI CE --> NS CE --> VS CE --> AS CE --> RS CE --> LS CE --> CS CE --> AL CE --> DL CE --> TL CE --> TW CE --> DW CE --> DA CE --> DB WA --> UG VS --> DB AS --> DB RS --> DB

For details on how each microservice is used during assessment, discovery, and transformation workflows, see the CHAI User Guide — Platform Overview.

3.2 Container Registry & Image Naming

All CHAI microservice images are distributed via the CloudHedge AWS ECR registry. Images follow a consistent naming and tagging convention to enable precise version pinning, rollback, and audit.

Component Value
ECR Registry Account 720029083713
ECR Region us-east-1
ECR Base URL 720029083713.dkr.ecr.us-east-1.amazonaws.com
Image Namespace cloudhedge/<service-name>
Release Tag Format ch-rel-<version>
Current Release Tag ch-rel-2.1.6-13
Release Date February 25, 2026

Example image references:

Service Full Image URI
webapp 720029083713.dkr.ecr.us-east-1.amazonaws.com/cloudhedge/webapp:ch-rel-2.1.6-13
core-engine 720029083713.dkr.ecr.us-east-1.amazonaws.com/cloudhedge/core-engine:ch-rel-2.1.6-13
auth-gateway-service 720029083713.dkr.ecr.us-east-1.amazonaws.com/cloudhedge/auth-gateway-service:ch-rel-2.1.6-13
cruize-service 720029083713.dkr.ecr.us-east-1.amazonaws.com/cloudhedge/cruize-service:ch-rel-2.1.6-13
db-service (MongoDB) 720029083713.dkr.ecr.us-east-1.amazonaws.com/cloudhedge/db-service:ch-rel-2.1.6-13

ECR Authentication:

aws ecr get-login-password --region us-east-1 \
  | podman login --username AWS \
    --password-stdin 720029083713.dkr.ecr.us-east-1.amazonaws.com

All images are scanned for vulnerabilities at push time via ECR enhanced scanning (Inspector). Lifecycle policies retain the last 10 release tags per repository and expire untagged images after 14 days.


4. Networking & Connectivity

4.1 VPC & Subnet Design

Internal Communication Security: All 17 CHAI microservices communicate over the cloudhedge Podman network (10.90.0.0/16), which is isolated to the EC2 instance. Inter-service traffic does not traverse the VPC network or the internet. External traffic enters only via the ALB (HTTPS :443) and exits only via VPC Endpoints (PrivateLink) or NAT Gateway for explicitly configured integrations.

Component Configuration CIDR / Details
VPC chai-prod-vpc 10.0.0.0/16 — 65,536 addresses
Public Subnet AZ-1 chai-public-1a — hosts ALB 10.0.1.0/24 — us-east-1a
Public Subnet AZ-2 chai-public-1b — hosts ALB second node 10.0.2.0/24 — us-east-1b
Public Subnet AZ-3 chai-public-1c — ALB third node 10.0.3.0/24 — us-east-1c
Private Subnet AZ-1 chai-private-1a — EC2, EFS mount target 10.0.11.0/24 — us-east-1a
Private Subnet AZ-2 chai-private-1b — EFS mount target, standby EC2 10.0.12.0/24 — us-east-1b
Private Subnet AZ-3 chai-private-1c — EFS mount target 10.0.13.0/24 — us-east-1c
Internet Gateway chai-igw — attached to VPC Provides internet access for ALB; NAT Gateway for EC2 egress
NAT Gateway chai-nat-1a — in Public Subnet AZ-1 Provides outbound internet for private subnet EC2 (ECR, Bedrock if no VPC endpoint)
Route Table (Public) Routes 0.0.0.0/0 → Internet Gateway Associated with all public subnets
Route Table (Private) Routes 0.0.0.0/0 → NAT Gateway Associated with all private subnets
Podman Internal Network cloudhedge network (pod-internal) 10.90.0.0/16 (IPv4), fd00:db8:2::/64 (IPv6) — container-to-container communication

4.2 Security Groups & Port Matrix

Security Group Rule Direction Source / Destination Port / Protocol Purpose
chai-alb-sg Inbound 0.0.0.0/0 (or Customer CIDR) TCP :443 (HTTPS) End-user access to CHAI web UI
chai-alb-sg Inbound 0.0.0.0/0 (or Customer CIDR) TCP :80 (HTTP) HTTP → HTTPS redirect
chai-alb-sg Outbound chai-ec2-sg TCP :8080 ALB to EC2 webapp forwarding
chai-ec2-sg Inbound chai-alb-sg TCP :8080 Receive proxied traffic from ALB
chai-ec2-sg Inbound Customer Bastion / Admin CIDR TCP :22 (SSH) Administrative SSH access for ops team
chai-ec2-sg Inbound chai-ec2-sg (self) All traffic Inter-service communication on Podman network (internal)
chai-ec2-sg Outbound chai-efs-sg TCP :2049 (NFS) EC2 to EFS NFS mount
chai-ec2-sg Outbound Linux Build Box SG TCP :22 (SSH) CHAI to Linux Build Box for container builds
chai-ec2-sg Outbound Windows Build Box SG TCP :5986 (WinRM HTTPS) CHAI to Windows Build Box for Windows container builds
chai-ec2-sg Outbound 0.0.0.0/0 TCP :443 (HTTPS) ECR pulls, Bedrock inference, Transform, Bitbucket, GitHub
chai-efs-sg Inbound chai-ec2-sg TCP :2049 (NFS) EC2 to EFS NFS access
chai-efs-sg Outbound None None EFS does not initiate connections
chai-build-linux-sg Inbound chai-ec2-sg TCP :22 (SSH) CHAI EC2 SSH into Linux Build Box
chai-build-windows-sg Inbound chai-ec2-sg TCP :5986 (WinRM) CHAI EC2 WinRM into Windows Build Box

4.3 Data Flow Diagram

sequenceDiagram participant U as User / Enterprise Network participant ALB as ALB (HTTPS :443) participant WA as webapp (Nginx :8080) participant AG as auth-gateway (:3000) participant CE as core-engine (:3001) participant SVC as Microservices (:3001-:5006) participant DB as MongoDB (:27017 / EFS) participant ECR as AWS ECR participant BD as AWS Bedrock U->>ALB: HTTPS :443 ALB->>WA: HTTP :8080 (SSL terminated) WA->>AG: Auth check :3000 AG-->>WA: JWT validated WA->>CE: API request :3001 CE->>SVC: Dispatch to services SVC->>DB: Read/Write :27017 DB-->>SVC: Data response (EFS-backed) SVC-->>CE: Service response CE->>BD: AI inference (Bedrock :443) BD-->>CE: Model response CE-->>WA: Aggregated response WA-->>U: HTTPS response CE->>ECR: Pull images on startup :443

4.4 Network Connectivity Map

flowchart LR classDef chaiNode fill:#2020a0,stroke:#6222ff,stroke-width:3px,color:#ffffff,font-weight:700 classDef buildNode fill:#1a5fa8,stroke:#2020a0,stroke-width:1px,color:#ffffff,font-weight:600 classDef vpcNode fill:#435ef8,stroke:#2020a0,stroke-width:1px,color:#ffffff,font-weight:600 classDef extNode fill:#6222ff,stroke:#2020a0,stroke-width:1px,color:#ffffff,font-weight:600 classDef awsNode fill:#0e7c7b,stroke:#2020a0,stroke-width:1px,color:#ffffff,font-weight:600 CHAI(["CHAI Platform EC2\nPrivate Subnet · us-east-1"]):::chaiNode subgraph BUILD[" Build Infrastructure "] direction TB LBB["Linux Build Box\nSSH :22"]:::buildNode WBB["Windows Build Box\nWinRM :5986"]:::buildNode end subgraph VPC[" AWS VPC Internal (PrivateLink) "] direction TB EFS["Amazon EFS\nNFS :2049"]:::vpcNode ECR["AWS ECR\nHTTPS :443"]:::vpcNode BDR["AWS Bedrock\nHTTPS :443"]:::vpcNode CW["CloudWatch\nHTTPS :443"]:::vpcNode SSM["Systems Manager\nHTTPS :443"]:::vpcNode S3["Amazon S3\nHTTPS :443"]:::vpcNode end subgraph REPOS[" Source Repositories "] direction TB BB["Bitbucket Server\nEnterprise"]:::extNode GH["GitHub / GHE"]:::extNode GL["GitLab"]:::extNode end subgraph AWSSVC[" AWS Modernization Services "] direction TB TRF["AWS Transform"]:::awsNode AQ["Amazon Q Developer"]:::awsNode end CHAI -->|"SSH / WinRM"| BUILD CHAI -->|"VPC / PrivateLink"| VPC CHAI -->|"HTTPS :443"| REPOS CHAI -->|"HTTPS :443"| AWSSVC

5. High Availability Deployment Architecture

5.1 HA Architecture Overview

CHAI™ achieves high availability through a combination of ALB health checks, ASG auto-recovery, and EFS-decoupled persistent storage. Because all stateful data resides on Amazon EFS rather than the EC2 instance's local EBS volume, a replacement instance launched by the ASG immediately mounts the same data — eliminating recovery time associated with data reconstruction. The following configuration steps establish the core HA posture:

  1. Create the VPC with public subnets in three Availability Zones for ALB placement, and private subnets in three AZs for EC2 and EFS mount targets.
  2. Deploy Amazon EFS with mount targets in each private subnet AZ. Enable encryption at rest. Configure inbound NFS (:2049) from the EC2 security group.
  3. Launch the CHAI EC2 instance from the marketplace AMI in the private subnet. Mount EFS at /mnt/efs via /etc/fstab. Migrate all stateful data to EFS paths.
  4. Create a golden AMI from the configured and validated EC2 instance. This AMI includes the updated chctl-compose.yaml with EFS volume paths, the Podman configuration, and the CHAI software stack.
  5. Create a Launch Template referencing the golden AMI, the EC2 security group, the IAM instance profile, and the chctl-compose.yaml user data script that starts the appliance on boot.
  6. Create an Auto Scaling Group using the Launch Template. Set Desired: 1, Min: 1, Max: 1. Associate with the private subnet. Configure EC2 health check type with a 300-second grace period.
  7. Create an Application Load Balancer in the public subnets. Add an HTTPS :443 listener with an ACM certificate. Create a Target Group pointing to :8080 with a health check on GET /api/health. Register the EC2 instance.
  8. Configure DNS (Route 53 or customer DNS) to point the CHAI hostname to the ALB DNS name.
  9. Validate HA by terminating the EC2 instance and confirming the ASG launches a replacement that mounts EFS and starts CHAI services within the defined recovery window.

5.2 HA Architecture Diagram

flowchart TD subgraph Internet["Internet / Enterprise Network"] U["Users / Enterprise"] end subgraph AWS_useast1["AWS us-east-1 — PRIMARY ACTIVE"] subgraph Public_Subnet["Public Subnets (3 AZs)"] ALB["Application Load Balancer\nHTTPS :443 to HTTP :8080\nACM Certificate · Health Check /api/health"] end subgraph AZ1["Availability Zone 1 — Private Subnet"] EC2A["CHAI Platform EC2 (Active)\nm7i.xlarge / t3.large\nPodman + 17 services"] ASG1["Auto Scaling Group\nDesired:1 · Min:1 · Max:1\nLaunch Template: CHAI-golden-ami"] end subgraph EFS_Layer["Multi-AZ Persistent Storage"] EFS["Amazon EFS\n/mnt/efs/mongodb — MongoDB data\n/mnt/efs/shared — App shared files\n/mnt/efs/nginx — Config + TLS certs"] MT1["Mount Target AZ-1"] MT2["Mount Target AZ-2"] MT3["Mount Target AZ-3"] end subgraph Build_Infra["Build Infrastructure — Private Subnet"] LBB["Linux Build Box\nRHEL 8.10 + Podman\nSSH :22"] WBB["Windows Build Box\nServer 2022 + containerd\nWinRM :5986"] end end U -->|"HTTPS :443"| ALB ALB -->|"HTTP :8080"| EC2A ASG1 -.->|"Manages"| EC2A EC2A <-->|"NFS :2049"| MT1 EFS --> MT1 & MT2 & MT3 EC2A -->|"SSH :22"| LBB EC2A -->|"WinRM :5986"| WBB

5.3 EFS Persistent Storage

Amazon EFS is the foundation of CHAI's data durability strategy. By decoupling all stateful data from the EC2 instance lifecycle, EFS enables rapid instance replacement without data loss, supports the DR replication model, and ensures that both primary and standby instances always operate on the same data set.

EFS Path Container Mount Path Contents Criticality Notes
/mnt/efs/mongodb/data/db /opt/appliance/mongodb/data/db All MongoDB 7.0.12 database files — application metadata, assessment results, user accounts, audit logs, transformation outputs Critical Must be backed up via EFS backup policy (daily, 35-day retention)
/mnt/efs/shared /opt/appliance/shared Shared application files: uploaded source artifacts, generated reports, intermediate transformation outputs, job artifacts Critical Large files; monitor EFS throughput; consider EFS provisioned throughput for large-scale transformations
/mnt/efs/nginx /opt/appliance/nginx Nginx configuration (nginx.conf), SSL/TLS certificates, reverse proxy rules, custom error pages High TLS certificates must be renewed before expiry; CHAI will fail to serve HTTPS if certs expire
/mnt/efs/nginx/ssl /opt/appliance/nginx/ssl TLS private key and certificate chain (PEM format) for the CHAI web UI HTTPS endpoint High Stored on EFS so replacement instances inherit certificate configuration without re-provisioning
/mnt/efs/shared/chctl-compose.yaml /opt/appliance/chctl-compose.yaml Appliance orchestration manifest — defines all 17 microservice containers, volume mounts, network configuration, environment variables Critical Any volume path updates must reference /mnt/efs/ paths; changes take effect on chctl restart appliance

5.4 EFS /etc/fstab Configuration

The following /etc/fstab entry mounts the Amazon EFS file system automatically on instance boot, ensuring CHAI services have access to persistent data before the appliance starts.

# /etc/fstab — Amazon EFS mount for CHAI persistent storage
# Replace <EFS_FILE_SYSTEM_ID> with your actual EFS ID (e.g., fs-0a1b2c3d4e5f6789a)
<EFS_FILE_SYSTEM_ID>.efs.us-east-1.amazonaws.com:/ /mnt/efs efs \
  _netdev,tls,iam,noresvport,nofail,\
  retrans=2,rsize=1048576,wsize=1048576,\
  hard,timeo=600 0 0

Manual mount command (for initial setup or troubleshooting):

sudo mount -t efs -o tls,iam <EFS_FILE_SYSTEM_ID>:/ /mnt/efs

Create required subdirectories after first mount:

sudo mkdir -p /mnt/efs/mongodb/data/db
sudo mkdir -p /mnt/efs/shared
sudo mkdir -p /mnt/efs/nginx/ssl
sudo chown -R 1000:1000 /mnt/efs/mongodb /mnt/efs/shared /mnt/efs/nginx
IAM Permissions Required for EFS IAM-based Mount: The EC2 instance IAM role must include elasticfilesystem:ClientMount, elasticfilesystem:ClientWrite, and elasticfilesystem:ClientRootAccess permissions on the EFS resource ARN. Without these permissions, the iam mount option will cause the mount to fail silently. Ensure the EFS file system policy also grants access to the EC2 instance role ARN. See Section 10.4 for the full IAM policy reference.

6. Disaster Recovery

6.1 Cross-Region DR Architecture

CHAI™ implements a cross-region warm-standby disaster recovery architecture with a primary deployment in us-east-1 and a standby deployment in us-west-1. EFS continuous replication keeps the DR data store synchronized in near-real-time. Daily AMI snapshots are copied to the DR region to ensure a consistent, bootable instance is always available. Under normal operations, the DR EC2 instance remains stopped to minimize cost. On DR activation, the instance starts, mounts the now-writable DR EFS (replication must be deleted before the DR EFS becomes writable), and services resume within the RTO window.

flowchart LR subgraph Primary["PRIMARY — us-east-1 (ACTIVE)"] P_ALB["ALB (HTTPS)"] --> P_EC2["CHAI Platform EC2\nPodman Active"] P_EC2 <-->|NFS| P_EFS["EFS: chai-prod-data\nREAD-WRITE"] P_AMI["Daily AMI Snapshot"] end subgraph DR["DR — us-west-1 (STANDBY)"] D_ALB["ALB (Standby)"] --> D_EC2["CHAI Platform EC2\n(Stopped/Standby)"] D_EC2 <-->|NFS| D_EFS["EFS: chai-dr-data\nREAD-ONLY (while replicating)"] D_AMI["Copied AMI"] end P_EFS -->|"EFS Replication\n(continuous)"| D_EFS P_AMI -->|"Daily copy"| D_AMI DNS["Route 53 / DNS"] -->|"Normal traffic"| P_ALB DNS -.->|"Failover (DR activation)"| D_ALB

6.2 RTO/RPO Table

Objective Target Measurement Method Notes
RTO (Recovery Time Objective) < 30 minutes Time from DR activation decision to CHAI web UI confirmed available on DR URL Includes: EFS replication deletion (~5 min), EC2 start (~3 min), EFS mount and chctl start (~10 min), DNS propagation (~2 min), service health check validation (~5 min)
RPO (Recovery Point Objective) < 1 hour Maximum data loss measured from last EFS replication sync point to failure event EFS replication is continuous (typically < 15 min lag); RPO < 1 hr is conservative; actual RPO is typically < 15 minutes under normal replication
AMI Recovery Point < 24 hours Age of most recent AMI copy in DR region Daily AMI backup copied to us-west-1; used only if EFS DR data is also unavailable
DR Test Frequency Quarterly DR activation drill results documented in DORA resilience testing log Test activations are conducted on a non-production instance to avoid disrupting production; results reviewed by security and compliance teams
DNS Failover Propagation < 5 minutes Route 53 health check interval: 30 sec; TTL: 60 sec; failover effective within 2 health check cycles Customer DNS may have additional propagation delay if not using Route 53 natively; coordinate DNS cutover timing during DR activation

6.3 DR Activation Procedure

The following 9-step procedure is executed by the CloudHedge on-call operations team or designated customer infrastructure team upon confirmation that the primary us-east-1 deployment is unavailable and cannot be recovered within the established RTO window.

  1. Declare DR Event. Notify the DR response team via the incident communication channel. Confirm that primary region failure is not a transient AWS issue resolvable within 30 minutes. Reference the incident severity matrix in Section 10.2 to confirm P1 threshold is met.

  2. Navigate to EFS in us-east-1. In the AWS Console, navigate to EFS → chai-appliance-data-prod → Replication tab. Confirm the replication status shows the DR region EFS ID and current lag.

  3. Delete EFS Replication. Click "Delete replication" on the primary EFS. This action disables the replication relationship and transitions the DR EFS (chai-dr-data in us-west-1) from READ-ONLY to READ-WRITE. Wait approximately 5 minutes for the state transition to complete.

  4. Confirm DR EFS is Writable. In the AWS Console, navigate to EFS in us-west-1. Confirm the chai-dr-data file system shows state = Available and replication role = None (no longer a replica).

  5. Start DR EC2 Instance. Navigate to EC2 in us-west-1. Locate the instance tagged CHAI-appliance-DR. Start the instance. Wait for instance state = Running and health checks = 2/2 passed.

  6. SSH into DR EC2 and Mount EFS. Connect to the DR EC2 instance. Update /etc/fstab to reference the DR EFS file system ID (chai-dr-data ID). Execute sudo mount -a to mount the DR EFS at /mnt/efs. Confirm with df -h | grep efs.

  7. Start CHAI Services. Execute sudo chctl start appliance. Monitor startup with sudo chctl status. All 17 microservices should reach running state within 5–8 minutes. If any service fails to start, inspect logs with podman logs <service-name>.

  8. Validate Application Availability. Open the CHAI web UI at the DR ALB DNS name. Confirm login is functional. Run a test discovery or assessment job to validate end-to-end service health.

  9. Update DNS. Update the Route 53 failover record (or customer DNS) to point the CHAI hostname to the DR ALB endpoint. Notify customer operations team and end users of the temporary DR URL if DNS propagation will take > 5 minutes. Document the event in the DORA incident log.

6.4 DR Activation Flowchart

flowchart TD A["PRIMARY REGION FAILURE DETECTED"] --> B["Notify DR Team\nOpen P1 Incident Ticket"] B --> C["Navigate to AWS Console — us-east-1\nEFS → chai-appliance-data-prod → Replication"] C --> D["Delete EFS Replication\nWait ~5 minutes"] D --> E{"DR EFS State\n= Available?"} E -->|No| D E -->|Yes| F["DR EFS is now WRITABLE\nus-west-1: chai-dr-data"] F --> G["Start EC2: CHAI-appliance-DR\nin us-west-1"] G --> H["SSH into DR EC2\nUpdate /etc/fstab with DR EFS ID\nsudo mount -a"] H --> I["sudo chctl start appliance"] I --> J{"sudo chctl status\nAll 17 services UP?"} J -->|No| K["Check logs: podman logs core-engine\nRestart failed service: chctl restart svc"] K --> J J -->|Yes| L["Update Route 53 DNS\nPoint CHAI hostname to DR ALB endpoint"] L --> M["DR ACTIVE — Notify users of new URL\nDocument event in DORA incident log"]

7. Data Migration & Transfer

7.1 Critical Data Inventory

Data Asset Source Path (Existing Instance) EFS Destination Path Contents Criticality
MongoDB Database /opt/appliance/mongodb/data/db /mnt/efs/mongodb/data/db All CHAI application data: users, tenants, assessments, discovery results, transformation jobs, reports, activity logs Critical — loss of this data requires full re-discovery and re-assessment
Shared Application Files /opt/appliance/shared /mnt/efs/shared Uploaded source artifacts, generated PDF reports, intermediate job files, transformation output archives High — recoverable through re-execution but costly in time
Appliance Compose Manifest /opt/appliance/chctl-compose.yaml /mnt/efs/shared/chctl-compose.yaml (then symlinked to /opt/appliance/) Full microservice orchestration definition including environment variables, volume mounts, network config, image references Critical — without this file the appliance cannot start
Nginx Configuration /mnt/efs/nginx/nginx.conf or /opt/appliance/nginx/nginx.conf /mnt/efs/nginx/nginx.conf Nginx reverse proxy configuration, upstream definitions, SSL settings, custom headers High — CHAI web UI inaccessible without valid Nginx config
TLS Certificates /opt/appliance/nginx/ssl/ /mnt/efs/nginx/ssl/ SSL private key (server.key) and certificate chain (server.crt) for CHAI web UI HTTPS High — expired or missing certs cause browser security warnings and HTTPS failures
License File /opt/appliance/license.key /mnt/efs/shared/license.key CHAI platform license key — base64 encoded entitlement token issued by CloudHedge Critical — CHAI will enter degraded mode after grace period if license is missing

7.2 Migration Architecture

flowchart LR subgraph Source["SOURCE INSTANCE (Existing)"] S1["/opt/appliance/mongodb/"] S2["/opt/appliance/shared/"] S3["/opt/appliance/chctl-compose.yaml"] S4["/mnt/efs/nginx/nginx.conf"] end subgraph EFS["AMAZON EFS (/mnt/efs)"] E1["/mnt/efs/mongodb/data/db"] E2["/mnt/efs/shared/"] E3["/mnt/efs/nginx/nginx.conf"] end subgraph Target["TARGET INSTANCE (New)"] T1["CHAI New Deployment\nMounts same EFS\nAll data preserved"] end S1 -->|"sudo cp -r"| E1 S2 -->|"sudo cp -r"| E2 S4 -->|"copy"| E3 S3 -->|"Update volume paths to /mnt/efs/"| E2 EFS -->|"EFS Mount via /etc/fstab"| T1

7.3 Step-by-Step Migration Procedure

The following procedure migrates an existing CHAI deployment to an EFS-backed architecture, or transfers data from one instance to a new deployment. Execute all steps as root or with sudo.

  1. Stop the CHAI appliance on the source instance. This ensures MongoDB performs a clean shutdown and all write-ahead logs are flushed before copying data.

       sudo chctl stop appliance
       sudo chctl status  # Confirm all services are stopped
       

  2. Create and mount the EFS file system. In the AWS Console, create an EFS file system in the same VPC. Create mount targets in each private subnet. On the source (or new target) EC2 instance, install the EFS mount helper and mount:

       sudo yum install -y amazon-efs-utils   # RHEL/AL2023
       sudo mkdir -p /mnt/efs
       sudo mount -t efs -o tls,iam <EFS_ID>:/ /mnt/efs
       

  3. Create the required EFS directory structure.

       sudo mkdir -p /mnt/efs/mongodb/data/db
       sudo mkdir -p /mnt/efs/shared
       sudo mkdir -p /mnt/efs/nginx/ssl
       sudo chown -R 1000:1000 /mnt/efs/mongodb /mnt/efs/shared /mnt/efs/nginx
       

  4. Copy MongoDB data to EFS. This is the most time-consuming step for large databases. Use rsync for resume capability:

       sudo rsync -avz --progress \
         /opt/appliance/mongodb/data/db/ \
         /mnt/efs/mongodb/data/db/
       

  5. Copy shared application files to EFS.

       sudo rsync -avz --progress \
         /opt/appliance/shared/ \
         /mnt/efs/shared/
       

  6. Copy Nginx configuration and TLS certificates.

       sudo cp /opt/appliance/nginx/nginx.conf /mnt/efs/nginx/nginx.conf
       sudo cp /opt/appliance/nginx/ssl/server.key /mnt/efs/nginx/ssl/server.key
       sudo cp /opt/appliance/nginx/ssl/server.crt /mnt/efs/nginx/ssl/server.crt
       

  7. Update chctl-compose.yaml volume paths. Edit the appliance manifest to replace all local /opt/appliance/ volume references with /mnt/efs/ paths. The critical paths are the MongoDB data directory and the shared files directory. Copy the updated manifest to EFS:

       sudo cp /opt/appliance/chctl-compose.yaml /mnt/efs/shared/chctl-compose.yaml
       

  8. Add EFS to /etc/fstab for persistent mounting. Add the fstab entry from Section 5.4 to ensure EFS mounts automatically on every reboot before the CHAI appliance service starts.

  9. Start the CHAI appliance and validate. Start services and confirm all 17 microservices are running correctly, MongoDB is reading data from the EFS-backed path, and the web UI is accessible:

       sudo chctl start appliance
       sudo chctl status
       # Open web UI and confirm login and data integrity
       

7.4 Amazon Linux 2023 Deployment Notes

CHAI supports both RHEL 8.10 and Amazon Linux 2023 as host operating systems. Organizations may choose either based on their OS standardization policy, licensing model, and AWS optimization preferences. The following notes document the key differences between the two platforms that affect CHAI deployment and operations.

Amazon Linux 2023 vs. RHEL 8.10 — Key Differences:

Package Manager: AL2023 uses dnf exclusively (not yum). All yum install commands must be replaced with dnf install.

EFS Mount Helper: On AL2023, install with sudo dnf install -y amazon-efs-utils. The package is available in the default AL2023 repository — no EPEL or third-party repo required.

Podman Version: AL2023 ships with Podman 4.x (vs. Podman 3.x on RHEL 8.10). The chctl-compose.yaml format is compatible with both versions, but Podman 4.x changes the default network backend from CNI to netavark. Confirm the cloudhedge network is created with podman network create cloudhedge --subnet 10.90.0.0/16 before starting the appliance.

SELinux: AL2023 enables SELinux in enforcing mode by default. EFS mounts require the sefcontext for /mnt/efs to be set correctly. Run sudo restorecon -r /mnt/efs after mounting if Podman containers report permission denied on EFS-mounted volumes.

Systemd Unit: The chctl systemd service unit path is the same on both platforms (/etc/systemd/system/appliance.service). No changes required.

AWS SSM Agent: Pre-installed on AL2023 AMIs. On RHEL 8.10, SSM Agent must be installed manually. AL2023 supports SSM Session Manager out-of-box, enabling SSH-free access for ops teams with appropriate IAM permissions.

8. External System Integrations

8.1 Integration Overview Diagram

flowchart LR classDef chaiNode fill:#2020a0,stroke:#6222ff,stroke-width:3px,color:#ffffff,font-weight:700 classDef repoNode fill:#435ef8,stroke:#2020a0,stroke-width:1px,color:#ffffff,font-weight:600 classDef cicdNode fill:#6222ff,stroke:#2020a0,stroke-width:1px,color:#ffffff,font-weight:600 classDef aiNode fill:#8d00fc,stroke:#2020a0,stroke-width:1px,color:#ffffff,font-weight:600 classDef buildNode fill:#1a5fa8,stroke:#2020a0,stroke-width:1px,color:#ffffff,font-weight:600 classDef regNode fill:#0e7c7b,stroke:#2020a0,stroke-width:1px,color:#ffffff,font-weight:600 CHAI(["CHAI Platform\nEC2 · Private Subnet\nch-rel-2.1.6-13"]):::chaiNode subgraph SRC[" Source Code Repositories "] direction TB BB["Bitbucket Server\nHTTPS :443"]:::repoNode GH["GitHub / GHE\nHTTPS :443"]:::repoNode GL["GitLab / GitLab.com\nHTTPS :443"]:::repoNode CC["AWS CodeCommit\nHTTPS :443"]:::repoNode ADO["Azure DevOps\nHTTPS :443"]:::repoNode end subgraph CICD[" CI/CD Platforms "] direction TB JK["Jenkins\nWebhook :443"]:::cicdNode GHA["GitHub Actions\nAPI :443"]:::cicdNode CP["AWS CodePipeline\nLambda :443"]:::cicdNode ADO_P["Azure Pipelines\nWebhook :443"]:::cicdNode end subgraph AI[" AWS AI Services "] direction TB BDR["AWS Bedrock\nClaude · Titan · Llama\nVPC Endpoint :443"]:::aiNode TRF["AWS Transform\nModernization :443"]:::aiNode Q["Amazon Q Developer\nHTTPS :443"]:::aiNode end subgraph BUILD[" Build Infrastructure "] direction TB LBB["Linux Build Box\nPodman · SSH :22"]:::buildNode WBB["Windows Build Box\ncontainerd · WinRM :5986"]:::buildNode end subgraph REG[" Container Registries "] direction TB ECR["AWS ECR\nHTTPS :443"]:::regNode ACR["Azure Container Registry\nHTTPS :443"]:::regNode Harbor["Harbor / Private Registry\nHTTPS :443"]:::regNode end CHAI -->|"HTTPS :443"| SRC CHAI -->|"Webhook / API"| CICD CHAI -->|"VPC Endpoint"| AI CHAI -->|"SSH / WinRM"| BUILD CHAI -->|"HTTPS :443"| REG

This section covers infrastructure-level connectivity and credentials setup. For step-by-step instructions on connecting repositories and running discovery from the CHAI web UI, see the CHAI User Guide.

8.2 Source Code Repository Connectivity Table

Repository System Protocol Port Authentication CHAI Usage Configuration Notes
Bitbucket Server (Data Center) HTTPS 443 HTTP Basic Auth or App Password (read-only token) Source discovery, clone for transformation, repo metadata extraction Common enterprise SCM. Configure with your Bitbucket Server base URL and service account credentials stored in the CHAI vault. See Section 8.3 for a step-by-step example.
Bitbucket Cloud HTTPS 443 App Password with Repositories:Read scope Source discovery and clone Workspace URL format differs from server; use https://bitbucket.org as base URL
GitHub.com HTTPS 443 Personal Access Token (PAT) — repo:read scope Source discovery, clone, PR creation for transformed code Fine-grained PATs preferred; classic PATs acceptable with repo scope
GitHub Enterprise Server HTTPS 443 PAT or GitHub App installation token Same as GitHub.com; self-hosted base URL required Ensure TLS certificate is trusted by CHAI EC2 or add to trust store
GitLab.com HTTPS 443 Project/Group Access Token — read_repository scope Source discovery and clone OAuth2 app integration also supported for SSO
GitLab Self-Managed HTTPS 443 Personal or Project Access Token Same as GitLab.com; custom hostname required Internal CA certificate must be added to EC2 trust store
AWS CodeCommit HTTPS 443 IAM HTTPS Git credentials (not IAM role) Source discovery and clone Git credentials generated in IAM console per IAM user; not compatible with IAM roles directly
Azure DevOps / TFS HTTPS 443 PAT with Code:Read scope Source discovery, clone, push transformed code Organization URL format: https://dev.azure.com/<org>
SVN (Apache Subversion) HTTP/HTTPS / SVN 443 / 3690 Username + password Legacy source discovery for SVN repositories CHAI extracts SVN working copy and converts to Git-compatible structure for transformation
Generic Git (SSH) SSH 22 SSH key pair (ED25519 recommended) Any Git host accessible via SSH CHAI generates an SSH key pair; public key must be added to the repository host's authorized keys

8.3 Bitbucket Server Configuration (Reference Example)

The following walkthrough uses Bitbucket Server as a reference example. CHAI supports all repository systems listed in Section 8.2 — including GitHub, GitLab, Azure DevOps, CodeCommit, and generic Git over SSH. The configuration steps (create service account → generate token → store in CHAI vault → test connection) follow the same pattern for all platforms. For platform-specific setup instructions, see the CHAI User Guide.

Bitbucket Server Integration — Step-by-Step Configuration:

Step 1 — Create Service Account: In Bitbucket Server, create a dedicated service account (e.g., chai-svc-readonly). Grant this account read access to all projects and repositories that CHAI will discover or transform.

Step 2 — Generate HTTP Access Token: Log in as the service account. Navigate to Account Settings → HTTP Access Tokens → Create Token. Set token name: CHAI-Discovery-Token. Set permissions: Repositories: Read, Projects: Read. Set expiry: 1 year. Copy the token value immediately — it will not be shown again.

Step 3 — Store Credentials in CHAI Vault: In the CHAI web UI, navigate to Settings → Source Control → Add Repository. Enter the Bitbucket Server base URL (e.g., https://bitbucket.yourcompany.internal), username (chai-svc-readonly), and the HTTP access token as the password. Click Test Connection.

Step 4 — Verify TLS Certificate: If Bitbucket Server uses an internal CA-signed certificate, the CA certificate must be added to the CHAI EC2 system trust store:
sudo cp your-internal-ca.crt /etc/pki/ca-trust/source/anchors/ && sudo update-ca-trust

Step 5 — Configure Webhook (Optional for CI/CD): In Bitbucket Server, navigate to Repository Settings → Webhooks → Create Webhook. Set URL to the CHAI webhook endpoint: https://chai.yourcompany.internal/api/webhooks/bitbucket. Select events: Push, Pull Request Created. Save. CHAI will receive push events and trigger automated re-assessment on code changes.

Step 6 — Test Discovery: In CHAI, initiate a new Discovery job against the Bitbucket repository. Confirm that repository metadata, branch list, and file tree are successfully retrieved.

8.4 CI/CD Integration Table

CI/CD Platform Integration Method Trigger CHAI Capability Configuration
Jenkins Webhook POST to CHAI API Post-build step or Pipeline stage Trigger automated re-assessment after build; push transformation artifacts back to repo Add POST https://chai-host/api/webhooks/jenkins to Jenkins post-build actions; configure CHAI Jenkins credentials in vault
GitLab CI CHAI pipeline stage in .gitlab-ci.yml On merge to main/release branch Run CHAI assessment as a pipeline gate; block merge if assessment score below threshold Use CHAI REST API in gitlab-ci.yml; store CHAI API key in GitLab CI/CD variables
AWS CodePipeline Lambda action invoking CHAI API Source change in CodeCommit/S3 Automated discovery and assessment triggered by code change Lambda function with CHAI API key calls /api/jobs/assess; CodePipeline waits for CHAI job completion
Azure Pipelines REST API call in pipeline task On push to feature/main branch Assessment and transformation as pipeline stage Use Azure Pipelines InvokeRestAPI task or custom script task to call CHAI API
GitHub Actions CHAI action in workflow YAML On push, pull_request, workflow_dispatch Automated assessment and report generation in PR workflow Workflow step calls CHAI REST API using repository secret CHAI_API_KEY

8.5 Build Box Connectivity Table

Build Box OS Protocol Port Authentication Purpose Configuration
Linux Build Box RHEL 8.10 SSH 22 SSH key pair (stored in CHAI vault) Builds Linux container images using Podman; executes podman build for transformed Linux workloads; pushes images to ECR CHAI EC2 must have the build box's IP/hostname in Security Group outbound. Add CHAI EC2's public SSH key to build box's ~/.ssh/authorized_keys
Windows Build Box Windows Server 2022 WinRM (HTTPS) 5986 Username + password (stored in CHAI vault) Builds Windows container images using containerd; executes docker build for transformed Windows workloads; pushes to ECR Enable WinRM HTTPS on Windows Build Box: winrm quickconfig -transport:https. Add CHAI EC2's outbound :5986 to Security Group. Store credentials in CHAI vault

9. AWS AI Services Integration

9.1 AWS Bedrock Connectivity

CHAI™ leverages AWS Bedrock as the primary AI inference layer for all large language model operations — including application assessment, code transformation, architecture recommendation, and natural language report generation. Bedrock is accessed via a VPC PrivateLink endpoint, ensuring all model traffic remains within the AWS network and never traverses the public internet. The core-engine and cruize-service microservices are the primary Bedrock consumers; cruize-service handles complex multi-step AI orchestration workflows using chained model invocations.

flowchart LR subgraph VPC["Customer VPC"] CHAI["CHAI Platform EC2\ncore-engine\ncruize-service\nflow-orchestrator"] VPE["VPC Endpoint\ncom.amazonaws.us-east-1\n.bedrock-runtime\n(PrivateLink)"] end subgraph Bedrock["AWS Bedrock"] Claude["Anthropic Claude\nSonnet 4.6 · Opus 4.6 · Haiku 4.5"] Titan["Amazon Titan\nText · Embeddings"] Llama["Meta Llama 3\n70B Instruct"] end CHAI -->|"HTTPS :443\n(private — no internet)"| VPE VPE --> Claude VPE --> Titan VPE --> Llama

9.2 Foundation Models Table

Model Provider Model ID (Bedrock) CHAI Use Case Notes
Claude Sonnet 4.6 Anthropic anthropic.claude-sonnet-4-6 Primary model for application assessment, 6R rationalization, Tri-Vector scoring, code analysis, and infrastructure recommendation generation Default model for most CHAI DART and CHAI Flow operations; best balance of quality and throughput
Claude Opus 4.6 Anthropic anthropic.claude-opus-4-6 Complex multi-file code transformation, architecture pattern inference for large monoliths, deep dependency analysis for 100K+ LOC codebases Reserved for highest-complexity assessment tasks; higher cost per token; invoked selectively by cruize-service
Claude Haiku 4.5 Anthropic anthropic.claude-haiku-4-5-20251001 Batch metadata extraction, rapid file classification, service dependency parsing, high-volume discovery augmentation Fast and cost-efficient; used for pre-processing large application portfolios before deeper Sonnet/Opus analysis
Amazon Titan Text Amazon amazon.titan-text-express-v1 Fallback text generation for summary reports and natural language descriptions when Anthropic models are unavailable or rate-limited Available as a secondary option; configured in CHAI model fallback chain
Amazon Titan Embeddings Amazon amazon.titan-embed-text-v2:0 Semantic search across application discovery results, similarity matching between applications for portfolio grouping, RAG retrieval for CHAI knowledge base Used by cruize-service for vector similarity operations; embeddings stored in MongoDB vector index
Meta Llama 3 70B Meta meta.llama3-70b-instruct-v1:0 Open-source code analysis tasks, license-sensitive environments where Anthropic models cannot be used, secondary transformation validation Available as an alternative inference path; configured per-tenant in CHAI vault service

Model Selection Flexibility: CHAI does not require a specific foundation model. Organizations can enable any combination of the models listed above based on their performance, cost, and data-residency requirements. Model selection is configurable per CHAI project — different teams can use different models within the same deployment. For model selection guidance, see the CHAI User Guide.

9.3 Bedrock VPC Endpoint Setup

Step-by-Step: Create Bedrock VPC Endpoint (PrivateLink):

Step 1: In AWS Console, navigate to VPC → Endpoints → Create Endpoint.

Step 2: Set Name tag: chai-bedrock-runtime-endpoint. Select Service category: AWS services. Search for: com.amazonaws.us-east-1.bedrock-runtime. Select the Interface type endpoint.

Step 3: Select the CHAI VPC (chai-prod-vpc). Select all private subnets (AZ-1, AZ-2, AZ-3) for endpoint placement.

Step 4: Security Group: Create a new SG chai-bedrock-vpce-sg allowing inbound HTTPS :443 from chai-ec2-sg.

Step 5: Policy: Select Full access (or use a custom resource policy to restrict to specific model ARNs).

Step 6: Create endpoint. Wait for state = Available (~2 minutes).

Step 7: Enable Private DNS: Ensure "Enable DNS name" is checked on the endpoint. This allows CHAI to use the standard Bedrock Runtime endpoint hostname (bedrock-runtime.us-east-1.amazonaws.com) without any application configuration changes — all traffic is automatically routed through the VPC endpoint.

Step 8: In the CHAI web UI, navigate to Settings → AI Configuration → Test Bedrock Connection to confirm private connectivity.

9.4 AWS Transform

AWS Transform provides additional automated code modernization capabilities that CHAI integrates with for .NET and Java legacy code conversion. CHAI's transform-service-linux and transform-service-windows microservices can invoke AWS Transform jobs as part of the CHAI Flow™ orchestration pipeline, enabling hybrid AI-powered transformation where CHAI handles assessment and workflow orchestration while AWS Transform executes specific language upgrade tasks.

Connectivity: HTTPS :443 to transform.us-east-1.amazonaws.com. No VPC endpoint required; outbound via NAT Gateway or dedicated VPC endpoint.

IAM Permissions Required for AWS Transform:

Permission Resource Purpose
transform:StartJob arn:aws:transform:us-east-1:*:job/* Initiate a new code transformation job
transform:GetJob arn:aws:transform:us-east-1:*:job/* Poll job status and retrieve results
transform:ListJobs * List active and completed transformation jobs
s3:GetObject Source code S3 bucket ARN Read source code from S3 staging bucket
s3:PutObject Output S3 bucket ARN Write transformed code to S3 output bucket
codecommit:GetRepository Repository ARNs Read source code from CodeCommit repos
codecommit:CreateBranch Repository ARNs Create output branches for transformed code

9.5 Model Usage Guidance

Best Practices: Selecting the Right Model for Each CHAI Task:

Claude Sonnet 4.6 — General Assessment & Standard Transformation: Use Sonnet for the majority of CHAI DART assessment operations, including Tri-Vector scoring, 6R rationalization, dependency map generation, architecture description, and standard containerization transformation for applications under ~50K lines of code. Sonnet provides the best throughput-to-quality ratio and is the default model for all CHAI DART™ report generation.

Claude Opus 4.6 — Complex Reasoning & Large Codebase Transformation: Reserve Opus for large monolithic applications (100K+ LOC), complex multi-service dependency inference, architectural pattern recognition across polyglot codebases, and transformation tasks requiring multi-turn reasoning chains. Opus is invoked by cruize-service for CHAI Flow™ workflows that require multi-step reasoning. Expect 3–5× higher token cost vs. Sonnet.

Claude Haiku 4.5 — Batch Processing & Fast Inference: Use Haiku for high-volume, low-complexity tasks: file-type classification across large portfolios, metadata extraction from manifests and configuration files, rapid service inventory generation, and pre-screening applications before deep Sonnet/Opus analysis. Haiku delivers near-instant responses and is ideal for portfolios of 100+ applications where initial triage speed matters most.

Titan Embeddings — Semantic Search & Portfolio Clustering: Use Titan Embeddings for semantic similarity operations: grouping similar applications in portfolio analysis, retrieval-augmented generation (RAG) over CHAI's internal knowledge base, and searching assessment results by natural language query. Embeddings are stored in MongoDB with vector indexing.

Cost Optimization: Configure CHAI's AI model routing in Settings → AI Configuration to define per-task model preferences. Use Haiku for triage, Sonnet for standard operations, and Opus only when cruize-service escalates a task due to complexity scoring.

For guidance on how AI models are used within CHAI assessment and transformation workflows — including prompt strategies, output review, and confidence scoring — see the CHAI User Guide.


10. Security & DORA Compliance

The European Union's Digital Operational Resilience Act (DORA), established under Regulation (EU) 2022/2554, mandates that financial entities and their critical ICT third-party service providers demonstrate structured, measurable operational resilience. DORA is organized around five pillars: (1) ICT Risk Management — continuous identification, classification, and mitigation of technology risks; (2) ICT-Related Incident Reporting — structured classification, internal escalation, and regulatory notification of significant ICT incidents; (3) Digital Operational Resilience Testing — periodic testing of business continuity, disaster recovery, and threat-led penetration testing (TLPT) for systemically important entities; (4) ICT Third-Party Risk Management — due diligence, contractual obligations, and ongoing monitoring of technology vendors; and (5) Information and Intelligence Sharing — participation in industry threat intelligence sharing arrangements. CHAI's infrastructure architecture, operational procedures, and security controls have been designed to support the licensee's compliance obligations under each of these five pillars.

10.1 DORA Compliance Matrix

flowchart LR classDef root fill:#6222ff,stroke:#ffffff,stroke-width:2px,color:#ffffff,font-weight:700 classDef pillar fill:#2020a0,stroke:#435ef8,stroke-width:2px,color:#ffffff,font-weight:700 classDef ctrl fill:#435ef8,stroke:#6222ff,stroke-width:1px,color:#ffffff,font-weight:600 DORA(["DORA Compliance\nEU Reg 2022/2554"]):::root subgraph C1["ICT Risk Management"] direction TB I1["VPC Isolation"]:::ctrl I2["IAM Least Privilege"]:::ctrl I3["EFS Encryption AES-256"]:::ctrl I4["TLS in Transit"]:::ctrl end subgraph C2["Incident Reporting"] direction TB N1["CloudWatch Alarms"]:::ctrl N2["Activity Service Audit Logs"]:::ctrl N3["CloudTrail API Logs"]:::ctrl N4["P1-P4 Severity Matrix"]:::ctrl end subgraph C3["Resilience Testing"] direction TB R1["AWS Inspector Image Scans"]:::ctrl R2["DR Activation Drills"]:::ctrl R3["ASG Recovery Tests"]:::ctrl R4["Backup Restoration Tests"]:::ctrl end subgraph C4["Third-Party Risk"] direction TB T1["SBOM Documentation"]:::ctrl T2["ECR Image Scanning"]:::ctrl T3["Vendor SLAs"]:::ctrl T4["Read-only Repo Tokens"]:::ctrl end subgraph C5["Information Sharing"] direction TB S1["SBOM Published"]:::ctrl S2["Security Advisories"]:::ctrl S3["Release Notes"]:::ctrl S4["Support Portal"]:::ctrl end DORA --> C1 DORA --> C2 DORA --> C3 DORA --> C4 DORA --> C5
DORA Article Requirement CHAI™ Implementation Evidence / Artifact
Art. 5 — ICT Risk Management Framework Maintain and update ICT risk management framework VPC isolation, Security Groups, IAM least privilege, TLS encryption in transit, EFS encryption at rest (AES-256) VPC architecture diagram; IAM policy JSON; EFS encryption settings
Art. 9 — Protection & Prevention Protect ICT systems from unauthorized access and ensure data integrity EC2 in private subnet (no public IP); ALB as sole ingress; SSH restricted to admin CIDR; Podman rootless containers; no embedded credentials (all via IAM and SSM Parameter Store) Security group rules; IAM instance profile; SSM Parameter Store config
Art. 10 — Detection Detect anomalous activities promptly CloudWatch alarms on CPU, memory, error rates, service health; CloudTrail API logging; CHAI activity-service audit log for all user and system actions CloudWatch dashboard; CloudTrail S3 bucket; activity-service MongoDB audit collection
Art. 11 — Response & Recovery Define and test response and recovery procedures DR activation procedure (Section 6.3); ASG auto-recovery (Section 5.1); RTO < 30 min, RPO < 1 hr documented and tested quarterly DR runbook; ASG configuration; quarterly DR drill log
Art. 17 — Incident Classification Classify ICT incidents by severity and report per regulatory requirements P1–P4 severity matrix (Section 10.2); notification-service automates P1/P2 alerts; DORA-specific incident report template maintained in shared documentation Incident severity matrix; notification-service webhook configuration
Art. 24 — Resilience Testing Conduct regular resilience testing including DR drills and (for significant entities) TLPT Quarterly DR activation drills; ECR image scanning via AWS Inspector; ASG recovery tests; MongoDB backup restoration tests Quarterly test reports; Inspector scan results; backup restoration logs
Art. 25 — TLPT (significant entities) Conduct threat-led penetration testing every 3 years AWS Inspector network reachability; third-party VAPT engagement recommended for organizations classified as DORA significant entities Inspector findings; VAPT engagement scope documentation
Art. 28 — Third-Party ICT Risk Assess and monitor ICT third-party service providers SBOM published with all third-party components (Section 10.3); ECR image scanning; CloudHedge vendor SLA; read-only source repo tokens; no third-party write access to production SBOM document; ECR scan reports; vendor contract SLA terms
Art. 45 — Information Sharing Participate in cyber threat intelligence sharing Security advisories published per release; SBOM shared with customer security team upon request; CloudHedge security advisory mailing list; release notes include security fix summaries Release notes; security advisory emails; SBOM distribution records

10.2 Incident Severity Matrix

Severity Definition Example Scenarios Response SLA DORA Reporting
P1 — Critical Complete CHAI platform unavailability affecting all users; primary region EC2 failure with ASG unable to recover; EFS data loss or corruption Primary EC2 terminated and ASG fails to launch replacement within 15 min; EFS file system unavailable; MongoDB data corruption detected; all 17 services down; security breach or unauthorized data access Acknowledge: 15 min; Mitigate: 30 min (RTO target); Resolve: 4 hours Report to customer DORA Incident Manager within 2 hours of detection per the applicable support agreement; CloudHedge escalation to CTO
P2 — High Partial service degradation affecting key CHAI functions; 1–3 critical microservices down but platform partially operational; performance degraded > 50% core-engine or auth-gateway unavailable; Bedrock connectivity lost; ECR pull failures preventing service restart; ALB health check failures on > 1 target Acknowledge: 30 min; Mitigate: 2 hours; Resolve: 8 hours Notify customer operations team within 4 hours; CloudHedge support ticket P2
P3 — Medium Non-critical service degradation; minor feature unavailability; intermittent errors affecting < 10% of requests report-service slow or failing (reports not generating); notification-service down (email alerts delayed); ch-user-guide unavailable; non-critical integration (Bitbucket webhook) not functioning Acknowledge: 2 hours; Mitigate: 8 hours; Resolve: 24 hours Notify customer operations team within 24 hours; CloudHedge support ticket P3
P4 — Low Informational; minor issues with no user impact; planned maintenance windows; non-urgent configuration changes SSL certificate expiry warning (> 30 days out); log volume approaching CloudWatch retention limit; minor security advisory in non-critical dependency; documentation update needed Acknowledge: 24 hours; Resolve: 5 business days No regulatory notification required; document in change log

10.3 SBOM Management

CloudHedge maintains a published Software Bill of Materials (SBOM) for every CHAI release. The SBOM documents all first-party and third-party software components and their versions. Image scanning is performed automatically on every ECR image push via AWS Inspector Enhanced Scanning, and a full SBOM report is generated with each release. Customers may request the SBOM for any release from their CloudHedge account team.

SBOM Technology Stacks:

Layer Components
Runtime — Node.js Node.js 16.16.x / >=18.20.x, Express.js 4.18.x, jsonwebtoken 9.0.x, bcrypt 5.1.x, passport-saml 3.1.x, mongoose 7.x
Runtime — Frontend React 18.2.x, webpack 5.x, axios 1.x
Runtime — Go Go >=1.10.x (cruize-service, aws-lift-shift, discover-service-windows, transform-service-windows, discover-service-aix)
Runtime — Python Python 3.6.x (discover-service-linux, transform-service-linux, discover-service-aix)
Infrastructure Nginx 1.22.x, MongoDB 7.0.12, Podman 3.x/4.x
Base Images RHEL UBI 8.10.x, RHEL UBI 9.5.x (selected services)
Auth jsonwebtoken 9.0.x, bcrypt 5.1.x, passport-saml 3.1.x

10.4 IAM Policy Reference

The following IAM policy represents the minimum permissions required for the CHAI EC2 instance role. This policy follows the principle of least privilege and should be attached to an IAM role assigned to the CHAI EC2 instance profile. No inline policies, wildcard accounts, or administrative permissions should be granted.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EFSAccess",
      "Effect": "Allow",
      "Action": [
        "elasticfilesystem:ClientMount",
        "elasticfilesystem:ClientWrite",
        "elasticfilesystem:ClientRootAccess"
      ],
      "Resource": "arn:aws:elasticfilesystem:us-east-1:<ACCOUNT_ID>:file-system/<EFS_ID>"
    },
    {
      "Sid": "SSMParameterAccess",
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter",
        "ssm:GetParameters",
        "ssm:GetParametersByPath"
      ],
      "Resource": "arn:aws:ssm:us-east-1:<ACCOUNT_ID>:parameter/chai/*"
    },
    {
      "Sid": "ECRAccess",
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchCheckLayerAvailability"
      ],
      "Resource": "*"
    },
    {
      "Sid": "BedrockAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-sonnet-4-6",
        "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-opus-4-6",
        "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-haiku-4-5-20251001",
        "arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-text-express-v1",
        "arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-embed-text-v2:0",
        "arn:aws:bedrock:us-east-1::foundation-model/meta.llama3-70b-instruct-v1:0"
      ]
    },
    {
      "Sid": "CloudWatchMetricsAndLogs",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:PutMetricData",
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams"
      ],
      "Resource": "*"
    }
  ]
}

10.5 Access Control Matrix

Role CHAI Web UI SSH to EC2 AWS Console (CHAI resources) ECR Push Bedrock Direct Access Incident Response
CHAI End User Full access (assigned tenants) No No No No View P3/P4 tickets
CHAI Platform Administrator Full access (all tenants) No Read-only (CloudWatch) No No Create/manage P1–P4 tickets
Customer Infrastructure Engineer No Yes (via bastion, key-based) Read/Write (EC2, EFS, ALB) No No P1/P2 DR activation authority
CloudHedge Support Engineer Admin access (support sessions only) Yes (authorized during incidents) Read-only (CloudWatch, ECR) No No P1/P2 incident response; escalation to CloudHedge CTO
CloudHedge Release Engineer No No ECR Push (CI/CD pipeline role only) Yes (specific ECR repos) No N/A
Customer Security / Compliance No No Read-only (CloudTrail, Config, Inspector) No No DORA incident reporting; SBOM review
Automated (CI/CD Pipeline) No No Scoped: ECR push, ASG launch, ALB registration Yes No Automated P4 alert creation on deployment failure

11. Operational Runbook

This section covers infrastructure operations (start, stop, upgrade, backup, monitor). For application-level operations — managing users, tenants, projects, and running assessments — see the CHAI User Guide.

11.1 Appliance Lifecycle Commands

All CHAI appliance lifecycle operations are performed using the chctl command-line tool, which abstracts Podman orchestration into human-readable, atomic operations. chctl must be run as root or with sudo.

Command Description When to Use Expected Output
sudo chctl start appliance Start all 17 CHAI microservices in dependency order Post-boot startup; after a planned maintenance window; after DR activation All services transition to running state within 5–8 minutes

First-Time Deployment? After starting the appliance for the first time, access the CHAI web UI at https://<alb-hostname> to complete initial setup: create the first admin user, activate the license key, and configure your first project. See the CHAI User Guide — Getting Started for the step-by-step setup wizard walkthrough.
| sudo chctl stop appliance | Gracefully stop all 17 services in reverse dependency order (MongoDB last) | Before taking an AMI snapshot; before data migration; planned maintenance | All services transition to stopped state; MongoDB performs clean shutdown |
| sudo chctl restart appliance | Stop then start all 17 services | After updating chctl-compose.yaml; after a configuration change affecting multiple services | Full restart cycle; expect ~10 minutes total |
| sudo chctl restart <service> | Restart a single named service (e.g., core-engine) | After a single service crash; after updating a single service's environment variable | Named service restarts without affecting other services |
| sudo chctl status | Display running state of all 17 services | Health verification; post-startup validation; troubleshooting | Table showing service name, container ID, state, port, uptime |
| sudo chctl status <service> | Display detailed status of a single named service | Deep troubleshooting of a specific service | Container metadata, environment variables, mount points, recent log tail |
| sudo chctl logs <service> | Tail live logs for a named service (wraps podman logs -f) | Real-time troubleshooting; monitoring startup sequences | Streaming log output; Ctrl+C to exit |
| sudo chctl upgrade | Pull latest container images from ECR and restart services with new images | During planned release upgrades (e.g., 2.1.6-12 → 2.1.6-13) | Pulls new images, stops old containers, starts new containers; data preserved on EFS |
| sudo chctl backup | Trigger an on-demand MongoDB backup to the configured backup path | Before major changes; supplement to automated EFS backup policy | Backup archive created at /mnt/efs/backups/<timestamp>/ |
| sudo chctl health | Run end-to-end health check across all services and external integrations | Pre-incident validation; post-upgrade verification | Pass/Fail status per service and integration; total health score |

11.2 Appliance Upgrade Procedure

To upgrade CHAI to a new release version:

  1. Review release notes for the target version at the CloudHedge support portal
  2. Create a backup AMI of the current running instance: sudo chctl snapshot
  3. Pull new images from ECR: sudo chctl pull --tag ch-rel-<new-version>
  4. Stop the appliance: sudo chctl stop appliance
  5. Start with new images: sudo chctl start appliance
  6. Verify health: sudo chctl health — all services should show PASS
  7. Verify version: sudo chctl version — should show the new release tag

Rollback: If the upgrade fails health checks, run sudo chctl pull --tag ch-rel-<previous-version> followed by sudo chctl stop appliance && sudo chctl start appliance to restore the previous version. MongoDB data on EFS is version-independent and is not affected by container image upgrades.

For detailed release notes and upgrade advisories, contact CloudHedge support or visit the CHAI User Guide.

11.3 Log Management

CHAI microservice logs are written to stdout/stderr within Podman containers and captured by CloudWatch Logs Agent running on the EC2 instance. Log retention is configured per-service based on volume and compliance requirements.

Log File Paths (on EC2 instance):

Log Type Path / Log Group Retention Description
Podman Container Logs podman logs <service-name> (real-time) In-memory (container lifetime) Accessed via chctl logs <service> or directly with podman logs
CloudWatch Log Group — Core /chai/core-engine 90 days Core orchestration, job dispatch, Bedrock API calls
CloudWatch Log Group — Auth /chai/auth-gateway-service 90 days Authentication events, JWT validation failures, SAML assertions
CloudWatch Log Group — All Services /chai/<service-name> 30 days (standard services) Per-service application logs for all 17 microservices
CloudWatch Log Group — Activity /chai/activity-service 365 days DORA-relevant audit log — all user actions and system events; extended retention for compliance
CloudTrail Logs S3: s3://chai-audit-logs-<account>/cloudtrail/ 90 days All AWS API calls; IAM actions; EC2, EFS, ECR operations
Nginx Access Logs /mnt/efs/nginx/logs/access.log 30 days (rotated by logrotate) All HTTP/HTTPS requests to the CHAI web UI
Nginx Error Logs /mnt/efs/nginx/logs/error.log 30 days (rotated by logrotate) Nginx-level errors; upstream connection failures

11.4 Monitoring & Alerting

CloudWatch alarms are configured to alert the operations team on the following conditions. All P1/P2-threshold alarms route to the customer incident management system via SNS topic → webhook → ticketing integration.

Metric CloudWatch Namespace Alarm Threshold Alarm Action DORA Relevance
EC2 CPU Utilization AWS/EC2 > 85% for 5 consecutive minutes SNS → P2 alert; consider EC2 resize ICT Risk — performance degradation signal
EC2 Status Check Failed AWS/EC2 StatusCheckFailed_Instance = 1 SNS → P1 alert; ASG terminates and replaces instance ICT Risk — instance-level hardware failure
EFS ClientConnections AWS/EFS = 0 for 3 consecutive minutes (during business hours) SNS → P1 alert ICT Risk — EFS connectivity lost; MongoDB data unavailable
EFS PercentIOLimit AWS/EFS > 80% for 10 consecutive minutes SNS → P2 alert; consider EFS provisioned throughput ICT Risk — storage I/O saturation affecting MongoDB performance
ALB Healthy Host Count AWS/ApplicationELB < 1 for 2 consecutive minutes SNS → P1 alert; trigger DR assessment ICT Incident — all CHAI instances unhealthy
ALB HTTP 5xx Error Rate AWS/ApplicationELB > 5% of requests over 5 minutes SNS → P2 alert Incident Detection — backend service errors
CloudWatch Logs — ERROR rate /chai/core-engine (custom metric filter) > 10 ERROR log events per minute SNS → P3 alert Incident Detection — application-level error spike
MongoDB EFS Bytes Written Custom (from activity-service) = 0 for 15 minutes during active jobs SNS → P2 alert ICT Risk — MongoDB not writing; potential data integrity issue

11.5 Health Check Procedure

Execute this procedure after any appliance restart, upgrade, DR activation, or infrastructure change to confirm full operational status.

  1. Verify all services are running.

       sudo chctl status
       # Expected: All 17 services in "running" state; no "exited" or "error" status
       

  2. Confirm EFS is mounted.

       df -h | grep efs
       # Expected: /mnt/efs mounted with expected available capacity
       mount | grep efs
       # Expected: EFS ID visible with tls,iam options
       

  3. Confirm MongoDB is accessible and data is present.

       podman exec -it db-service mongosh --eval "db.adminCommand('ping')"
       # Expected: { ok: 1 }
       podman exec -it db-service mongosh --eval "show dbs"
       # Expected: chai_db visible with non-zero size
       

  4. Test ALB health endpoint.

       curl -k https://<ALB_DNS_NAME>/api/health
       # Expected: HTTP 200; JSON body with {"status":"healthy","services":17}
       

  5. Confirm Bedrock connectivity.
    In the CHAI web UI: Settings → AI Configuration → Test Bedrock Connection.
    Expected: "Connection successful" with response latency < 2 seconds.

  6. Verify CloudWatch log ingestion.
    In AWS Console: CloudWatch → Log Groups → /chai/core-engine. Confirm log events are being written within the last 5 minutes.

  7. Run CHAI health command.

       sudo chctl health
       # Expected: All services PASS; all integrations PASS; overall health score 100%
       

  8. Confirm web UI login.
    Open the CHAI web URL in a browser. Log in with an admin account. Confirm the dashboard loads and displays existing application portfolio data from MongoDB.


Appendix A — Port Reference

A.1 Internal Ports

Ports used by CHAI microservices for inter-service communication. All traffic runs on the cloudhedge Podman network (10.90.0.0/16) and does not traverse the VPC or internet. These ports are never exposed to end users or external systems.

# Service Port Protocol Direction Notes
1 webapp (Nginx HTTP) 8080 HTTP / TCP ALB → webapp SSL terminated at ALB; webapp receives plain HTTP from ALB
2 webapp (Nginx HTTPS) 8443 HTTPS / TCP Internal Direct HTTPS if bypassing ALB; used in dev/test only
3 auth-gateway-service 3000 HTTP / TCP webapp → auth-gateway Called by webapp for all authentication and authorization checks
4 core-engine 3001 HTTP / TCP webapp, auth-gateway → core-engine Central orchestration; receives all API calls from webapp
5 cloud-infra-service 3002 HTTP / TCP core-engine → service Called by core-engine for cloud resource provisioning operations
6 notification-service 3005 HTTP / TCP core-engine → service Called by core-engine; delivers email and webhook notifications
7 vault-service 3006 HTTP / TCP core-engine, all services → vault Encrypted credential storage; called by all services needing secrets
8 activity-service 3007 HTTP / TCP All services → activity Audit log service; all user and system events recorded here
9 report-service 3009 HTTP / TCP core-engine → service Report generation; produces DART assessment and compliance artifacts
10 license-service 3011 HTTP / TCP core-engine → service License validation; called on startup and periodically during operation
11 cruize-service 3012 HTTP / TCP core-engine → service AI orchestration; manages Bedrock model invocations and prompt chaining
12 aws-lift-shift 4005 HTTP / TCP core-engine → service Lift-and-shift migration executor for EC2/ECS/EKS rehosting
13 discover-service-linux 5001 HTTP / TCP core-engine → service Linux discovery coordinator; manages remote SSH discovery sessions
14 transform-service-linux 5003 HTTP / TCP core-engine → service Linux transformation; AI-assisted Dockerfile generation for Linux apps
15 transform-service-windows 5004 HTTP / TCP core-engine → service Windows transformation; converts Windows apps via Windows Build Box
16 discover-service-windows 5005 HTTP / TCP core-engine → service Windows discovery coordinator; manages remote WinRM discovery sessions
17 discover-service-aix 5006 HTTP / TCP core-engine → service AIX/UNIX discovery coordinator; manages remote SSH discovery on IBM AIX
18 ch-user-guide 8001 HTTP / TCP webapp → service (proxied) Static in-product documentation; proxied via Nginx in webapp
19 db-service (MongoDB) 27017 MongoDB Wire / TCP core-engine, vault, activity, report → DB Primary datastore; all service state and assessment data
20 Amazon EFS 2049 NFS v4.1 / TCP CHAI EC2 → EFS NFS mount for persistent storage; encrypted via TLS mount helper

A.2 External Ports

Ports used by users or external systems to communicate with CHAI. These ports must be open on the relevant security groups and accessible from the specified sources.

# Component Port Protocol Direction Source Notes
1 ALB (HTTPS) 443 HTTPS / TCP Inbound → ALB End users / enterprise network Primary access point; ACM certificate; routes to webapp :8080
2 ALB (HTTP redirect) 80 HTTP / TCP Inbound → ALB End users / enterprise network HTTP to HTTPS redirect only; no application traffic
3 CHAI EC2 (Admin SSH) 22 SSH / TCP Inbound → EC2 Ops team / bastion host Administrative access; key-based authentication; restrict to admin CIDR
4 Linux Build Box 22 SSH / TCP CHAI EC2 → Build Box CHAI platform EC2 CHAI initiates SSH for Linux container builds; key-based auth via vault-service
5 Windows Build Box 5986 WinRM HTTPS / TCP CHAI EC2 → Build Box CHAI platform EC2 CHAI initiates WinRM for Windows container builds; credentials via vault-service
6 Source Hosts (Linux discovery) 22 SSH / TCP CHAI EC2 → source hosts CHAI platform EC2 Outbound SSH to Linux application servers during DART discovery phase
7 Source Hosts (Windows discovery) 5986 WinRM HTTPS / TCP CHAI EC2 → source hosts CHAI platform EC2 Outbound WinRM to Windows application servers during DART discovery phase
8 AWS ECR / Bedrock / SSM / S3 443 HTTPS / TCP CHAI EC2 → AWS services CHAI platform EC2 Via VPC PrivateLink endpoints where configured; NAT Gateway fallback
9 Source Code Repositories 443 HTTPS / TCP CHAI EC2 → SCM CHAI platform EC2 GitHub, GitLab, Bitbucket; read-only token-based access
10 MCP SSE Server 30080 HTTP SSE / TCP CHAI Universe → MCP server CHAI Universe client Optional CHAI MCP™ integration; configurable port; see CHAI MCP Installation Guide

Appendix B — AWS Cost Estimate

Cost Estimate Notes: The following estimates are monthly costs for a single CHAI deployment in us-east-1 using on-demand pricing. Actual costs vary based on deployment topology (single EC2 vs Multi-AZ), instance family, EFS usage, Bedrock inference volume, and applicable AWS enterprise discount. Reserved Instance or Savings Plans pricing can reduce EC2 costs by 30–60%. For a customized TCO estimate based on your deployment requirements, contact CloudHedge sales.

The following estimates are based on us-east-1 on-demand pricing as of March 2026. Actual costs will vary based on usage patterns, reserved instance commitments, and enterprise discount programs. All estimates assume continuous 24/7 operation.

AWS Service Configuration Estimated Monthly Cost (USD) Notes
EC2 — CHAI Primary m7i.xlarge, on-demand, 24/7 $220 ~$0.302/hr; use Reserved Instance (1-yr) for ~40% savings (~$132/mo)
EC2 — Linux Build Box t3.large, on-demand, 24/7 $60 Can be stopped when no builds running; savings-mode: ~$15/mo if stopped 75% of time
EC2 — Windows Build Box t3.large, Windows, on-demand, 24/7 $115 Windows licensing premium; can be stopped when not in use
Application Load Balancer 1 ALB, ~100 GB processed/mo $20 $0.008/hr + $0.008/LCU-hr; minimal LCU usage for typical CHAI traffic
Amazon EFS 100 GB average stored, General Purpose $35 $0.30/GB-month standard storage; 100 GB × $0.30 = $30 + throughput
EFS Replication (DR) Continuous replication to us-west-1 $25 $0.25/GB replicated; assumes 100 GB × $0.25
EC2 — DR Standby (us-west-1) m7i.xlarge, stopped (EBS charges only) $15 EBS 150 GB gp3 at $0.10/GB-month; EC2 stopped = no instance charge
EFS DR (us-west-1) 100 GB replica $30 Same rate as primary EFS
AWS ECR 30 GB stored (all release tags) $3 $0.10/GB-month; data transfer within region free
AWS Bedrock Claude Sonnet 4.6 — ~2M tokens/month $60 $3.00/1M input tokens, $15/1M output tokens; estimate 2M mixed
Amazon CloudWatch Logs 10 GB/month, 8 alarms, dashboards $25 Log ingestion $0.50/GB; metrics and alarms additional
AWS CloudTrail Multi-region trail, S3 storage $10 First trail free; S3 storage for logs
NAT Gateway 1 NAT GW, ~50 GB processed/mo $35 $0.045/hr ($33/mo) + $0.045/GB data processed
Data Transfer Out ~20 GB/month to users $2 First 100 GB/month at $0.09/GB
AWS Systems Manager Parameter Store standard tier $0 Standard parameters free; advanced: $0.05/parameter/month
Total Estimated Monthly ~$655/month Excludes Marketplace AMI subscription fee; excludes enterprise discounts
With Reserved Instances (1-yr) EC2 m7i.xlarge + t3.large reserved ~$470/month ~28% savings via RI commitment on compute

Appendix C — Deployment Checklist

flowchart TD A["Start New CHAI Deployment"] --> B["Subscribe to CHAI AMI\non AWS Marketplace\nSKU: 5xtx6bcy9hcg3lj48z84f2li9"] B --> C["Create VPC and Subnets\nPublic for ALB (3 AZs)\nPrivate for EC2 and EFS (3 AZs)"] C --> D["Create Security Groups\nchai-ec2-sg · chai-efs-sg · chai-alb-sg\nchai-build-linux-sg · chai-build-windows-sg"] D --> E["Create IAM Role and Instance Profile\nEFS + ECR + Bedrock + CloudWatch permissions\nAttach minimum IAM policy from Section 10.4"] E --> F["Launch EC2 from CHAI AMI\nm7i.xlarge · 150 GB EBS gp3\nAssign IAM instance profile · Private subnet"] F --> G["Create and Mount Amazon EFS\nCreate EFS with 3 mount targets\nmkdir /mnt/efs · mount -t efs\nUpdate /etc/fstab"] G --> H["Migrate Data to EFS\n/mnt/efs/mongodb — database files\n/mnt/efs/shared — application files\n/mnt/efs/nginx — config and TLS certs"] H --> I["Update chctl-compose.yaml\nReplace /opt/appliance/ paths\nwith /mnt/efs/ paths for all volumes"] I --> J["Create Golden AMI from Configured Instance\nTag: CHAI-golden-v2.1.6-13-rhel8.10"] J --> K["Create Launch Template and ASG\nReference golden AMI\nDesired:1 · Min:1 · Max:1\nAssign IAM instance profile"] K --> L["Create ALB and Target Group\nHTTPS :443 listener\nACM certificate\nTarget Group :8080 · Health check /api/health"] L --> M["Configure Build Boxes\nLinux Build Box: SSH :22\nWindows Build Box: WinRM :5986\nStore credentials in CHAI vault"] M --> N["Configure Bedrock VPC Endpoint\ncom.amazonaws.us-east-1.bedrock-runtime\nEnable required foundation models in Bedrock console"] N --> O["Setup DR Environment in us-west-1\nCreate EFS + configure replication from primary\nLaunch DR EC2 from golden AMI (stopped)\nCreate DR ALB (standby)"] O --> P["Configure CloudWatch\nCreate log groups per service\n8 metric alarms + SNS topic\nDashboard for operational visibility"] P --> Q["CHAI Deployment Complete\nVerify via web UI login\nsudo chctl health — all services PASS"]

Appendix D — Legal & Trademarks

Intellectual Property

This document and all referenced CHAI platform software are the intellectual property of CloudHedge Technologies Inc. All rights reserved. No part of this document may be reproduced, distributed, or transmitted in any form or by any means without the prior written permission of CloudHedge Technologies Inc., except as expressly authorized in the applicable software license agreement between CloudHedge Technologies Inc. and the licensee.

Trademarks

CHAI™, CHAI DART™, CHAI Flow™, and CHAI Universe™ are trademarks of CloudHedge Technologies Inc., registered or pending registration in the United States and other jurisdictions. R6Ai® is a registered trademark of CloudHedge Technologies Inc. The CloudHedge name and logo are trademarks of CloudHedge Technologies Inc.

All other trademarks, service marks, product names, and company names mentioned in this document are the property of their respective owners. References to third-party products, services, and trademarks do not constitute or imply endorsement, sponsorship, or affiliation by CloudHedge Technologies Inc.

Regulatory References

License & Warranty Disclaimer

THE CHAI PLATFORM SOFTWARE IS PROVIDED UNDER THE TERMS OF THE CLOUDHEDGE ENTERPRISE LICENSE AGREEMENT. THE PLATFORM IS PROVIDED "AS IS" WITH RESPECT TO THIRD-PARTY OPEN-SOURCE COMPONENTS. CLOUDHEDGE TECHNOLOGIES INC. MAKES NO WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIRD-PARTY SOFTWARE COMPONENTS IDENTIFIED IN THE SBOM. CLOUDHEDGE'S OBLIGATIONS WITH RESPECT TO DEFECTS, UPTIME, AND SUPPORT ARE EXCLUSIVELY GOVERNED BY THE APPLICABLE ENTERPRISE LICENSE AGREEMENT AND SUPPORT ADDENDUM.

Legacy Product Note

For historical reference only: CHAI is the successor platform to the CloudHedge legacy product line. All new deployments use the CHAI platform. References to legacy product nomenclature in prior customer agreements should be interpreted as referencing the current CHAI platform for all purposes of the applicable agreement.

Contact

CloudHedge Technologies Inc.
33 Wood Avenue S, Suite 600
Iselin, NJ 08830, USA
Web: cloudhedge.io
Support: support@cloudhedge.io
Security: security@cloudhedge.io