Quick start guide for deploying and managing iMBrace Platform infrastructure on AWS Private Cloud

Getting Started with iMBrace DevOps Infrastructure

Welcome to the iMBrace DevOps Infrastructure documentation! This guide will help you quickly understand the system architecture and get started with deploying the iMBrace Platform on AWS Private Cloud.

🚀 Quick Start Overview

The iMBrace Platform can be deployed in two main configurations:

Single Node Deployment - Perfect for testing, PoC, or small-scale deployments
High Availability (HA) Deployment - Production-ready multi-node setup with load balancing

📋 Prerequisites

Before you begin, ensure you have the following tools and access:

Required Tools

Git - For repository management
Ansible - For infrastructure automation
Python 3 - Runtime for Ansible
SOPS - For encrypted secrets management
AWS CLI - For AWS resource management
Docker - For containerized applications
VSCode (recommended) - For code editing

Required Access

GitLab Access - To clone private repositories
AWS Account - With appropriate permissions for resource creation
SSH Key - For server access
Domain Name - For SSL certificates and DNS configuration

🏗️ Architecture Overview

The iMBrace infrastructure follows a multi-layer architecture:

┌─────────────────────────────────────────────────────────────┐
│                    Public Layer (OnServer)                  │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │app-gateway  │ │  backend    │ │ dashboard   │   ...      │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
└─────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   Load Balancers  │
                    │   (ALB + NLB)     │
                    └─────────┬─────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                   Private Layer (Engine)                    │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │ai-service   │ │   aiv2      │ │workflow-eng │   ...      │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      Data Layer                             │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │MongoDB Atlas│ │PostgreSQL   │ │ElastiCache  │   ...      │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
└─────────────────────────────────────────────────────────────┘

🛠️ Step-by-Step Deployment

1. Environment Setup

First, set up your local development environment:

# Install required tools (Ubuntu/Debian)
sudo apt update
sudo apt install git ansible python3-pip awscli docker.io

# Install SOPS
curl -LO https://github.com/mozilla/sops/releases/latest/download/sops-latest.linux
sudo mv sops-latest.linux /usr/local/bin/sops
sudo chmod +x /usr/local/bin/sops

# Configure AWS CLI
aws configure --profile imbrace

2. Repository Setup

Clone the appropriate repository based on your deployment needs:

# For Single Node Deployment
git clone https://gitlab.com/imbraceco/partners/private-cloud-single.git
cd private-cloud-single

# For HA Deployment
git clone https://gitlab.com/imbraceco/partners/private-cloud-ha.git
cd private-cloud-ha

# Switch to develop branch
git fetch --all
git checkout develop
git pull

3. Infrastructure Provisioning

Execute the Ansible playbooks to set up your infrastructure:

# Install system packages
ansible-playbook -i hosts ansible/sysinit-alux.yml

# Configure credentials
ansible-playbook -i hosts ansible/set-credentials.yml

# Clone repositories on target servers
ansible-playbook -i hosts ansible/clone-repo.yml

# Deploy containerized components
ansible-playbook -i hosts ansible/site-deploy-remote.yml

4. Application Configuration

Configure your applications using SOPS for secure secret management:

# Set AWS profile
export AWS_PROFILE=imbrace

# Decrypt secrets
sops -d ai-service/secrets.enc.env > ai-service/secrets.env

# Edit configuration
nano ai-service/secrets.env

# Re-encrypt secrets
sops -e ai-service/secrets.env > ai-service/secrets.enc.env

5. Application Deployment

Deploy your applications to the target servers:

# On each target server
sh /opt/imbrace/repos/<repo-name>/ansible/files/sync-files.sh
sh deploy-apps.sh

# Restart Nginx proxy
docker restart nginx-proxy

📚 Documentation Structure

This documentation is organized into the following sections:

Document	Purpose
Standard Private Cloud Single Node	Single-node deployment guide
Standard Private Cloud HA	Multi-node HA deployment guide
Standard HA Infra Configuration	AWS resource provisioning guide
Platform Environment Specification	Hardware and software requirements
ALB and NLB Configuration	Load balancer configuration reference

🔧 Common Tasks

Managing Secrets

# Decrypt all secrets
find . -name "*.enc.env" -exec sops -d {} \; -exec sh -c 'mv "$1" "${1%.enc.env}.env"' _ {} \;

# Encrypt all secrets
find . -name "*.env" -not -name "*.enc.env" -exec sops -e {} \; -exec sh -c 'mv "$1" "${1%.env}.enc.env"' _ {} \;

Updating Applications

# Pull latest changes
git pull origin develop

# Sync files to servers
ansible-playbook -i hosts ansible/sync-files.yml

# Restart services
ansible-playbook -i hosts ansible/restart-services.yml

Monitoring Services

# Check service status
docker ps

# View logs
docker logs <service-name>

# Restart a service
docker restart <service-name>

🚨 Troubleshooting

Common Issues

SOPS Decryption Fails
- Ensure AWS profile is set: export AWS_PROFILE=imbrace
- Check AWS credentials: aws sts get-caller-identity
Ansible Connection Issues
- Verify SSH key is added: ssh-add ~/.ssh/id_rsa
- Test connection: ansible all -i hosts -m ping
Docker Container Issues
- Check logs: docker logs <container-name>
- Verify environment variables: docker exec <container-name> env
Load Balancer Issues
- Check target group health: AWS Console → EC2 → Target Groups
- Verify security group rules
- Check DNS resolution

Getting Help

Check the detailed guides in each documentation section
Review AWS CloudWatch logs for application issues
Verify network connectivity and security group configurations
Ensure all required AWS resources are properly provisioned

🔐 Security Best Practices

Always use SOPS for managing secrets
Regularly rotate AWS access keys
Keep your infrastructure updated with security patches
Monitor AWS CloudTrail for suspicious activities
Use least-privilege IAM policies
Enable VPC Flow Logs for network monitoring

📈 Next Steps

Once you have successfully deployed the iMBrace Platform:

Configure Monitoring - Set up CloudWatch dashboards and alarms
Implement Backup Strategy - Configure automated backups for databases
Set Up CI/CD - Implement automated deployment pipelines
Security Hardening - Review and implement additional security measures
Performance Optimization - Monitor and optimize based on usage patterns

Ready to dive deeper? Check out the specific deployment guides for your chosen configuration!

Getting Started with iMBrace DevOps Infrastructure

On this page