Overview

Vantiq Edge installations are non-clustered Vantiq servers designed to run in edge environments, typically very close to
data sources. This proximity facilitates low-latency remote application processing, allowing for a more distributed
workload across large applications. While it is not a requirement, Vantiq Edge installations usually communicate with a
clustered Vantiq cloud installation.

Vantiq Edge installations provide all Vantiq core services, but do not include the following:

  • Vantiq’s monitoring services (Grafana)
  • Integration with an OAuth provider
  • Clustered deployment

This guide describes the process for deploying Vantiq Edge installations via:

In addition to the deployment information, this guide also provides instructions for managing the edge installations. General
knowledge of Java applications, Docker, and Kubernetes is assumed (for each respective deployment method).

Requirements

General Requirements

For all deployment methods, a Vantiq license is required to startup the edge server. The license comprises two files:

  • license.key
  • public.pem

The license files can be acquired by contacting Vantiq Technical Support via email, at [email protected].

For the Docker or Kubernetes deployment methods, a quay.io ID must be registered with Vantiq Technical Support. This is
necessary to enable access to the Vantiq Edge and AI-Assistant Docker images that are stored in a private quay.io repository. To access these images, the
developer must create a quay.io account, and then email their quay.io ID to [email protected]. Once the ID has been
validated and registered, the developer will then have access to the Docker images.

Hardware Requirements

The edge computing device must meet or exceed the following requirements:

  • 64-bit ARM or x86 processor
    • (For Docker deployments, an x86 processor is required)
  • 4 GB main memory
  • 32 GB permanent storage (to support MongoDB and Qdrant)

Software Requirements

Operating system CPU Arch Supported configurations
Linux amd64 Docker Engine or Executable JAR
Linux arm64 Executable JAR
Windows amd64 Docker Desktop on WSL2 or Docker Using apt on WSL2
MacOS Intel amd64 Docker Desktop or other Docker
MacOS Apple Silicon Executable JAR

Deployment Methods

Vantiq Edge can be deployed several ways:

For production, it is recommended to use docker engine and docker compose on Linux with appropriate x86-64 hardware.
Vantiq Edge can be run on 64-bit client operating systems, though usually that is for test and evaluation purposes.

The following sections describe each Vantiq Edge deployment method in detail, offering a simple example for each.

Executable JAR Deployment

This deployment method only supports the deployment of the Vantiq Edge server with MongoDB. It does not support the deployment of the AI Assistant and Qdrant vector database.
We recommend using Docker to deploy the Edge Server with AI capabilities.

The JAR deployment can be used on any platform that supports the Java version noted above, and does not require Docker or Hardware Virtualization support.

NOTE: The steps below assume that a suitable version of Java has already been installed.

MongoDB

The Vantiq Edge installation requires a running MongoDB instance (version 4.2 or earlier). To download MongoDB,
follow the instructions below:

After successfully installing and starting up, the next step involves properly configuring the database. To do so,
first open a command line connection to mongo.

  • This is typically done by running the mongo command from the command line
    • In some cases, the command may not be recognized. The solution usually involves editing
      your PATH environment variable to include the directory in which the mongo executable is installed.
  • For more details, visit the MongoDB documentation

Once inside the mongo command, create a new user in the ars02 database as follows:

use ars02

db.createUser({user: "ars", pwd: "ars", roles: ["readWrite", "dbAdmin"]})
  • To verify success:
show users
  • This should display information about the new user in json format

Running the Vantiq Executable

With MongoDB running and configured, the Vantiq Edge installation can now be started up. The Vantiq Edge executable is
packaged as a .zip file, and can be retrieved by emailing Vantiq Technical Support ([email protected]).

Once downloaded, create a directory for the edge deployment in the machine’s filesystem, and copy/unzip the .zip file
there. There should be 3 resulting directories:

  • bin
  • lib
  • config

Copy the license files (the license.key and public.pem files) into the config directory. Then, create the log directory: /var/log/vantiq and
ensure that the log directory is writable by the Vantiq Edge installation process (i.e., by the user under which the Vantiq executable will run).

Finally, to run the Vantiq Edge installation, execute the following command:

./<pathToInstallDirectory>/bin/vantiq.sh

Alternatively, the following command can run the executable in the background for Unix-based operating systems:

./<pathToInstallDirectory>/bin/vantiq.sh > /dev/null 2>&1 &
  • NOTE: Be sure to validate that the executable can run successfully before attempting to run in the background.

If either step fails, examine the logs in /var/log/vantiq or contact Vantiq Technical Support ([email protected]).
(Note that if no log files are present in this directory, it may be that that directory is not writable by the user running the Vantiq executable.)

