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

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

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

```bash
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

```bash
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:

```bash
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:

```bash
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`:

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

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

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

Then start Node-RED:

```bash
node-red
```

## Your first flow

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

```bash
# 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

```mermaid
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](Architecture) | Internalise the 3-tier (entry → nodeClass → specificClass) pattern. |
| [Topology-Patterns](Topology-Patterns) | See typical plant configs end-to-end with verified edges. |
| Pick a node | The most mature is [pumpingStation](https://gitea.wbd-rd.nl/RnD/pumpingStation/wiki/Home) (refactor pilot). |
| [Topic-Conventions](Topic-Conventions) | Reference for naming when you start wiring your own flows. |
| [Telemetry](Telemetry) | If you're plumbing InfluxDB or Grafana. |

## Quick command reference

```bash
# 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](Home) — top-level navigation
- [Architecture](Architecture) — how a node is built
- [Topology-Patterns](Topology-Patterns) — plant configurations