Environment Variables

5min

Overview
The LE Sparkplug Edge Node can be configured using environment variables passed during the docker run command. This method is an alternative to using the Configuration File (config.json), which is the recommended approach, especially for complex setups like TLS.
If a config.json file is mounted and environment variables are also set, the environment variables will take precedence.
Variables
The following environment variables are available:
Variable Name
Required Status
Description
Default Value
EDGE_API_TOKEN
Required
The API token for authenticating with the Litmus Edge REST API.
None
GROUP_ID
Required
The Sparkplug Group ID for this Edge Node instance.
None
NODE_ID
Required
The Sparkplug Node ID for this specific Edge Node instance. Must be unique within the GROUP_ID.
None
MQTT_SERVERS
Required
A JSON array string defining the MQTT broker(s) to connect to. Each object requires url. user and password are optional. TLS fields can be added (see below). Example: '[{"url":"tcp://broker:1883","user":"u","pass":"p"}]'
None
PRIMARY_HOST_SUPPORT
Optional
If true, the Edge Node waits for a Primary Host Application (defined by PRIMARY_HOST_ID) to be online before sending data.
false
PRIMARY_HOST_ID
Conditionally Req
The Sparkplug Application ID of the Primary Host. Required only if PRIMARY_HOST_SUPPORT is set to true.
None
LE_STORE_AND_FORWARD
Optional
If true, enables the local buffering of data when the MQTT connection is down. See related LE_* variables below.
false
LE_TTL_DURATION
Optional
Time-to-live (in hours) for buffered messages when LE_STORE_AND_FORWARD is true.
12 (hours)
LE_MAX_SIZE_MB
Optional
Maximum size (in Megabytes) of the buffer database when LE_STORE_AND_FORWARD is true.
1000 (MB)
LE_MAX_NUM_ENTRIES
Optional
Maximum number of entries allowed in the buffer database when LE_STORE_AND_FORWARD is true.
1000000
MQTT_CLIENT_ID
Optional
Custom MQTT client ID. If blank, one is auto-generated based on Group/Node ID.
(auto-generated)
MQTT_CLIENT_ID_SUFFIX
Optional
A suffix appended to the MQTT_CLIENT_ID (whether custom or auto-generated).
(blank)
MQTT_CONNECT_TIMEOUT
Optional
Maximum time (e.g., "30s", "1m") to wait for an MQTT connection attempt.
30s
MQTT_WRITE_TIMEOUT
Optional
Maximum time (e.g., "3s") to wait for an MQTT publish operation.
3s
MQTT_KEEPALIVE
Optional
Maximum interval (in seconds) between MQTT control packets. Sends PINGREQ if no other packets are sent.
30 (seconds)
LE_LOGGING_LEVEL
Optional
Sets the application's logging verbosity. Options: debug, info, warn, error.
info
EDGE_HOSTNAME
External Only
Required only when running externally. The hostname or IP address of the target Litmus Edge device for NATS connection.
None
NATS_URL
External Only
Required only when running externally. The NATS connection string. Format: tls://admin:<API Account Token>@<EDGE_HOSTNAME>:4222 (or nats://).
None
MQTT_SERVERS JSON: When providing the MQTT_SERVERS value as an environment variable, ensure the JSON string is properly escaped for your shell. For TLS configuration within this variable, see the TLS Certs﻿ guide.
Configuration Example (with TLS and other options)
Bash
docker run -d --name le-sparkplug --network host -e EDGE_API_TOKEN="<Your Litmus Edge API Token>" -e PRIMARY_HOST_SUPPORT=true -e PRIMARY_HOST_ID="<Your Primary Host ID>" -e LE_STORE_AND_FORWARD=false -e GROUP_ID="MyGroup" -e NODE_ID="MyEdgeNode" -e MQTT_SERVERS='[{\"url\":\"ssl://<broker_ip_or_hostname>:8883\",\"user\":\"<mqtt_username>\",\"password\":\"<mqtt_password>\",\"ca_cert\":\"<Base64_CA_Cert>\",\"client_cert\":\"<Base64_Client_Cert>\",\"client_key\":\"<Base64_Client_Key>\",\"skip_cert_verify\":false}]' -e LE_LOGGING_LEVEL="debug" <imgName>:<tagName>
docker run -d --name le-sparkplug --network host -e EDGE_API_TOKEN="<Your Litmus Edge API Token>" -e PRIMARY_HOST_SUPPORT=true -e PRIMARY_HOST_ID="<Your Primary Host ID>" -e LE_STORE_AND_FORWARD=false -e GROUP_ID="MyGroup" -e NODE_ID="MyEdgeNode" -e MQTT_SERVERS='[{\"url\":\"ssl://<broker_ip_or_hostname>:8883\",\"user\":\"<mqtt_username>\",\"password\":\"<mqtt_password>\",\"ca_cert\":\"<Base64_CA_Cert>\",\"client_cert\":\"<Base64_Client_Cert>\",\"client_key\":\"<Base64_Client_Key>\",\"skip_cert_verify\":false}]' -e LE_LOGGING_LEVEL="debug" <imgName>:<tagName>
﻿
Remember to replace placeholders and handle JSON escaping carefully.
JSON
   {
       "edge_api_token": "0iriyynzv5xjac1aupqxm4j2tzuls5pf", // Example Token
       "group_id": "LE-Group",
       "node_id": "LE-Node",
       "primary_host_support": true, // Enabled
       "primary_host_id": "LE-97IS6VF", // Required if primary_host_support is true
       "le_store_and_forward": false, // Disabled by default
       "le_logging_level": "info",
       "mqtt": {
           "servers": [
               {
                   "url": "ssl://mqtt.secure.com:8883", // Example TLS server
                   "user": "myuser",
                   "password": "mypassword",
                   "ca_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FUtCk1JSUVkakNDQWRZQ0...", // Base64 encoded
                   "client_cert": "LS0tLS1CRUdJTiBSU0EgUFVCTElDIEtFWS0tpRd0lC...", // Base64 encoded
                   "client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktUlCRXdF...", // Base64 encoded
                   "skip_cert_verify": false
               },
               {
                   "url": "tcp://mqtt.insecure.com:1883", // Example non-TLS server
                   "username": "admin",
                   "password": "admin@"
               }
           ],
           "client_id": "", // Auto-generated if blank
           "client_id_suffix": "le-spb", // Optional suffix
           "connect_timeout": "30s",
           "write_timeout": "3s",
           "keepalive": 30
       }
   }
   {
       "edge_api_token": "0iriyynzv5xjac1aupqxm4j2tzuls5pf", // Example Token
       "group_id": "LE-Group",
       "node_id": "LE-Node",
       "primary_host_support": true, // Enabled
       "primary_host_id": "LE-97IS6VF", // Required if primary_host_support is true
       "le_store_and_forward": false, // Disabled by default
       "le_logging_level": "info",
       "mqtt": {
           "servers": [
               {
                   "url": "ssl://mqtt.secure.com:8883", // Example TLS server
                   "user": "myuser",
                   "password": "mypassword",
                   "ca_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FUtCk1JSUVkakNDQWRZQ0...", // Base64 encoded
                   "client_cert": "LS0tLS1CRUdJTiBSU0EgUFVCTElDIEtFWS0tpRd0lC...", // Base64 encoded
                   "client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktUlCRXdF...", // Base64 encoded
                   "skip_cert_verify": false
               },
               {
                   "url": "tcp://mqtt.insecure.com:1883", // Example non-TLS server
                   "username": "admin",
                   "password": "admin@"
               }
           ],
           "client_id": "", // Auto-generated if blank
           "client_id_suffix": "le-spb", // Optional suffix
           "connect_timeout": "30s",
           "write_timeout": "3s",
           "keepalive": 30
       }
   }