Navigate to the Setting Up Vantiq Edge section for next steps.

Windows bat file

The steps for using the vantiq.bat file for Windows are similar to those above. You will need to copy the license files and create the log directory, as described above.

Then, to run the Vantiq Edge installation on Windows, execute the following command:

<pathToInstallDirectory>\bin\vantiq.bat

Docker Deployment

NOTE: It is assumed that a quay.io ID has been registered with Vantiq Technical Support and that a suitable version
of Docker, including either docker-compose or docker compose, has been installed.

Begin by creating a directory for the edge deployment in the target machine’s filesystem (that is, the machine on which
the image will be running). Then, navigate into the directory and create a subdirectory named config. Copy the
license.key and public.pem files into the config subdirectory. Next, from the top-level edge deployment directory
(the parent directory of config), create a file named docker-compose.yml. Paste the following content into the new
docker-compose.yml file:

services:
  vantiq_edge:
    container_name: vantiq_edge_server
    image: quay.io/vantiq/vantiq-edge:1.37.0
    ports:
      - 8080:8080
    depends_on:
      - vantiq_edge_mongo
      - vantiq_edge_qdrant
    restart: unless-stopped
    volumes:
      - ./config/license.key:/opt/vantiq/config/license.key
      - ./config/public.pem:/opt/vantiq/config/public.pem
    networks:
      - vantiq_edge

  vantiq_edge_mongo:
    container_name: vantiq_edge_mongo
    image: bitnami/mongodb:4.2.5
    restart: unless-stopped
    environment:
      - MONGODB_USERNAME=ars
      - MONGODB_PASSWORD=ars
      - MONGODB_DATABASE=ars02
    volumes:
      - vantiq_edge_data:/bitnami:rw
    networks:
      vantiq_edge:
        aliases: [edge-mongo]

  vantiq_ai_assistant:
    container_name: vantiq_ai_assistant
    image: quay.io/vantiq/ai-assistant:1.37.0
    restart: unless-stopped
    network_mode: "service:vantiq_edge"

  vantiq_edge_qdrant:
    container_name: vantiq_edge_qdrant
    image: qdrant/qdrant
    restart: unless-stopped
    volumes:
      - qdrantData:/qdrant/storage
    networks:
      vantiq_edge:
        aliases: [edge-qdrant]

networks:
  vantiq_edge:
    ipam:
      config: []
volumes:
  vantiq_edge_data: {}
  qdrantData: {}

The tag for the vantiq-edge image (the 1.37.0 in image: quay.io/vantiq/vantiq-edge:1.37.0) can be changed
to whichever suitable version the developer would like to use. The version tags are listed in the quay.io repository.
The tag for the ai-assistant image must match the tag for the vantiq-edge image for the major and minor versions
(e.g., 1.37). The patch version (e.g., 1.37.1) might be different, but should preferably be the same.

  • NOTE: Do NOT use any tag containing SNAPSHOT.

The same is true for the MongoDB version tag, so long as it meets the version requirements noted above in the Software
Requirements section.

Once the docker-compose.yml file has been created and saved, make sure that Docker CLI has been logged into
the quay.io container registry. This can be done by running docker login quay.io and entering the
credentials when prompted. With that done, the edge installation can be started up using the following command:

docker compose up -d

or if you have docker-compose installed,

docker-compose up -d

This will run the docker images in the background. To check that they are up and running, examine the running docker
processes using the following command:

docker ps

The initial startup may take a few minutes. You can check the logs of the edge server using the command,

docker logs -f vantiq_edge_server

or check the overall startup logs using the docker compose command,

docker compose logs -f

Navigate to the Setting Up Vantiq Edge section for next steps.

Kubernetes Deployment

NOTE: It is assumed that a Kubernetes cluster has already been created, and that the developer has access to it or
its administrator.

The following section describes how to deploy the Vantiq Edge into a Kubernetes cluster using Vantiq’s External
Lifecycle Management tools. Before continuing, be sure to read the External Lifecycle Management
documentation completely. The following guide assumes that a K8s Cluster has
already been defined in the developer’s Vantiq namespace, and that a K8s Worker has been
deployed in the developer’s Kubernetes cluster.

Deploying the Vantiq Edge requires deploying Vantiq K8s Installations, one for MongoDB and one for the Vantiq Edge
image. For AI capability support you will also need to deploy AI-Assistant and Qdrant Installations.

Deploying MongoDB Vantiq Installation

