Cloud deployment

Evolve supports two deployment paths as first-class targets: the major cloud providers (AWS, GCP, and Azure), and Vercel.

Vercel

Evolve can run its whole stack on Vercel as one project: the storefront, the GraphQL gateway, and the domain services. Deployment uses Vercel’s own build and tooling, not Terraform or MACH Composer, and it brings preview deployments and other developer-experience features to the whole platform. See Hosting on Vercel.

Cloud providers (AWS, GCP, and Azure)

Each project runs on a single cloud provider, but the same backend services deploy to any of the three with only configuration changes. Infrastructure is managed with Terraform, orchestrated by MACH Composer, and deployed through GitHub Actions CI/CD pipelines.

graph TD;
    subgraph CI/CD
        gh["GitHub Actions"]
        mcc["MACH Composer Cloud"]
    end

    subgraph Infrastructure
        tf["Terraform"]
        mc["MACH Composer"]
    end

    subgraph Cloud providers
        aws["AWS<br/>ECS Fargate + Lambda"]
        gcp["GCP<br/>Cloud Run"]
        azure["Azure<br/>Container Apps"]
    end

    subgraph Shared services
        cdn["CDN<br/>CloudFront / Cloud LB / Front Door"]
        registry["Container registry<br/>ECR / GAR / ACR"]
        cache["Redis / ElastiCache"]
        otel["OpenTelemetry"]
    end

    gh --> mcc
    mcc --> mc
    mc --> tf
    tf --> aws
    tf --> gcp
    tf --> azure
    gh --> registry
    aws --> cdn
    gcp --> cdn
    azure --> cdn
    aws --> cache
    aws --> otel
    gcp --> otel
    azure --> otel

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:

Cloud	Registry
AWS	ECR (Elastic Container Registry)
GCP	GAR (Google Artifact Registry)
Azure	ACR (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.yaml 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:

Directorybackend/services/{service-name}/terraform/
- Directoryaws/ ECS task, ALB target group, IAM roles
  - …
- Directorygcp/ Cloud Run service, NEG, IAM
  - …
- Directoryazure/ Container App, identity, role assignments
  - …

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

Directoryfrontend/site/terraform/
- Directoryaws/ ECS + CloudFront + S3
  - …
- Directorygcp/ Cloud Run + Cloud Load Balancing
  - …
- Directoryazure/ 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

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)

Directoryconfig/
- Directoryaws/
  - demo.yaml AWS test environment
- Directorygcp/
  - demo.yaml GCP test environment
- Directoryazure/
  - 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

On the cloud-provider path, 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).

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

Choosing a cloud provider

Each project runs on a single cloud provider, chosen based on the organization’s preferences and existing infrastructure. Evolve does not run one instance across several providers at once. Supporting AWS, GCP, and Azure is about choice and portability rather than simultaneous use:

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

The backend services, Terraform modules, and CI/CD pipelines are designed so that adding or switching a cloud target requires only infrastructure configuration, not code changes. Migrating from one provider to another is supported, and a temporary state spanning two providers is possible during such a migration, managed through MACH Composer, though it is uncommon.

ObservabilityHow Evolve uses OpenTelemetry for distributed tracing, metrics, and frontend performance monitoring.

Cloud servicesDetailed breakdown of cloud services used per provider, networking, and CDN configuration.

SAAS configurationHow Evolve uses Terraform to provision and configure SAAS services like commercetools, Contentful, Storyblok, and Algolia.