Skip to content

README.md

Latest commit

 

History

History
218 lines (160 loc) · 7.98 KB

README.md

File metadata and controls

218 lines (160 loc) · 7.98 KB

EdgeKit

EdgeKit is an open-source client/server IoT edge platform built around EdgeX Foundry 4.x and designed to run on k3s.
It provides a central MQTT broker (server) and autonomous EdgeX edge nodes (clients) that collect telemetry over Modbus and REST, buffer it locally, and forward it reliably to the server over MQTT.

Architecture

┌──────────────────────────────────────────┐
│              edgekit-server               │
│         central Mosquitto MQTT broker     │
│      :1883 (MQTT)    :9001 (MQTT/WS)       │
└──────────────────────────────────────────┘
            ▲                       ▲
   MQTT export (store & forward)    │
┌───────────┴────────────┐  ┌───────┴────────────────┐
│      edgekit-client     │  │      edgekit-client     │
│   EdgeX 4.x edge node   │  │           ...           │
│  modbus + rest → MQTT   │  └─────────────────────────┘
│  bus → export service →  │
│  Store & Forward export  │
└──────────────────────────┘

Each client is a single Docker image bundling the autonomous EdgeX 4.x edge stack:

  • Collects data via device-modbus (Modbus TCP) and device-rest (REST/JSON)
  • Uses an internal MQTT message bus (no Redis) and a local PostgreSQL database
  • Runs app-service-configurable to filter/tag/compress and export to the central broker
  • Buffers locally with native Store & Forward and replays on reconnect

The server is a single Eclipse Mosquitto container with both plain MQTT (1883) and WebSocket (9001) listeners.

For a deeper dive, see doc/architecture.md, the design rationale in doc/adr/0001-edgex-4x-mqtt-edge.md, and the operations guide in doc/edge-operations.md.

Quick Start (local)

Prerequisites

1. Clone the repository

git clone https://github.com/perspikapps/edgekit.git
cd edgekit

2. Start the stack

./scripts/start-local.sh

This builds and starts:

  • edgekit-server – MQTT broker (ports 1883 and 9001 exposed on localhost)
  • edgekit-client – Autonomous EdgeX 4.x edge node (Modbus/REST → MQTT export)

3. Watch events flow

# Subscribe to all edgekit topics (exported EdgeX Events land on edgekit/events)
docker run --rm --network host eclipse-mosquitto:2.0 \
    mosquitto_sub -h localhost -t "edgekit/#" -v

The edge node only exports data once its device services can reach real devices (see the Modbus/REST definitions under client/res/). Point them at your hardware or a simulator to see Events arrive.

4. Stop the stack

./scripts/stop-local.sh

For a full walkthrough, see doc/quickstart.md.

Deploy on k3s

Prerequisites

  • A running k3s cluster
  • Helm ≥ 3.14
  • kubectl configured to reach the cluster

Install with Helm

# Install edgekit (server + 1 client)
helm install edgekit oci://ghcr.io/perspikapps/charts/edgekit \
    --namespace edgekit \
    --create-namespace

# Scale to multiple clients
helm upgrade edgekit oci://ghcr.io/perspikapps/charts/edgekit \
    --namespace edgekit \
    --set client.replicaCount=3

Or from the local chart:

helm install edgekit ./helm/edgekit \
    --namespace edgekit \
    --create-namespace

Verify

kubectl -n edgekit get pods
kubectl -n edgekit logs -f -l app.kubernetes.io/component=client

Configuration

The edge client uses the EdgeX configuration & registry provider (Core Keeper): the files under client/res/ seed Keeper on first start, and environment overrides in client/env/edge.env apply on top (EdgeX maps SECTION_SUBSECTION_KEY env vars onto config keys).

Variable Default Description
WRITABLE_PIPELINE_FUNCTIONS_MQTTEXPORT_PARAMETERS_BROKERADDRESS tcp://edgekit-server:1883 Central broker URL
WRITABLE_PIPELINE_FUNCTIONS_MQTTEXPORT_PARAMETERS_TOPIC edgekit/events Central export topic
WRITABLE_PIPELINE_FUNCTIONS_ADDTAGS_PARAMETERS_TAGS site:edge-site-001 Per-site identity stamp
WRITABLE_STOREANDFORWARD_ENABLED true Offline buffering
EDGEKIT_ENABLE_CORE_DATA false Optional local Event persistence

See doc/edge-operations.md for the full reference and the config-upgrade procedure, and helm/edgekit/values.yaml for the Helm configuration.

Repository Layout

edgekit/
├── server/                  # MQTT broker container
│   ├── Dockerfile
│   ├── mosquitto.conf
│   └── entrypoint.sh
├── client/                  # Autonomous EdgeX 4.x edge node
│   ├── Dockerfile           # all-in-one image
│   ├── entrypoint.sh
│   ├── supervisord.conf
│   ├── env/edge.env         # static per-site config
│   └── res/                 # static EdgeX config (modbus, rest, export, bus)
├── helm/
│   └── edgekit/             # Root Helm chart
│       ├── Chart.yaml
│       ├── values.yaml
│       └── templates/
├── scripts/
│   ├── build.sh             # Build Docker images
│   ├── start-local.sh       # Start via docker compose
│   └── stop-local.sh        # Stop local stack
├── .github/
│   └── workflows/
│       ├── ci.yml           # CI: lint + build on PR/push to develop|main
│       └── release.yml      # Release: push images + Helm chart on tag
├── doc/
│   ├── architecture.md
│   └── quickstart.md
└── docker-compose.yml       # Local development

CI / CD

Workflow Trigger What it does
ci.yml push / PR to develop or main Lints Helm chart, builds both Docker images (linux/amd64 + linux/arm64)
release.yml push of v*.*.* tag Builds & pushes multi-arch (amd64 + arm64) images to GHCR, packages & pushes Helm chart to GHCR OCI registry

To release a new version:

git tag v1.0.0
git push origin v1.0.0

Branching strategy

Branch Purpose
main Production-ready releases only
develop Integration branch – all feature branches merge here
feature/* Individual features or fixes

Contributing

Pull requests are welcome. Please open an issue first to discuss what you would like to change.

License

Apache 2.0