In order to properly deploy the MongoDB image into the Kubernetes Cluster, the Kubernetes Cluster administrator must
create a Persistent Volume where the database data will be stored. This is necessary in order for the MongoDB data to persist if the MongoDB Installation is
shutdown for any reason. This typically requires creating a Persistent Volume Claim as well as a Persistent Volume.
Examine the Kubernetes documentation
for more information, and be sure to keep track of the Persistent Volume Claim’s name since it is needed in the next
step.

Navigate to the K8s Cluster in the Vantiq IDE, and click on the Deploy button to deploy a new Installation. Name the Installation
MongoEdge and configure it with the following information, either by using the Edit Config as JSON option to paste in the
following text, or by manually entering each field via the Configuration Options UI:

[
  {
    "type": "image", 
    "name": "bitnami/mongodb:4.2.5"
  },
  {
    "type": "environmentVariable", 
    "name": "MONGODB_USERNAME", 
    "value": "ars"
  },
  {
    "type": "environmentVariable", 
    "name": "MONGODB_PASSWORD", 
    "value": "ars"
  },
  {
    "type": "environmentVariable", 
    "name": "MONGODB_DATABASE", 
    "value": "ars02"
  },
  {
    "type": "persistentVolumeRef", 
    "name": "<persistentVolumeClaimName>", 
    "path": "/bitnami"
  }
]

Be sure to replace <persistentVolumeClaimName> with the name of the Persistent Volume Claim created in the Kubernetes
Cluster.

Note that the mongodb is a non-root container running as the user ID 1001 belonging to the root group. If you are using a persistent volume that was created by a different user, you may need to change the persistent volume access controls accordingly.

  • If using the Configuration Options UI, fill out the Image option (only need to add the Name), then add three
    Environment Variable options and one Persistent Volume Ref option, filling out each exactly as defined above.

EdgeMongo

The tag for the MongoDB image (the 4.2.5 in "name": "bitnami/mongodb:4.2.5") can be changed to whichever
suitable version the developer would like to use, so long as it meets the version requirements noted above in the
Software Requirements section.

Finally, press the Deploy button to create the Work Item. Once the Work Item has been completed, the MongoDB image should
be deployed in the Kubernetes Cluster. The Kubernetes Cluster administrator can check to make sure it has been
successfully deployed by searching for a Stateful Set with the same name as the Vantiq Installation.

Deploying Qdrant Edge Installation

If you want to deploy the AI capabilities, you will need to deploy a Qdrant Edge Installation. This is done in the same way as the MongoDB Installation, but with a different name and image.

Navigate to the K8s Cluster in the Vantiq IDE, and click on the Deploy button to deploy a new Installation. Name the Installation QdrantEdge and configure it with the following information, either by using the Edit Config as JSON option to paste in the following text, or by manually entering each field via the Configuration Options UI:

[
  {
    "type": "image", 
    "name": "qdrant/qdrant"
  },
  {
    "type": "persistentVolumeRef", 
    "name": "<qdrantPersistentVolumeClaimName>", 
    "path": "/qdrant/storage"
  }
]

Similar to the MongoDB Installation, the Kubernetes Cluster administrator must create a Persistent Volume where the Qdrant data will be stored. Once Persistent Volume and Persistent Volume Claim are created, the Persistent Volume Claim name must be entered in the persistentVolumeRef configuration option.

Note that qdrant is a container running as the root user, so access controls for the Persistent Volume might differ from the ones that must be defined for the MongoDB Installation.

Finally, press the Deploy button to create the Work Item. Once the Work Item has been completed, the Qdrant image should
be deployed in the Kubernetes Cluster. The Kubernetes Cluster administrator can check to make sure it has been
successfully deployed by searching for a Stateful Set with the same name as the Qdrant Installation.

Deploying Vantiq Edge Installation

Having successfully deployed the MongoDB image, and possibly the
Qdrant Installation, the next step is to deploy the Vantiq Edge Installation.
This document assumes that you have uploaded both the license.key and public.pem files as
Vantiq Documents in the same Namespace as the K8s Cluster.

Additionally, the Kubernetes Cluster will need access to quay.io via the credentials registered with Vantiq Technical
Support. The Kubernetes Cluster administrator can accomplish this by creating an Image Pull Secret in the cluster. The
following Kubernetes documentation
elaborates on this in more detail. Be sure to remember the secret name as it is needed in the next step.

Now, navigate to the K8s Cluster in the Vantiq IDE, and click on the Deploy button to deploy a new Installation. Name the Installation VantiqEdge and configure it with the following information, either by using the Edit Config as JSON option to paste in the following text, or by manually entering each field via the Configuration Options UI:

