feat: integrate EdgeX Foundry 4.0 (Odessa)

README.md

@@ -3,38 +3,49 @@
 **EdgeKit** is an open-source client/server IoT edge platform designed to run on [k3s](https://k3s.io/).  
 It provides a central MQTT broker (server) and lightweight edge agents (clients) that collect telemetry and stream it to the server via MQTT over WebSocket.
 
+EdgeKit integrates [EdgeX Foundry 4.0 (Odessa)](https://docs.edgexfoundry.org/4.0/) to add full IoT device management, Modbus connectivity, and centrally-managed security services.
+
 ---
 
 ## Architecture
 
 ```
-┌─────────────────────────────────────────┐
-│            k3s / Kubernetes             │
-│                                         │
-│  ┌───────────────────────────────────┐  │
-│  │         edgekit-server            │  │
-│  │   Eclipse Mosquitto MQTT broker   │  │
-│  │   • port 1883 – plain MQTT        │  │
-│  │   • port 9001 – MQTT over WS      │  │
-│  └───────────────────────────────────┘  │
-│            ▲              ▲             │
-│            │  WebSocket   │             │
-│  ┌─────────┴──┐    ┌──────┴─────────┐  │
-│  │   client 1 │    │   client N     │  │
-│  │ edge agent │    │  edge agent    │  │
-│  └────────────┘    └────────────────┘  │
-└─────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────┐
+│                   Central Server                         │
+│                                                          │
+│  ┌───────────────────────────────────────────────────┐   │
+│  │   edgekit-server  (Eclipse Mosquitto MQTT broker) │   │
+│  │   • port 1883 – plain MQTT                        │   │
+│  │   • port 9001 – MQTT over WS                      │   │
+│  └───────────────────────────────────────────────────┘   │
+│  ┌───────────────────────────────────────────────────┐   │
+│  │   EdgeX Security Services                         │   │
+│  │   • secret-store (OpenBao)  :8200                 │   │
+│  │   • nginx API gateway       :8443                 │   │
+│  └───────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────┘
+         ▲ WebSocket / MQTT   ▲ WebSocket / MQTT
+         │                    │
+┌────────┴───────┐   ┌────────┴────────────────┐
+│  Full k3s Node │   │   Thin Edge Node        │
+│                │   │                         │
+│ edgekit-client │   │  edgekit-thin-client    │
+│ EdgeX Core +   │   │  (single container:     │
+│ device-modbus  │   │   EdgeX + PG + MQTT)    │
+│ (10 containers)│   │                         │
+└────────────────┘   └─────────────────────────┘
 ```
 
-Each **client** is a single Docker container that:
+Each **full k3s edge node** runs:
 
-- Collects system metrics (CPU, memory, disk, network)
-- Publishes JSON payloads to `edgekit/<client-id>/metrics` every 5 seconds (configurable)
-- Automatically reconnects to the broker on failure
+- `edgekit-client` – collects system metrics and publishes them to the central MQTT broker
+- EdgeX Core Services (`core-data`, `core-metadata`, `core-command`) in separate containers
+- EdgeX Supporting Services (`support-notifications`, `support-scheduler`)
+- `device-modbus` – reads from Modbus TCP/RTU field devices
 
-The **server** is a single Eclipse Mosquitto container with both plain MQTT (1883) and WebSocket (9001) listeners.
+Each **thin edge node** runs a single `edgekit-thin-client` container that bundles all of the above (EdgeX + PostgreSQL + Mosquitto, managed by supervisord). It is hardened, standalone, and not extendable without rebuilding the image.
 
-For a deeper dive, see [docs/architecture.md](docs/architecture.md).
+For a deeper dive, see [docs/architecture.md](docs/architecture.md) and [docs/edgex.md](docs/edgex.md).
 
 ---
 
@@ -135,36 +146,86 @@ See [helm/edgekit/values.yaml](helm/edgekit/values.yaml) for the full Helm confi
 
 ---
 
-## Repository Layout
+## EdgeX Foundry integration
+
+EdgeKit embeds [EdgeX Foundry 4.0 (Odessa)](https://docs.edgexfoundry.org/4.0/) for full IoT device management and Modbus connectivity. There are **two edge client variants**:
+
+### Full k3s edge node – start the EdgeX core stack
+
+```bash
+./scripts/start-edgex-client.sh
+```
+
+Starts 10 separate containers: MQTT message bus, PostgreSQL, core-keeper, core-data, core-metadata, core-command, support-notifications, support-scheduler, device-modbus.  Best for k3s clusters or development environments where services need to be extended.
+
+### Thin edge node – single-container EdgeX stack
+
+```bash
+docker build -t edgekit-thin-client edgex-thin-client/
+./scripts/start-edgex-thin-client.sh --no-build
+```
+
+Starts **one hardened container** with all EdgeX services embedded (PostgreSQL + Mosquitto + all Core/Supporting/Device services, managed by supervisord). Standalone, not extendable without rebuilding. Best for resource-constrained or locked-down production devices.
+
+### Central server – start the EdgeX security stack
+
+```bash
+./scripts/start-edgex-server.sh
+```
+
+Starts: OpenBao (secret store), security-bootstrapper, security-secretstore-setup, security-proxy-auth, security-proxy-setup, nginx (TLS API gateway on :8443).
+
+See [docs/edgex.md](docs/edgex.md) for the full integration guide.
+
+---
 
 ```
 edgekit/
-├── server/                  # MQTT broker container
+├── server/                       # MQTT broker container
 │   ├── Dockerfile
 │   ├── mosquitto.conf
 │   └── entrypoint.sh
-├── client/                  # Edge agent container
+├── client/                       # Edge agent container
 │   ├── Dockerfile
 │   ├── package.json
 │   └── src/
 │       └── index.js
+├── edgex-thin-client/            # Single-container thin EdgeX client image
+│   ├── Dockerfile                # Multi-stage: extracts EdgeX binaries + Alpine base
+│   ├── supervisord.conf          # Manages all internal processes
+│   ├── mosquitto.conf            # Embedded MQTT (localhost only)
+│   └── entrypoint.sh             # PostgreSQL initdb + supervisord
 ├── helm/
-│   └── edgekit/             # Root Helm chart
+│   └── edgekit/                  # Root Helm chart
 │       ├── Chart.yaml
-│       ├── values.yaml
+│       ├── values.yaml           # Default values
+│       ├── values-client.yaml    # Full k3s edge node overrides
+│       ├── values-server.yaml    # Central server overrides
+│       ├── values-thin-client.yaml  # Thin edge node overrides
 │       └── templates/
 ├── scripts/
-│   ├── build.sh             # Build Docker images
-│   ├── start-local.sh       # Start via docker compose
-│   └── stop-local.sh        # Stop local stack
+│   ├── build.sh                  # Build Docker images
+│   ├── start-local.sh            # Start base stack via docker compose
+│   ├── stop-local.sh             # Stop base stack
+│   ├── start-edgex-client.sh     # Start full k3s EdgeX edge stack
+│   ├── stop-edgex-client.sh      # Stop full k3s EdgeX edge stack
+│   ├── start-edgex-server.sh     # Start EdgeX security stack
+│   ├── stop-edgex-server.sh      # Stop EdgeX security stack
+│   ├── start-edgex-thin-client.sh  # Build + start thin EdgeX client
+│   └── stop-edgex-thin-client.sh   # Stop thin EdgeX client
 ├── .github/
 │   └── workflows/
-│       ├── ci.yml           # CI: lint + build on PR/push to develop|main
-│       └── release.yml      # Release: push images + Helm chart on tag
+│       ├── ci.yml                # CI: lint + build on PR/push to develop|main
+│       └── release.yml           # Release: push images + Helm chart on tag
 ├── docs/
 │   ├── architecture.md
+│   ├── edgex.md                  # EdgeX integration guide
 │   └── quickstart.md
-└── docker-compose.yml       # Local development
+├── docker-compose.yml            # Base local stack (MQTT broker + edge agent)
+├── docker-compose.edgex-client.yml     # Full k3s EdgeX edge stack (no security)
+├── docker-compose.edgex-thin-client.yml  # Thin EdgeX single-container stack
+├── docker-compose.edgex-server.yml  # EdgeX security services
+└── fleet.yaml                    # Rancher Fleet multi-cluster GitOps
 ```
 
 ---