EVOLV/wiki/Getting-Started.md

Getting Started

Reflects code as of 9ab9f6b · regenerated 2026-05-11

How to clone, install, and run EVOLV locally; how to deploy the example flows; and where to go next.

Prerequisites

Tool	Version	Why
Node.js	≥ 18 LTS	Node-RED 4 requires 18+
npm	≥ 9	Comes with Node.js
git	≥ 2.35	Submodule support
Docker + compose v2	optional	For the local Node-RED + InfluxDB stack
WSL2 (on Windows)	optional	Recommended for native docker performance

Clone and install

git clone --recurse-submodules https://gitea.wbd-rd.nl/RnD/EVOLV.git
cd EVOLV
npm install

If you cloned without --recurse-submodules, run:

git submodule update --init --recursive

There are 12 submodules — one per node (generalFunctions plus 11 active nodes). Each lives under nodes/<name>/.

Verify the platform builds

npm run test:platform   # expect 823 / 0

This runs the full unit test suite across all 12 submodules. ~3 minutes on a workstation (reactor's mathjs initialisation dominates).

Option A — Run via Docker (recommended)

The repo ships a docker-compose.yml that brings up Node-RED + InfluxDB pre-loaded with the EVOLV nodes:

docker compose up -d

When healthy:

Service	URL
Node-RED editor	http://localhost:1880
FlowFuse dashboard (if widgets installed)	http://localhost:1880/dashboard
InfluxDB UI	http://localhost:8086

Watch the container logs while you click around:

docker compose logs -f nodered

WSL2 note: use the native docker from Ubuntu, not docker.exe from Windows Docker Desktop. systemd docker.service should be enabled and your user in the docker group. Compose v2 plugin lives at ~/.docker/cli-plugins/docker-compose.

Option B — Run via local Node-RED

If you already have Node-RED installed in ~/.node-red:

# in EVOLV/
ln -s "$PWD" ~/.node-red/nodes/EVOLV

Or add to your ~/.node-red/settings.js:

module.exports = {
  // ...
  nodesDir: ['/path/to/EVOLV/nodes'],
}

Then start Node-RED:

node-red

Your first flow

Each node ships with example flows under nodes/<name>/examples/. The recommended starting point is rotatingMachine — Basic Manual Control:

# Copy the example into your Node-RED user dir
cp nodes/rotatingMachine/examples/01-Basic-Manual-Control.json ~/.node-red/

In the editor:

1. Menu → Import → select the file → Import.
2. Hit Deploy.
3. Open the dashboard at http://localhost:1880/dashboard.
4. Click the startup button. Watch the state machine progress: idle → starting → warmingup → operational.
5. Drag the demand slider. The flow + power predictions update in real time.

What to read next

flowchart TB
    start[You are here]:::neutral
    arch[Architecture<br/>3-tier code structure]:::tier1
    topo[Topology-Patterns<br/>typical plant configs]:::tier1
    conv[Topic-Conventions<br/>naming + units]:::tier1
    tele[Telemetry<br/>Port 0/1/2 + InfluxDB]:::tier1
    node[Pick a node's wiki<br/>per-repo Home.md]:::tier3

    start --> arch
    start --> topo
    arch --> node
    topo --> node
    node --> conv
    node --> tele

    classDef neutral fill:#dddddd
    classDef tier1 fill:#a9daee,color:#000
    classDef tier3 fill:#50a8d9,color:#000

Path	Why
Architecture	Internalise the 3-tier (entry → nodeClass → specificClass) pattern.
Topology-Patterns	See typical plant configs end-to-end with verified edges.
Pick a node	The most mature is pumpingStation (refactor pilot).
Topic-Conventions	Reference for naming when you start wiring your own flows.
Telemetry	If you're plumbing InfluxDB or Grafana.

Quick command reference

# run all tests
npm run test:platform

# run one node's tests
cd nodes/rotatingMachine && node --test test/basic/*.test.js

# regenerate a node's wiki AUTOGEN blocks
cd nodes/rotatingMachine && npm run wiki:all

# rebuild docker stack
docker compose build && docker compose up -d

# update all submodules to their development tips
git submodule update --remote --recursive

# pack EVOLV as an npm tarball
npm pack

Where to ask for help

Channel	Use it for
Per-node wiki on Gitea	Operator-level questions for one node.
.claude/refactor/OPEN_QUESTIONS.md	Live decisions log — issues being worked on.
Gitea repo issues per submodule	File a bug against a specific node.
R&D team Slack / Teams	Anything urgent or strategic.

Related pages

• Home — top-level navigation
• Architecture — how a node is built
• Topology-Patterns — plant configurations