Installation

Evolve supports development on macOS, Windows (WSL), and Linux environments. This guide walks you through installation, environment setup, and running the platform locally.

Prerequisites

Tool	Purpose
Node.js 24+	JavaScript runtime
pnpm (via corepack)	Package manager
go-task	Task runner
1Password CLI	Environment variable management
Docker	Local development services

Installation

macOS

brew install node@24 go-task 1password-cli
corepack enable
pnpm install

Windows (WSL)

Install WSL 2 with the default Ubuntu distro:
Terminal window
```
wsl --install
```
Install Homebrew, then install dependencies:
Terminal window
```
brew install go-task nvm 1password-cli
```
Install Node.js 24 and enable corepack:
Terminal window
```
nvm install 24
corepack enable
```

Linux / Ubuntu

Install Node.js 24+ using a package manager of your choice.
Install 1Password CLI.
Install Task:
Terminal window
```
snap install task --classic
```

Environment setup

Evolve uses 1Password to manage environment variables. A fully working .env file is available in your project’s shared vault:

task get-env

Running the development server

pnpm dev

Visit the storefront at http://localhost:3000.

Local HTTPS with Portless

For OAuth callbacks, secure cookies, and the authoring chrome’s cross-subdomain session probe, you’ll want real HTTPS. Evolve uses Portless to put every service behind a stable *.evolve.localhost hostname with a system-trusted cert:

pnpm dev:setup-portless    # one-time per machine
pnpm dev:secure            # same as pnpm dev, served over HTTPS

See Local HTTPS with Portless for the full walk-through, including how to add new services and the SameSite-cookie reasoning behind the two-level domain.

Local development services

A Docker Compose file provides supporting services for local development:

Service	URL
Redis	—
Jaeger (OpenTelemetry)	http://localhost:16686
Mailpit (local SMTP)	http://localhost:8025

task docker:services    # start
docker compose down     # stop

Useful commands

Command	Description
`pnpm dev`	Start the full development environment
`pnpm check`	Run formatting, typechecking, linting, and Terraform checks
`pnpm test`	Run all tests
`pnpm codegen`	Generate GraphQL types and schema files
`task get-env`	Pull latest `.env` from 1Password
`task docker:services`	Start Redis, Jaeger, and Mailpit

API testing with Bruno

Example GraphQL Gateway API calls are included in the api-collection folder, meant to be used with the Bruno API Client:

Download and install Bruno.
Import the collection from the api-collection folder.
Select the correct environment (top right corner) and execute calls.

Next steps

Learn about Evolve’s architecture and how services are organized.
Explore the technology stack to understand the frameworks and tools used.
Read the frontend and backend development guides.

Relevant links

Documentation	Demo environments
GitHub	AWS / Commercetools / Storyblok
Storybook	GCP / Commercetools / Storyblok
Figma design system	Azure / Commercetools / Storyblok
Lab Digital engineering docs