Skip to main content

Cloud deployment

Evolve runs on all three major cloud providers: AWS, GCP, and Azure. The same backend services deploy to any of them with only configuration changes. Infrastructure is managed with Terraform, orchestrated by MACH Composer, and deployed through GitHub Actions CI/CD pipelines.

Design principles​

Evolve's backend services follow twelve-factor app methodology: configuration through environment variables, stateless processes, structured logging to stdout, and fast startup with graceful shutdown. This is what makes the same container image portable across all supported cloud providers.

Containers​

Every backend service and the Next.js frontend are packaged as Docker containers. This gives you a consistent deployment unit across all clouds and environments.

In production, containers run on the cloud-native orchestration service for your chosen provider:

  • AWS: ECS Fargate (serverless containers)
  • GCP: Cloud Run (serverless containers, scales to zero)
  • Azure: Container Apps

Serverless runtimes like AWS Lambda can be used alongside containers where appropriate (for example, payment webhook handlers).

Container registries​

Each cloud uses its own container registry:

CloudRegistry
AWSECR (Elastic Container Registry)
GCPGAR (Google Artifact Registry)
AzureACR (Azure Container Registry)

The CI/CD pipeline builds images once and pushes them to the registry for the target cloud.

Local development​

Evolve includes a docker-compose.yml for local development that provides supporting services:

  • Redis: caching (port 6379)
  • Jaeger: distributed tracing UI (port 16686)
  • OpenTelemetry Collector: trace collection (ports 4317, 4318)
  • Prometheus: metrics (port 9090)
  • Mailpit: local SMTP for email testing (ports 1025, 8025)
  • MongoDB: document storage (port 27017)

This lets you run the full platform locally with an environment that closely resembles production.

Terraform​

All infrastructure is defined as code using Terraform. This covers both cloud resources and SAAS service configuration: commercetools projects, CMS spaces, search indices, and other third-party services are all provisioned through Terraform. A new environment (including all its SAAS dependencies) can be spun up from a single terraform apply.

Each service has its own Terraform configuration per cloud provider:

backend/services/{service-name}/terraform/
├── aws/          # ECS task, ALB target group, IAM roles
├── gcp/          # Cloud Run service, NEG, IAM
└── azure/        # Container App, identity, role assignments

The frontend follows the same pattern, with additional configuration for CDN and static asset hosting:

frontend/site/terraform/
├── aws/          # ECS + CloudFront + S3
├── gcp/          # Cloud Run + Cloud Load Balancing
└── azure/        # Container Apps + Front Door

Terraform remote state is stored in the cloud provider's native storage (S3 for AWS, GCS for GCP, Azure Storage for Azure), each with locking to prevent concurrent modifications.

MACH Composer​

info

MACH Composer is optional. Since all infrastructure is defined in Terraform, you can manage deployments directly with Terraform and your own CI/CD pipelines if you prefer. MACH Composer adds a convenience layer for orchestrating multi-component deployments, but it is not a requirement.

MACH Composer orchestrates the deployment of all components in the platform. It manages the composition of services, their configuration, and the Terraform execution across environments.

A MACH Composer configuration file defines:

  • Which cloud provider and region to deploy to
  • Which components (services) to include
  • How components reference each other (e.g., the checkout service needs the account service endpoint)
  • Environment-specific settings (SAAS API keys, feature flags)
config/
├── aws/
│   └── demo.yaml       # AWS test environment
├── gcp/
│   └── demo.yaml       # GCP test environment
└── azure/
    ├── tst.yaml        # Azure test environment
    └── prd.yaml        # Azure production

MACH Composer Cloud (MCC) integrates with the CI/CD pipeline to track component versions and trigger deployments when new versions are available.

CI/CD​

GitHub Actions handles the build and deployment pipeline. The key workflows:

  • Build: validates code, builds Docker images, pushes to the container registry, and registers the component version with MACH Composer Cloud
  • Deploy: triggers MACH Composer to apply the new component versions to the target environment
  • Validate: checks Terraform configurations and MACH Composer configs on pull requests

Authentication to cloud providers uses OIDC federation (no static credentials):

  • AWS: GitHub OIDC role assumption
  • GCP: Workload Identity Federation
  • Azure: OIDC with service principal

CDN and frontend hosting​

The frontend is a Next.js application deployed as a container, with a CDN in front for static assets and caching. Each cloud uses its native CDN service (CloudFront on AWS, Cloud CDN on GCP, Front Door on Azure). Vercel is supported as an alternative when its advanced features (edge functions, analytics, preview deployments) are beneficial.

See cloud services for the full service breakdown per cloud provider.

Multi-cloud strategy​

Evolve's multi-cloud support is not about running on all clouds simultaneously. Projects choose a primary cloud provider based on their organization's preferences and existing infrastructure. The value of multi-cloud support is:

  • No vendor lock-in: switch providers if requirements change
  • Client flexibility: different clients can use different clouds
  • Compliance: deploy in regions or on providers required by regulation

The backend services, Terraform modules, and CI/CD pipelines are designed so that adding a new cloud target requires only infrastructure configuration, not code changes.