Skip to content
EvolveEvolveEvolve

Installation

A new Evolve project starts from a copy of a reference site. The Evolve team gives you the one that fits your project, as a zip without Git history, so it becomes the first commit of your own repository. Both are complete: a Next.js storefront, the services behind it, the GraphQL gateway, and the Terraform and deploy configuration to put it online.

Reference site Built for Commerce CMS Payments Search Cloud
B2C Consumers, with business accounts when a shopper has one commercetools Storyblok Adyen, Mollie commercetools Google Cloud
B2B Companies: business units, quotes, approvals commercetools Contentful Mollie, pay on account commercetools or Algolia Azure

This page takes your copy from a zip to a storefront in your browser.

Before you start

Section titled “Before you start”

Install these tools:

Tool Version What it is for
Node.js 26.3, the version in .nvmrc Runs the services and the storefront
pnpm 12, pinned in packageManager in package.json Installs the packages
Docker Any recent version Runs the gateway and the local services
Task Any recent version Runs the project’s tasks, such as composing the gateway’s schema
GitHub CLI Any recent version Signs Docker in to the gateway image
Terraform 1.8 or later Checks the configuration/ folder in pnpm check, and deploys later

Ask the Evolve team for:

  • An invite to the Evolve registry. The @evolve-framework/* and @evolve-storefront/* packages come from a private npm registry at npm.registry.evolve-platform.com. You sign in with GitHub, so the invite goes to your GitHub account.

  • Access to the gateway image. The GraphQL gateway runs from a private image, ghcr.io/evolve-platform/evolve-graphql-gateway. Your GitHub account needs read access to it. You also need your own vendor accounts. The copy runs on no shared accounts: every credential in it is yours.

  • A commercetools project, with an API client for each service.

  • A space in the CMS of your reference site: Storyblok for B2C, Contentful for B2B.

  • Test accounts at your payment providers.

The catalog in commercetools and the content in the CMS are yours to fill. With an empty project the storefront runs, but its pages have nothing to show.

Your settings

Section titled “Your settings”

The copy has a .env.example at its root that lists every variable the services and the storefront read. Copy it to .env and fill in your own credentials. Connect your own vendors says where each value comes from.

cp .env.example .env

.env stays out of Git. To keep your settings in the repository anyway, encrypt them with SOPS: put your own age public key in .sops.yaml and run task env-encrypt. It writes .env.encrypted, which is safe to commit, and task env-decrypt turns it back into .env for everyone who has the private key.

Run it

Section titled “Run it”

  1. Unzip the copy and make it your repository.

    unzip evolve-reference-b2c.zip -d my-project
    cd my-project
    git init

  2. Sign in to the Evolve registry. Use the GitHub account that received the invite. You do this once per machine.

    npm login --scope=@evolve-framework --registry=https://npm.registry.evolve-platform.com

    The token is for the registry, so it covers the @evolve-storefront/* packages too. Your copy maps both scopes to the registry in pnpm-workspace.yaml.

  3. Sign Docker in to GitHub’s container registry, so it can pull the gateway image. You also do this once per machine.

    gh auth token | docker login ghcr.io -u <your-github-username> --password-stdin

  4. Fill in .env, as in Your settings. Every service reads it from the root of your copy.

  5. Install the packages.

    pnpm install

  6. Generate the code the project needs: GraphQL types, event types, and the gateway’s supergraph.

    pnpm codegen

    Run this before the next step. The gateway reads the supergraph that codegen writes, and stops when the file is missing.

  7. Start the local services in Docker: the gateway, Redis, a mail catcher, and the tracing tools.

    task docker:services

  8. Start the services and the storefront.

    pnpm dev

  9. Open http://localhost:3000.

What you have now

Section titled “What you have now”

Your storefront runs on your machine, on your own commerce engine and CMS. Once your project has products and content, browse the catalog, sign up, and fill a cart.

URL What it is
localhost:3000 Your storefront
localhost:4000/graphql The GraphQL gateway, the API the storefront calls
localhost:4001/graphql The purchase service: cart, checkout, customers, orders
localhost:4002/graphql The discover service: catalog and content
localhost:8025 Mailpit, which catches the mail the site sends
localhost:16686 Jaeger, with a trace of every request

pnpm dev stops with Ctrl+C. The Docker services keep running until you stop them with docker compose down.

Next steps

Section titled “Next steps”