Deploying The Solution

15min
﻿
This guide provides step-by-step instructions to set up and deploy the LE Sparkplug Edge Node solution on your Litmus Edge device.
Prerequisites
Before proceeding, ensure you have the following:
Litmus Edge 3.16.x or later.
A Litmus Edge API Token. See the Create API Token guide.
MQTT Broker connection details (URL, username, password). The solution supports MQTT Protocol versions 3.1.0 and 3.1.1.
﻿
1. Upload the Image to Litmus Edge
Download the LE Sparkplug Edge Node image (LE Sparkplug Edge Node vx.x.x) from the Central Portal website via the Download button.
Download the LE Sparkplug Edge Node Image
﻿
Log in to your Litmus Edge instance and navigate to Applications > Images.
Click the Upload Image (+) icon, select Upload, choose the downloaded image file (le-sparkplug-x.x.x.tar.gz), and click Import. The image may take a few moments to appear in the list.
﻿
2. Deploy the Application
You can deploy the application using either a configuration file (recommended) or environment variables.
Method 1: Using a Configuration File (Recommended)
This method uses a JSON file to manage all configuration settings, making it easier to handle complex configurations like TLS.

Download the configuration flow LE Sparkplug Edge Node - Flow from the download page. 
Download the Flow
﻿
Update the config file with valid configuration values and trigger the flow to create the file. Next, see the Run the Docker Container section below.
For optional settings like enabling Primary Host support, Store and Forward, configuring TLS, or adjusting logging levels, add the corresponding fields to this JSON file. Refer to the Environment Variables﻿ documentation for all available fields and the TLS Certs﻿ guide for TLS setup.
Run the Docker Container:
Use the docker run command, mounting the directory containingconfig.json to /le-sparkplug/data/ inside the container. Replace <imgName>:<tagName> with the actual image name and tag you uploaded (e.g., us-docker.pkg.dev/litmus-customer-facing/litmus-solutions/le-sparkplug:1.4.4).
Bash
docker run -d --name le-sparkplug --network host -v /var/lib/customer/sparkplug/:/le-sparkplug/data/ <imgName>:<tagName>
docker run -d --name le-sparkplug --network host -v /var/lib/customer/sparkplug/:/le-sparkplug/data/ <imgName>:<tagName>
﻿
Method 2: Using Environment Variables
This method is an alternative if you prefer not to use a configuration file. Required settings are passed directly via -e flags.
Run the Docker Container:
Provide the required configuration values using environment variables. Replace placeholders (<...>) and <imgName>:<tagName>.
docker run Example:
Bash
docker run -d --name le-sparkplug --network host -e EDGE_API_TOKEN="<Your Litmus Edge API Token>" -e GROUP_ID="MyGroup" -e NODE_ID="MyEdgeNode" -e MQTT_SERVERS='[{\"url\":\"tcp://<broker_ip_or_hostname>:1883\",\"user\":\"<mqtt_username>\",\"password\":\"<mqtt_password>\"}]' <imgName>:<tagName>
docker run -d --name le-sparkplug --network host -e EDGE_API_TOKEN="<Your Litmus Edge API Token>" -e GROUP_ID="MyGroup" -e NODE_ID="MyEdgeNode" -e MQTT_SERVERS='[{\"url\":\"tcp://<broker_ip_or_hostname>:1883\",\"user\":\"<mqtt_username>\",\"password\":\"<mqtt_password>\"}]' <imgName>:<tagName>
﻿
The MQTT_SERVERS value is a JSON string. Ensure proper escaping of quotes!
For optional settings, add more -e flags. Refer to the Environment Variables﻿ documentation for all available environment variables. To configure TLS, you need to embed the base64-encoded certificates within the MQTT_SERVERS JSON string. See the TLS Certs﻿ guide.
﻿
That's it! Your LE Sparkplug Edge Node application should now be running on your Litmus Edge device. 🎉
﻿
Optional: Running Externally (Outside Litmus Edge)
You can also run the LE Sparkplug Edge Node container on a separate machine (e.g., your laptop, a server) and connect it back to your Litmus Edge instance. This requires specific prerequisites and configuration adjustments.
Prerequisites for Running Externally:
NATS Proxy Enabled: Ensure the NATS Proxy is enabled on your target Litmus Edge device. Navigate to System > Services > NATS Proxy in the Litmus Edge UI and enable it if necessary.
API Account Token: You need an API Account Token. Follow the instructions in the Create an API Account guide to generate one. This token is used in the NATS_URL.
Edge Hostname/IP: You need the hostname or IP address of your Litmus Edge device, accessible from the machine where you will run the container.
Configuration:
When running externally, you must provide two additional configuration parameters:
edge_hostname (JSON) / EDGE_HOSTNAME (Env Var): The hostname or IP address of your Litmus Edge device.
nats_url (JSON) / NATS_URL (Env Var): The connection string for the Litmus Edge NATS broker. Format: tls://admin:<Your API Account Token>@<EDGE_HOSTNAME>:4222
If the machine running the container is on the same local network as the Litmus Edge device and you encounter TLS certificate errors, try replacing tls:// with nats:// in the nats_url / NATS_URL. For example: nats://admin:<Your API Account Token>@<EDGE_HOSTNAME>:4222.
Deployment Examples for External Execution:
Method 1: Using a Configuration File (Recommended)
Update your config.json file:
JSON
{
    "edge_api_token": "<Your Litmus Edge API Token>",
    "edge_hostname": "<Your Litmus Edge Hostname or IP>", // Added for external connection
    "nats_url": "tls://admin:<Your API Account Token>@<Your Litmus Edge Hostname or IP>:4222", // Added for external connection
    "group_id": "MyGroup",
    "node_id": "MyNode",
    "mqtt": {
        "servers": [
            {
                "url": "tcp://<broker_ip_or_hostname>:1883",
                "user": "<mqtt_username>",
                "password": "<mqtt_password>"
            }
        ]
    }
    // Add other optional fields as needed (primary_host_support, etc.)
}
{
    "edge_api_token": "<Your Litmus Edge API Token>",
    "edge_hostname": "<Your Litmus Edge Hostname or IP>", // Added for external connection
    "nats_url": "tls://admin:<Your API Account Token>@<Your Litmus Edge Hostname or IP>:4222", // Added for external connection
    "group_id": "MyGroup",
    "node_id": "MyNode",
    "mqtt": {
        "servers": [
            {
                "url": "tcp://<broker_ip_or_hostname>:1883",
                "user": "<mqtt_username>",
                "password": "<mqtt_password>"
            }
        ]
    }
    // Add other optional fields as needed (primary_host_support, etc.)
}
﻿
Run the container, mounting the config file (ensure the container can access the path):
Bash
# Run on your external machine
docker run -d --name le-sparkplug-external -v /path/to/your/config/dir/:/le-sparkplug/data/ us-docker.pkg.dev/litmus-customer-facing/litmus-solutions/le-sparkplug:1.4.4
# Run on your external machine
docker run -d --name le-sparkplug-external -v /path/to/your/config/dir/:/le-sparkplug/data/ us-docker.pkg.dev/litmus-customer-facing/litmus-solutions/le-sparkplug:1.4.4
﻿
Adjust the volume path (/path/to/your/config/dir/) to the location of your config.json on the external machine.
/path/to/your/config/dir/ must contain a folder named config with the config file config.json
Method 2: Using Environment Variables
Run the container on your external machine with additional environment variables:
Bash
# Run on your external machine
docker run -d --name le-sparkplug-external -e EDGE_API_TOKEN="<Your Litmus Edge API Token>" -e EDGE_HOSTNAME="<Your Litmus Edge Hostname or IP>" -e NATS_URL="tls://admin:<Your API Account Token>@<Your Litmus Edge Hostname or IP>:4222" -e GROUP_ID="MyGroup" -e NODE_ID="MyNode" -e MQTT_SERVERS='[{\"url\":\"tcp://<broker_ip_or_hostname>:1883\",\"user\":\"<mqtt_username>\",\"password\":\"<mqtt_password>\"}]' us-docker.pkg.dev/litmus-customer-facing/litmus-solutions/le-sparkplug:1.4.4
# Run on your external machine
docker run -d --name le-sparkplug-external -e EDGE_API_TOKEN="<Your Litmus Edge API Token>" -e EDGE_HOSTNAME="<Your Litmus Edge Hostname or IP>" -e NATS_URL="tls://admin:<Your API Account Token>@<Your Litmus Edge Hostname or IP>:4222" -e GROUP_ID="MyGroup" -e NODE_ID="MyNode" -e MQTT_SERVERS='[{\"url\":\"tcp://<broker_ip_or_hostname>:1883\",\"user\":\"<mqtt_username>\",\"password\":\"<mqtt_password>\"}]' us-docker.pkg.dev/litmus-customer-facing/litmus-solutions/le-sparkplug:1.4.4
﻿
Add other optional -e flags as needed.
3. Verify the Deployment
To verify that the container is running correctly, you can check the logs:
Bash
docker logs le-sparkplug
docker logs le-sparkplug
﻿
You should see logs indicating that the container is running and connected to the MQTT broker.
LE Sparkplug Edge Node
Environment Variables