> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexalis.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Nexalis Agent with Docker

### Unzip Nexalis Agent docker

Once you receive nexalis\_agent\_build\_docker.zip, unzip it:

```bash theme={null}
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**
* `VERSION`

### Install Docker

```bash theme={null}
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
```

**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/
```

### 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).

### Configure `config_docker_launcher.json`

#### Option A — SASL\_SSL (username/password)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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:
  ```bash theme={null}
  jq empty config_docker_launcher.json
  ```

### Launch container

```bash theme={null}
./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, ensuring 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.

### Operate container

```bash theme={null}
# 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
```

### Docker Linux install folders and file locations

Inside Docker, the Nexalis Agent is installed in `/usr/local/nexalis-agent`.
You can find the Dockerfile inside the image at `/usr/local/nexalis-agent/Dockerfile`
The data directory inside the container is `/app`.
When running with `./docker_launcher.sh` then `/app` will be mounted to nexalis\_agent\_volume.

`gRPC_kafka` has its default directory inside `nexalis_agent_volume/gRPC_kafka` and connectors have their default directory inside `nexalis_agent_volume/connectors`.

> For example, the `opcua_connector` default directory is `nexalis_agent_volume/connectors/opcua_connector`.
> This is necessary to have a writable directory on a volume.

It contains:

* device\_models for configurations
* certs for configuration certificates

The offline database is inside `nexalis_agent_volume/gRPC_kafka/persistent_buffer`.
It is created when gRPC\_kafka is configured and running.

You can find the latest NexalisAgentService logs at `nexalis_agent_volume/logs/nexalis_agent_service/NexalisAgentService.log`
You can configure other logs connection for gRPC\_kafka in their respective configurations.
If unconfigured, the default log location will be inside the connector data directory.

> For example, for opcua connector the logs will be by default inside `nexalis_agent_volume/connectors/opcua_connector`.

### Docker Linux commands

After configuring `config_docker_launcher.json` and running `./docker_launcher.sh` (see steps above), inside the container (for example with Docker exec), you can run the following commands.

```sh theme={null}
/usr/local/nexalis-agent/NexalisAgent help
```

```
Usage: /usr/local/nexalis-agent/NexalisAgent <command>
  help
        print this text
  version
        get current version v1.1.6
  service-install [--noautostart][--user USER][--data-directory DIR]        Install/enable/start systemd socket+service. run as user (default to nexalis)
  service-reset
        Stop/disable and remove units from /etc/systemd/system
  start [--socket-path SOCKETPATH]
        systemctl start service (requires root) or send start signal by SOCKETPATH
  restart [--socket-path SOCKETPATH]
        systemctl restart service  (requires root) or send restart signal in SOCKETPATH
  reload [--socket-path SOCKETPATH]
        have service reload config.json by service socket  SOCKETPATH
  status [--socket-path SOCKETPATH]
        get service status by service socket or by SOCKETPATH
  stop [--socket-path SOCKETPATH]
        stop service using systemctl (requires root) or by socket if provided
  service-run  --socket-path SOCKETPATH
        run NexalisAgentService directly. (without systemd)
  gRPC_kafka-sasl-login USERNAME  set KAFKA_SASL_USERNAME for admin and KAFKA_SASL_PASSWORD from standard input inside /etc/NexalisEnviron (requires root)
```

> Inside Docker, you should always run commands with `--socket-path SOCKETPATH`.

`gRPC_kafka-sasl-login` command is not available in Docker.
You must use `config_docker_launcher.json`.

`service-install`/`service-reset` are not available inside container because there is no need for system service,
The Docker daemon already manages restarts and acts as a service.

> Running those commands will complain about systemd not installed or running.

#### sending stop command

```sh theme={null}
/usr/local/nexalis-agent/NexalisAgent stop --socket-path /tmp/nexalis.sock
```

Sending the stop command to the socket stops all connectors and gRPC\_kafka.
It doesn't stop the container.
See the [Errors](#7-errors) section if you have an error.

#### sending start command

```sh theme={null}
/usr/local/nexalis-agent/NexalisAgent start --socket-path /tmp/nexalis.sock
```

Sending the start command to the socket starts all connectors and gRPC\_kafka if they were stopped.
It doesn't stop the container.
See the [Errors](#7-errors) section if you have an error.

#### sending restart command

```sh theme={null}
/usr/local/nexalis-agent/NexalisAgent restart --socket-path /tmp/nexalis.sock
```

Sending the restart command to the socket restarts all connectors and gRPC\_kafka.
It doesn't stop the container.
See the [Errors](#7-errors) section if you have an error.

#### sending status command

```sh theme={null}
/usr/local/nexalis-agent/NexalisAgent status --socket-path /tmp/nexalis.sock
```

Sending the status command to the socket shows current status from all connectors and gRPC\_kafka.
Status works the same as in Windows. See [status](#status-command).

#### sending reload command

Reload works the same as in Windows. See [reload](#reload-command)

```sh theme={null}
/usr/local/nexalis-agent/NexalisAgent reload --socket-path /tmp/nexalis.sock
```

## Running Agent in Linux Balena

As in Docker, the executables are installed in `/usr/local/nexalis-agent`.

With Balena, you must set up Kafka username/password in the Balena web UI.

* KAFKA\_SASL\_USERNAME
* KAFKA\_SASL\_PASSWORD

In Balena as in Docker, you should use the `--socket-path SOCKETPATH` option.

In the Balena UI you can open a shell inside the container.
By selecting the `agent` container, you can then run the same commands as described in the Docker section.

Unlike Docker, Balena starts the agent unconfigured on first boot.
You can transfer files using FTP using the provided guide.
The default directory is the `/app` directory.