Deploy from Source

Clone esp-rainmaker-neo, build it, and deploy with AWS CDK. Take this route if you intend to modify the backend or run the deployment from your own CI; otherwise Deploy With Installer needs no toolchain at all.

The repository holds the cloud backend, the CDK infrastructure, the Admin Dashboard, and the Morpheus CLI.

Prerequisites

Tool	Version	Why
AWS CLI	latest	Install. Used by cdk and the test scripts.
Go	1.26.5	Install. Builds the Lambda binaries.
Python	3.12	Install. Runs the CDK app and the integration tests.
Node.js	24	Install. Builds the Admin Dashboard.

What you need

An AWS account you own, signed in as a user or role with administrator access.

AWS region and profile

To target a specific region or named profile, export them before running any make target:

export AWS_REGION=ap-south-1
export AWS_PROFILE=dev

Both default to whatever your CLI config has — default profile and the configured region.

Clone and set up

Submodules carry parts of the build, so the recursive init is not optional:

git clone https://github.com/espressif/esp-rainmaker-neo.git
cd esp-rainmaker-neo
git submodule update --init --recursive

The CDK app and the integration tests share one Python venv:

python3 -m venv myenv
source myenv/bin/activate
pip3 install -r requirements.txt

First-time setup

make setup             # create the assets bucket and bootstrap CDK

This creates the S3 bucket CDK uses for assets and runs cdk bootstrap for the chosen account/region. Run it once per account and region.

Deploy

make deploy            # build the Go Lambdas and the dashboard, then deploy

make deploy walks the stack groups in dependency order, building the Go binaries and the dashboard frontend along the way.

Tests and local development

Backend

make lint              # static analysis
make test              # Ginkgo unit tests, with coverage
make itest-setup       # stand up the integration test infrastructure and morpheus test data
make itest             # pytest integration suite against a live deployment

The unit tests run against mocked AWS services and carry the bulk of the coverage; the integration suite exists for what only a real deployment surfaces. See Run integration tests.

Admin Dashboard

The dashboard is a React, TypeScript, Vite and Tailwind app. make deploy builds and ships it, so you only need to run these to iterate on the frontend itself:

cd dashboard
npm install
npm run dev            # http://localhost:5174

npm run lint
npm run typecheck
npm test

CLI

Morpheus — is an interactive CLI for exercising a deployment end to end, with no phone app and no hardware in the loop. It authenticates against Cognito, registers and destroys nodes, drives the REST API, connects to MQTT as either a user or a simulated device, and manages groups, sharing, push platforms, Matter association and licenses.

It reuses the backend's Python 3.12 venv, and needs two things to target a deployment:

• The deployment outputs. By default it reads rmng-outputs.json from the repo root. Pass --client-outputs to point at another file or at a published URL — the same client-outputs file the app and dashboard use, described in Deployment Details.
• AWS credentials for that deployment's account and region. Morpheus checks this on startup and refuses to run against a mismatched account; --skip-account-check overrides.

Seed a scratch deployment

itest-setup provisions a known set of users and nodes from test_config.json — registering each one, creating a default Home group per user, and associating the nodes flagged for it. On a fresh checkout it writes that file from test_config.default.json, generating passwords and device certificates. It needs admin AWS credentials, since it creates Cognito users.

make itest-setup

Contexts

Each flag drops you into an interactive prompt. The first two are raw operations, where you drive one user-side or device-side call at a time; the last two are simulators that run the sequence of those calls a real app or device is expected to perform.

Command	Layer	Gives you
--user user@example.com	raw	user-side operations
--device node_rsa	raw	device-side operations
--app-sim user@example.com	simulator	The recommended sequence of app operations
--device-sim node_multi	simulator	The recommended sequence of device operations

Add --is-admin when the account is a super admin, so it authenticates against the admin pool and unlocks the deployment-wide commands. get / post / put / patch / delete <path> [data] hit any API route directly, and typing an unknown command prints the full list for that context.

python3 cli/morpheus.py --user user@example.com

Pass the password by prompt or environment

The password is read from --password, then RMNG_PASSWORD, then an interactive prompt. Prefer the latter two — a password given on the command line is visible to other processes and lands in your shell history.

Full command reference: the Morpheus guide.