﻿
﻿

Variable Name	Required Status	Description	Default Value
EDGE_API_TOKEN	Required	The API token for authenticating with the Litmus Edge REST API.	None
GROUP_ID	Required	The Sparkplug Group ID for this Edge Node instance.	None
NODE_ID	Required	The Sparkplug Node ID for this specific Edge Node instance. Must be unique within the GROUP_ID.	None
MQTT_SERVERS	Required	A JSON array string defining the MQTT broker(s) to connect to. Each object requires url. user and password are optional. TLS fields can be added (see below). Example: '[{"url":"tcp://broker:1883","user":"u","pass":"p"}]'	None
PRIMARY_HOST_SUPPORT	Optional	If true, the Edge Node waits for a Primary Host Application (defined by PRIMARY_HOST_ID) to be online before sending data.	false
PRIMARY_HOST_ID	Conditionally Req	The Sparkplug Application ID of the Primary Host. Required only if PRIMARY_HOST_SUPPORT is set to true.	None
LE_STORE_AND_FORWARD	Optional	If true, enables the local buffering of data when the MQTT connection is down. See related LE_* variables below.	false
LE_TTL_DURATION	Optional	Time-to-live (in hours) for buffered messages when LE_STORE_AND_FORWARD is true.	12 (hours)
LE_MAX_SIZE_MB	Optional	Maximum size (in Megabytes) of the buffer database when LE_STORE_AND_FORWARD is true.	1000 (MB)
LE_MAX_NUM_ENTRIES	Optional	Maximum number of entries allowed in the buffer database when LE_STORE_AND_FORWARD is true.	1000000
MQTT_CLIENT_ID	Optional	Custom MQTT client ID. If blank, one is auto-generated based on Group/Node ID.	(auto-generated)
MQTT_CLIENT_ID_SUFFIX	Optional	A suffix appended to the MQTT_CLIENT_ID (whether custom or auto-generated).	(blank)
MQTT_CONNECT_TIMEOUT	Optional	Maximum time (e.g., "30s", "1m") to wait for an MQTT connection attempt.	30s
MQTT_WRITE_TIMEOUT	Optional	Maximum time (e.g., "3s") to wait for an MQTT publish operation.	3s
MQTT_KEEPALIVE	Optional	Maximum interval (in seconds) between MQTT control packets. Sends PINGREQ if no other packets are sent.	30 (seconds)
LE_LOGGING_LEVEL	Optional	Sets the application's logging verbosity. Options: debug, info, warn, error.	info
EDGE_HOSTNAME	External Only	Required only when running externally. The hostname or IP address of the target Litmus Edge device for NATS connection.	None
NATS_URL	External Only	Required only when running externally. The NATS connection string. Format: tls://admin:<API Account Token>@<EDGE_HOSTNAME>:4222 (or nats://).	None

Deploying The Solution

TLS Certs