Skip to main content
This guide explains how to install Nexalis Agent. It is designed for technical users (e.g., SCADA engineers) who want to set up the Nexalis Agent into their environment.

​
1) Linux build (standalone)

​
2.1 Unpack & prerequisites

unzip nexalis_agent_build.zip
tar -xvf nexalis_agent_build.tar

​
1.2) Directory layout of Nexalis Agent

The Nexalis Agent Linux build contains nexalis_agent.sh, watchdog.sh, gRPC_kafka (binary + config_gRPC_kafka.json + certs/), and connectors with their own device_models/ and (if needed) certs/. 
nexalis_agent_build/
├─ nexalis_agent.sh
├─ watchdog.sh
├─ config.json                  # Nexalis Agent config template
├─ gRPC_kafka/
│  ├─ gRPC_kafka                # executable
│  ├─ config_gRPC_kafka.json    # gRPC_kafka config template
│  └─ certs/                    # required by mTLS
│     ├─ ca-cert.pem
│     ├─ client-cert.pem
│     └─ client-key.pem
└─ connectors/
   ├─ opcua_connector/
   │  ├─ opcua_connector        # executable
   │  ├─ device_models/
   │  │  ├─ model_server1.json
   │  │  ├─ model_server2.json
   │  │  └─ model_server3.json
   │  └─ certs/                 # if protocol/security requires
   └─ other_connector/
Populate device_models, certs, and edit config.json (Nexalis Agent) and config_gRPC_kafka.json (cloud uplink). See the following sections for detailed explanations. In the case of running gRPC_kafka with SASL, you need to set environment variables: 
export KAFKA_SASL_USERNAME=your_username
export KAFKA_SASL_PASSWORD=your_password

​
1.3) Start / stop / restart

# Start
./nexalis_agent.sh start

# Restart (e.g., after config changes). Note: brief data gap while restarting.
./nexalis_agent.sh restart

# Stop
./nexalis_agent.sh stop

​
1.4) Set up auto-start. Example with Debian and Systemd

This service ensures the Nexalis Agent starts automatically when the Debian boots (similar procedure with other OS distributions using Systemd). 🛠 Service File Location. Create: /etc/systemd/system/nexalis_agent.service ✅ Service Content 
[Unit]
Description=Nexalis Agent Launcher
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/debian/nexalis/nexalis_agent_build
ExecStart=/home/debian/nexalis/nexalis_agent_build/watchdog.sh
Restart=always
User=debian
Group=debian
Environment="KAFKA_SASL_USERNAME=your-username"
Environment="KAFKA_SASL_PASSWORD=your-password"

[Install]
WantedBy=multi-user.target
Notes:
  • Replace WorkingDirectory and ExecStart with the correct absolute paths on your system.
  • Use absolute paths for both variables.
  • Ensure watchdog.sh is launched here so systemd can handle auto-start properly.
  • Replace your-username and your-password with your actual Kafka SASL credentials.
✅ Enable the service 
sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable nexalis_agent
sudo systemctl start nexalis_agent
🧪 Check it’s running 
systemctl status nexalis_agent

​
2) Docker deployment

​
2.1 Unpack & prerequisites

Once you receive nexalis_agent_build_docker.zip, unzip it: 
unzip nexalis_agent_build_docker.zip
You’ll get:
  • config_docker_launcher.json — launch parameters (env, volume path, container name)
  • docker_launcher.sh — helper script to run the container
  • nexalis_agent_build_docker.tar — the Docker image
  • nexalis_agent_volume/ — shared host directory for configs and logs
  • utils/ (e.g., helper scripts)
  • VERSION
Image filesystem (inside container, /app) mirrors the build: Agent scripts, gRPC_kafka/, connectors/, logs/, config.json.
Host volume (nexalis_agent_volume/) holds your editable configs and the logs: 
nexalis_agent_volume/
├─ config.json
├─ gRPC_kafka/
│  ├─ certs/
│  └─ config_gRPC_kafka.json
│  └─ config_gRPC_kafka_mTLS.json
├─ connectors/
│  └─ opcua_connector/
│     ├─ device_models/
│     │  └─ OPCUA_template_config.json
│     └─ certs/
└─ logs/
   ├─ gRPC_kafka/
   └─ connectors/

​
2.2 Install Docker & Configure auto-start & load image (Debian example)

sudo apt update -y && sudo apt upgrade -y
sudo apt install -y docker.io

sudo systemctl start docker
sudo systemctl enable docker

sudo usermod -aG docker $USER
newgrp docker
docker load -i nexalis_agent_build_docker.tar
docker images

​
2.3 Configure Nexalis Agent

In ./nexalis_agent_volume, configure:
  • config.json (Nexalis Agent configuration)
  • Connector device models and certificates (e.g., connectors/opcua_connector/device_models, connectors/opcua_connector/certs, etc.)
  • gRPC_kafka/config_gRPC_kafka.json
  • logs/ (empty folder; log files will be created by the container)
Then edit config_docker_launcher.json. Use exactly one of the following valid JSON examples (remove any comments; JSON does not support # comments).

​
2.4 Configure config_docker_launcher.json

​
Option A — SASL_SSL (username/password)

{
  "KAFKA_SASL_USERNAME": "your_kafka_username",
  "KAFKA_SASL_PASSWORD": "your_kafka_password",
  "NEXALIS_VOLUME_PATH": "./nexalis_agent_volume",
  "NAME_DOCKER_CONTAINER": "nexalis_agent_container_staging"
}

​
Option B — mTLS (no SASL credentials)

{
  "NEXALIS_VOLUME_PATH": "./nexalis_agent_volume",
  "NAME_DOCKER_CONTAINER": "nexalis_agent_container"
}
Notes
  • Pick a unique NAME_DOCKER_CONTAINER per environment (e.g., staging vs. production).
  • You may use an absolute path for NEXALIS_VOLUME_PATH.
  • Validate the file before running: 
    jq empty config_docker_launcher.json

​
2.5 Launch container

./docker_launcher.sh
The script validates prerequisites (docker, jq), checks the JSON config file, and ensures the volume path and image exist before starting the container. It runs a docker run equivalent with:
  • -d — run the container in detached mode
  • --restart always — container restarts automatically on boot or after a crash
  • ${env_args[@]} — environment variables such as KAFKA_SASL_USERNAME and KAFKA_SASL_PASSWORD (if SASL authentication is used)
  • --name "$NAME_DOCKER_CONTAINER" — the container name
  • -v volume mounts for configuration, device models, certificates, and logs:
    • config.json (Agent configuration)
    • connectors/opcua_connector/certs
    • connectors/opcua_connector/device_models
    • connectors/modbus_connector/device_models
    • connectors/dnp3_connector/device_models
    • gRPC_kafka/certs
    • gRPC_kafka/config_gRPC_kafka.json
    • logs/
  • The container image (default: nexalis_agent_build_docker:latest)
This ensures the container runs in the background, restarts automatically if stopped, and mounts all required configs, certificates, and logs from the host volume into the container.

​
2.6 Operate container

# Show containers
docker ps -a

# Stop / remove container
docker stop <id|name>
docker rm   <id|name>

# Remove image
docker rmi  <imageID|imageName>

# Exec into container (root at /app)
docker exec -it nexalis_agent_container /bin/bash

# Enter the docker container
sudo docker exec -it nexalis_agent_container /bin/bash

​
3) Windows deployment

The Nexalis Windows installer ensures the proper installation of the Nexalis Agent on Windows systems (>= Windows 7), including setting up the Windows service for auto-start.