[
  {
    "type": "image", 
    "name": "quay.io/vantiq/vantiq-edge:1.37.0",
    "imagePullSecret": "<imagePullSecretName>"
  },
  {
    "type": "inboundPort", 
    "port": 8080, 
    "protocol": "HTTP",
    "host": "<hostName>"
  },
  {
    "type": "file",
    "resourceType": "documents",
    "resourceName": "public.pem",
    "path": "/opt/vantiq/config",
    "treatAsText": true,
    "dataSource": "configMap"
  },
  {
    "type": "file",
    "resourceType": "documents",
    "resourceName": "license.key",
    "path": "/opt/vantiq/config",
    "treatAsText": true,
    "dataSource": "configMap"
  },
  {
    "type": "file",
    "path": "/opt/vantiq/config",
    "filename": "mongoDbService.json",
    "content": "{\"hosts\": [{\"host\": \"vantiq-mongoedge-headless:27017\"}]}",
    "dataSource": "configMap"
  },
  {
    "type": "file",
    "dataSource": "configMap",
    "content": "{ \"config\": { \"semanticIndexService\": {\"vectorDB\": { \"host\": \"vantiq-qdrantedge-headless\"}}}}",
    "path": "/opt/vantiq/config",
    "filename": "io.vantiq.modelmgr.ModelManager.json"
  }
]

Be sure to replace <imagePullSecretName> with the name of the Image Pull Secret created earlier and <hostName> with the
host name for the Kubernetes cluster.

If you have deployed the Qdrant Installation, you also need to define the Qdrant file section above (the last one). If not, this section does not need
to be included.

Note that both MongoDB and Qdrant host names use the Installation names defined in the previous sections (i.e., mongoedge and qdrantedge). If you named the Installations differently, you will need to change the host names accordingly.

  • Alternatively to using an imagePullSecret at deployment time, it is also perfectly acceptable to attach the
    imagePullSecret to a service account, and include the service account name instead. For more information, refer to
    the External Lifecycle Management Documentation.
  • If using the Configuration Options UI, fill out the Image option (need to fill out both Name and Image Pull
    Secret    ), then add one Inbound Port option and the File options, filling out each exactly as defined above.

    • For the "content" of the "mongoDbService.json" and "io.vantiq.modelmgr.ModelManager.json" configuration options, the escaped quotation marks are only necessary when editing the configuration as JSON.

The tag for the vantiq-edge image (the 1.37.0 in "name": "quay.io/vantiq/vantiq-edge:1.37.0") can be
changed to whichever suitable version the developer would like to use. The version tags are listed in the quay.io
repository. The tag for the ai-assistant image must match the tag for the vantiq-edge image for the major and minor
version. The patch version might be different, but should preferably be the same.

  • NOTE: Do NOT use any tag containing SNAPSHOT.

Finally, press the Deploy button to create the Work Item. Once the Work Item has been completed, the Vantiq Edge image
should be deployed in the Kubernetes Cluster. The Kubernetes Cluster administrator can check to make sure it has been
successfully deployed by searching for a Stateful Set with the same name as the Vantiq Installation.

Deploying AI-Assistant Edge Installation

If you want to deploy the AI capabilities, you will need to deploy an AI-Assistant Edge Installation.

Navigate to the K8s Cluster in the Vantiq IDE, and click on the Deploy button to deploy a new Installation. Name the Installation AIAssistantEdge and configure it with the following information, either by using the Edit Config as JSON option to paste in the following text, or by manually entering the image field via the Configuration Options UI:

[
   {
      "type": "image",
      "name": "quay.io/vantiq/ai-assistant:1.37.0",
      "imagePullSecret": "<imagePullSecretName>"
   }
]

Be sure to replace <imagePullSecretName> with the name of the Image Pull Secret as described in the section above.

Finally, press the Deploy button to create the Work Item. Once the Work Item has been completed, the AI-Assistant Edge image
should be deployed in the Kubernetes Cluster. The Kubernetes Cluster administrator can check to make sure it has been
successfully deployed by searching for a Stateful Set with the same name as the AI-Assistant Installation.

AI-Assistant Configuration

If you have installed the AI-Assistant and Qdrant vector database, additional configuration steps are required.

Once you are logged as the system user as described in the Setting Up Vantiq Edge section:

  • Go to Administer/Advanced/Service Connectors
  • Edit the AIAssistantService entry and set the hostname to vantiq-aiassistantedge-headless and port value to 8888.
    If you defined a different name for the AI-Assistant Edge Installation, change the hostname accordingly.
  • Save the changes

