Skip to main content

On-VM Infrastructure Deployment

This guide covers deploying AI/Run CodeMie on a single virtual machine using Docker Compose. All three cloud providers are supported: AWS (EC2), GCP (Compute Engine), and Azure (VM).

This guide covers two deployment methods:

The deploy.sh script handles the full lifecycle: Terraform provisions cloud resources (VM, storage, networking, DNS), and Docker Compose brings up the CodeMie application stack on the provisioned VM.

Recommended Approach

Scripted deployment is the recommended method as it handles prerequisite checks, configuration validation, and proper sequencing of all operations automatically.

Prerequisites​

Before you begin, make sure you have completed all the requirements described in the On-VM Deployment Prerequisites section — account access, deployment machine tools, GCP Container Registry access (key.json), cloud authentication, and repository access for your chosen cloud provider.

Scripted Deployment​

Step 1: Clone the Repository​

git clone https://gitbud.epam.com/epm-cdme/codemie-on-vm.git
cd codemie-on-vm

Step 2: Place the GCP Registry Key​

Copy your key.json file to the repository root:

cp /path/to/key.json ./key.json

Step 3: Create Deployment Configuration​

One-Time Setup: IAM Deployer Role

Before running deploy.sh for the first time, create the IAM deployer role.

Navigate to the IAM module and apply Terraform:

cd terraform/aws/codemie-on-vm-aws-iam/

Create terraform.tfvars:

region             = "eu-north-1"
platform_name      = "codemie"
deployer_role_name = "CodemieOnVmDeployerRole"

Deploy:

terraform init
terraform plan
terraform apply
terraform output deployer_iam_role_arn
# Example: arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole

Then return to the repository root.

cp deployment.conf.example deployment.conf

Edit deployment.conf:

# AWS credentials
AWS_PROFILE=""
TF_VAR_region="eu-north-1"
TF_VAR_role_arn="arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole"

# Terraform State
TF_VAR_s3_states_bucket_name="codemie-terraform-states"

# Platform
TF_VAR_platform_name="codemie"

# EC2
TF_VAR_instance_type="r5.xlarge"   # 4 vCPU, 32 GB RAM
TF_VAR_volume_size=100
TF_VAR_access_prefix_list_ids='[]'
TF_VAR_private_ip_only=false

# Domain & TLS (optional)
TF_VAR_platform_domain_name=""

# CodeMie
CODEMIE_VERSION="2.26.0"
COMPOSE_PROFILE="enterprise"

Step 4: Authenticate with Cloud Provider​

# If using AWS SSO:
aws sso login --profile your-profile
export AWS_PROFILE=your-profile

# Verify credentials:
aws sts get-caller-identity

Step 5: Run the Deployment​

./deploy.sh

The script executes the following phases:

PhaseDescription
Loading configValidates deployment.conf variables
Checking prerequisitesVerifies required tools are installed
Verifying AWS credentialsConfirms valid AWS session
Initializing S3 remote backendCreates S3 bucket for Terraform state
Running terraformPlans and applies infrastructure (with approval prompt)
Reading terraform outputsFetches EC2 ID, IPs, S3 bucket, KMS key
Generating .envCreates secrets and renders Docker Compose environment
Provisioning EC2Installs Docker, syncs files, starts services
Writing outputsSaves credentials to deployment_outputs.env
Deployment summaryPrints URL, SSH command, credentials
Interactive Prompts

The script pauses twice for approval: remote backend Terraform plan and platform Terraform plan. Review plans carefully before typing y.

Step 6: Verify Deployment​

curl -k https://<CODEMIE_HOST>/v1/healthcheck

Expected response: {"status":"ok"}

Deployment Outputs​

The script creates deployment_outputs.env with:

  • CODEMIE_URL — Application URL
  • SSH_COMMAND — Full SSH command for access
  • Credentials — Keycloak admin or superadmin password
  • Internal secrets — Preserved across re-runs
Sensitive File

deployment_outputs.env contains passwords and secrets. Do not commit it to version control.

SSH Access​

SSH uses AWS Systems Manager Session Manager as a proxy (no need to open port 22):

ssh -i codemie-key.pem \
  -o "ProxyCommand=aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters portNumber=%p" \
  ubuntu@<EC2_INSTANCE_ID>

Re-deploying / Updating​

To update CodeMie version or configuration:

  1. Edit deployment.conf (e.g., change CODEMIE_VERSION)
  2. Run ./deploy.sh again

The script detects the existing deployment_outputs.env and preserves all secrets. Only the Docker Compose services are updated.

Manual Deployment​

Manual deployment provides full control over each Terraform phase. Use this when you need fine-grained customization or are integrating with existing infrastructure management workflows.

After provisioning the infrastructure manually, the application is deployed using BYO mode: ./deploy.sh --byo.

Deployment Phases (AWS)

PhaseDescriptionDirectory
Phase 1: IAM Deployer RoleCreates IAM role with required permissionsterraform/aws/codemie-on-vm-aws-iam/
Phase 2: State BackendCreates S3 bucket for Terraform stateterraform/aws/remote-backend/
Phase 3: Platform InfrastructureProvisions VPC, EC2, S3, KMS, ALBterraform/aws/platform/

Phase 1: IAM Deployer Role

One-Time Setup

This phase only needs to run once per AWS account.

cd terraform/aws/codemie-on-vm-aws-iam/

Create terraform.tfvars:

region             = "eu-north-1"
platform_name      = "codemie"
deployer_role_name = "CodemieOnVmDeployerRole"

Deploy:

terraform init
terraform plan -out=tfplan
terraform apply tfplan
terraform output deployer_iam_role_arn

Phase 2: Terraform State Backend

cd terraform/aws/remote-backend/
terraform init
terraform plan -out=tfplan \
  -var="region=eu-north-1" \
  -var="role_arn=arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole" \
  -var="bucket_name=codemie-terraform-states"
terraform apply tfplan

Phase 3: Platform Infrastructure

cd terraform/aws/platform/

Create backend.tfvars:

bucket       = "codemie-terraform-states"
key          = "codemie/terraform.tfstate"
region       = "eu-north-1"
use_lockfile = true

Create terraform.tfvars:

region                 = "eu-north-1"
role_arn               = "arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole"
platform_name          = "codemie"
instance_type          = "r5.xlarge"
volume_size            = 100
private_ip_only        = false
platform_domain_name   = ""
access_prefix_list_ids = []
terraform init -backend-config=backend.tfvars
terraform plan -out=tfplan
terraform apply tfplan

# Note outputs for Phase 4:
terraform output ec2_instance_id
terraform output ec2_public_ip
terraform output s3_bucket_name
terraform output kms_key_id
terraform output ssm_ec2_private_key

Fetch the SSH key from SSM:

aws ssm get-parameter \
  --name "$(terraform output -raw ssm_ec2_private_key)" \
  --region eu-north-1 \
  --with-decryption \
  --query "Parameter.Value" \
  --output text > codemie-key.pem
chmod 600 codemie-key.pem

After completing infrastructure provisioning, proceed to Application Provisioning (BYO Mode) to deploy the CodeMie stack.

Next Steps​

Infrastructure provisioning is complete. Proceed to Application Provisioning (BYO Mode) to deploy the CodeMie stack onto the provisioned VM.