Skip to content

quickstart.md

Latest commit

 

History

History
179 lines (124 loc) · 4.55 KB

quickstart.md

File metadata and controls

179 lines (124 loc) · 4.55 KB

Quick Start Guide

This guide walks you through running EdgeKit locally and then deploying it to a k3s cluster.

Running locally with Docker Compose

Prerequisites

  • Docker ≥ 24 (with Compose v2)
  • Git

Steps

1. Clone the repository

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

2. (Optional) Build images manually

./scripts/build.sh

3. Start the full stack

./scripts/start-local.sh

Expected output:

==> Starting edgekit stack (builds images if needed)…
[+] Building …
[+] Running 2/2
 ✔ Container edgekit-server  Started
 ✔ Container edgekit-client  Started

✅ edgekit is running!

   MQTT broker:       mqtt://localhost:1883
   MQTT over WS:      ws://localhost:9001

   View logs:         docker compose logs -f
   Stop:              ./scripts/stop-local.sh

4. Verify events are flowing

Open a second terminal and subscribe to all topics:

docker run --rm --network host eclipse-mosquitto:2.0 \
    mosquitto_sub -h localhost -t "edgekit/#" -v

Once the edge node's device services can reach real devices (Modbus/REST — see client/res/), exported EdgeX Events arrive on edgekit/events:

edgekit/events {"apiVersion":"v3","id":"...","deviceName":"modbus-th-01","readings":[{"resourceName":"Temperature","value":"21.4"}],"tags":{"site":"edge-local-1"}}

The first start also bootstraps the embedded Postgres database, so the edge container takes longer to become ready than the broker.

5. Stop the stack

./scripts/stop-local.sh

Deploying on k3s

Prerequisites

  • A k3s cluster (single node is fine for testing)
  • Helm ≥ 3.14
  • kubectl configured for the cluster

Option A – Install from GHCR (recommended)

helm install edgekit oci://ghcr.io/perspikapps/charts/edgekit \
    --namespace edgekit \
    --create-namespace \
    --wait

Option B – Install from local chart

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

Verify the deployment

kubectl -n edgekit get pods
# NAME                               READY   STATUS    RESTARTS
# edgekit-server-xxxxxxxxxx-xxxxx   1/1     Running   0
# edgekit-client-xxxxxxxxxx-xxxxx   1/1     Running   0

kubectl -n edgekit logs -f -l app.kubernetes.io/component=client
# [entrypoint] Initialising embedded Postgres ...
# core-metadata ... Service started ...
# app-export ... MQTT export ready ...

Scale to multiple edge nodes

helm upgrade edgekit ./helm/edgekit \
    --namespace edgekit \
    --set client.replicaCount=3

Point at a different central broker

helm upgrade edgekit ./helm/edgekit \
    --namespace edgekit \
    --set client.centralBrokerAddress=tcp://central.example.com:1883

Uninstall

helm uninstall edgekit --namespace edgekit
kubectl delete namespace edgekit

Subscribing to events from outside the cluster

Forward the WebSocket port to your local machine:

kubectl -n edgekit port-forward svc/edgekit-server 9001:9001

Then connect any MQTT-over-WebSocket client to ws://localhost:9001.

Example using mosquitto_sub with WebSocket support:

docker run --rm --network host eclipse-mosquitto:2.0 \
    mosquitto_sub -h localhost -p 9001 -t "edgekit/#" -v

Environment variable reference

The edge client is configured via client/env/edge.env and Helm values.yaml. The most common knobs:

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 edge-operations.md for the full reference.