then,

  • Go to Admnister/Deploy/Nodes
  • Edit the self entry and set the uri to the Vantiq Edge address so it can be accessed from the other deployed Installations.
    For example, it could be set to http://vantiq-edgevantiq-headless:8080 to use the internal Vantiq Edge cluster address, or it could be set to the external address if one is available.
  • Save the changes

Edge Vision Server

To deploy an Edge Server that includes Vision and TensorFlow support you need to use an image
from the vantiq-edge-vision repository. Image version tags are suffixed with either -cpu or -gpu. The -cpu images
can run on any machine using the docker compose instructions above. -gpu images take advantage of the
NVIDIA GPUs on the host machine and require additional configuration.

To use the -gpu images you must install the Nvidia Container Toolkit
on your host system. This toolkit allows Docker to communicate with the NVIDIA drivers and expose the GPUs to the containers.

Once the toolkit is installed, you can verify that containers have access to the GPUs by running the nvidia-smi command:

docker run -it --rm --gpus all ubuntu nvidia-smi

With the toolkit container installed, you can now configure the docker compose file by adding a deploy
section to the vantiq_edge service. For example,

vantiq_edge:
    container_name: vantiq_edge_server
    image: quay.io/vantiq/vantiq-edge-vision:1.37.0-gpu
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu]
    ports:
      - 8080:8080
    ...

Once the docker compose file is configured, start the server with the docker compose up -d command.

You can check that Vision and TensorFlow support is enabled by looking at the logs for the vantiq_edge_server container.

docker logs -f vantiq_edge_server

You will see log messages such as TensorFlowService started and The visual processor has been loaded successfully.

Setting Up Vantiq Edge

With the Vantiq Edge installation now running, the next step is to properly configure the installation. This can be done
through the Vantiq IDE.

The Edge IDE should look similar to that of the cloud-based installations. To access it, go to the URL of the deployed
system (often times http://localhost:8080/ui/ide/index.html). For an edge deployed in a K8s Installation,
you will need to use the node name provided as part of the installation definition (specifically, as part of the
inboundPort). As described in K8s Cluster Deployment documentation, that must
be a resolvable address in your network. That will probably be done via /etc/hosts/, but need not be done that way.
Then, the IDE should be accessible at http://<hostname> where <hostname> is the hostname defined in the previous
step.

  • (This is the host name provided as the host in the inboundPort definition)

The IDE should initially display a window requesting login credentials. Login as the system user with the following
credentials:

Username: system
Password: fxtrt$1492

After logging in, the next steps are:

  • change the system password
  • set the default LLMs API key
  • create a new Organization and Namespace

Changing the System Password

Select the menu Administer/Users and select the system user. Enter a new password and click Save, then
type a second time to confirm the new password.

Setting the default LLMs API key

Open the LLMs pane by selecting Add/LLMs from the menu. In the configuration description column, you will find the names
of the required API keys, represented as secrets (e.g., @secrets(OPENAI_API_KEY)) for the generative LLMs.
To edit or add the necessary secret(s), go to Administer/Advanced/Secrets. For instance, if the secret for
OPENAI_API_KEY is already defined to specify an OpenAI key, simply update it by entering
your API key value in the Secret field.

Creating a New Organization and Namespace

It is imperative that no applications
run in the system Namespace, so creating a new Organization and Namespace is critical. This will involve
creating a new user with a different username/password.

For more information, refer to the Administrators Reference Guide or follow the User and Namespace
Administration Tutorial

Vantiq Edge Self Node

The Vantiq Edge system self Node URI is set during initial startup with the default value localhost:8080. It is
possible to override this default value by defining vantiqExternalUri within a file named
io.vantiq.vertx.BootstrapVerticle.json placed in the Vantiq Edge config directory.

For example,

{
    "vantiqExternalUri": "<my server’s URI>"
}

For the override to take effect this file must be present during the initial Vantiq Edge startup.

If the system has already been started once, you will have to manually edit the URI of the Node named self while logged into
the system namespace.

Edge Installation Management

As all the Vantiq Edge installation’s data is stored in the adjacent MongoDB instance, it is crucial that
production-quality deployments backup the database. The following notes provide high-level guidelines for this process:

  • Backup MongoDB on a frequent basis.
  • Store the MongoDB backup on a machine separate from the edge compute device.
  • To restore MongoDB, you must start with an empty ars02 database.
  • After restoring MongoDB, manually check that the Vantiq Edge installation contains the data that is expected.
  • To backup and restore semantic indexes and Qdrant data, refer to the Vantiq CLI dump and load commands for the semanticindexes resource.