Single-VM (Ubuntu)

This article describes the procedure for deploying askEdgi components on a Single-VM Ubuntu environment, including:

• Edgi Data Service

• Edgi Insight Service

• Required configuration updates to the OvalEdge UI and Job Services

Each service is implemented as a Python application managed using Poetry and integrated with an existing OvalEdge installation.

This guide assumes an on-premises deployment model in which all components run on the same VM.

Purpose

The purpose of this article is to provide a comprehensive, standardized procedure for deploying and configuring askEdgi components—Edgi Data Service and Edgi Insight Service—in a single-VM Ubuntu environment integrated with an existing OvalEdge installation.

It guides administrators through prerequisites, software setup, environment configuration, service deployment, and validation steps to ensure seamless communication between askEdgi services and OvalEdge.

By following this article, teams can achieve a secure, reliable, and fully functional askEdgi setup, with all components running as managed system services and ready for operational use.

Prerequisites

Before starting the installation, ensure the following:

System & Access

• Ubuntu Linux (LTS recommended)

• User with sudo privileges

• Internet access for package installation

Application Prerequisites

• OvalEdge application is already installed and running on the same VM

• MySQL database is accessible

• Elasticsearch is installed and running (port 9200)

Software Requirements

• Python 3.13.x

• Poetry 2.1.3

Do not remove or overwrite the system default Python version used by Ubuntu. Doing so may break apt and system services.

Network & Port Requirements

The following inbound ports must be opened on the VM firewall to allow communication between OvalEdge and askEdgi services:

Port	Service	Purpose
8001	Edgi Data	Communication between Edgi Data Service and OvalEdge
8000	Edgi Insight	Communication between Edgi Insight Service and OvalEdge

Restrict inbound access to these ports to localhost or trusted internal IP ranges only.

Installation Steps

Python 3.13

1. Enable Required Repository

   sudo apt install software-properties-common -y
   sudo add-apt-repository ppa:deadsnakes/ppa -y
   sudo apt update

2. Check the existing Python version:

   python3 --version

3. If the version is below 3.13.x, install Python 3.13:

   sudo apt install -y python3.13

   Sample Reference Screenshot:

   
4. Configure alternatives (do not remove existing Python):

   sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1
   sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.13 2
   sudo update-alternatives --config python3

5. Verify Python version.

   python3 --version

   Sample Reference Screenshot:

   

There are two alternatives: python3 (providing /usr/bin/python3).

Selection	Path	Priority	Status
*0	/usr/bin/python3.10	1	auto mode
1	/usr/bin/python3.10	1	manual mode
2	/usr/bin/python3.13	2	manual mode

Poetry Installation (Version 2.1.3)

1. Install Poetry:

   curl -sSL https://install.python-poetry.org | python3 - --version 2.1.3

   Sample Reference Screenshot:

   
2. Update PATH:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

3. Verify installation:

   poetry --version

   Sample Reference Screenshot:

   

   We need to create two directories for edgi_data and edgi_insight.

Edgi Data Service Deployment

Directory Setup

1. Create Required Directory Structure.

   cd /home/ovaledge/edgi_data
   mkdir logs dbfolder
   touch .env

   Sample Reference Screenshot:

   

Environment Configuration (.env)

1. In the .env file, add the following environment variables.

   # Deployment
   DEPLOYMENT_TYPE=vm
   ENV=production
   # MySQL (Required)
   mysql_url=jdbc:mysql://<MYSQL_HOST>:3306/ovaledgedb?useUnicode=true&character_set_server=utf8mb4&useSSL=false&allowPublicKeyRetrieval=true
   mysql_user=<MYSQL_USER>
   mysql_password=<MYSQL_PASSWORD>
   # Workspace
   WORKSPACE_PROJECT_ID=0001
   WORKSPACE_USER=unknown
   # Logging
   LOG_PATH=/home/ovaledge/edgi_data/logs
   LOG_MODE=INFO
   # DuckDB
   DB_FOLDER=/home/ovaledge/edgi_data/dbfolder
   # Connection Pool
   MYSQL_POOL=10
   MYSQL_POOL_NAME=ovaledge_pool
   # Application Port
   APP_PORT=8001
   # Recipe Connection
   OVALEDGE_RECIPE_CONNECTION_ID=-1

   Sample Reference Screenshot:

   

   Avoid special characters, such as @, in passwords unless explicitly supported.

Package Download & Extraction

1. Download the Edgi Data .tar.gz package (provided by DevOps).

2. Extract it inside /home/ovaledge/edgi_data:

   tar -xvf edgi-data.tar.gz

   Sample Reference Screenshots:

   

   

   

Dependency Installation

1. Navigate to the directory containing pyproject.toml:

   poetry install

   Sample Reference Screenshots:

   

   

Service Validation (Manual)

poetry run service

Sample Reference Screenshot:

If the service starts successfully, stop it using Ctrl+C.

Configure systemd Service

1. Find Poetry path:

   which poetry

   Sample Reference Screenshot:

   
2. Create service file:

   sudo vim /etc/systemd/system/data.service
   [Unit]
   Description=Edgi Data Service
   After=network.target
   [Service]
   User=ovaledge
   WorkingDirectory=/home/ovaledge/edgi_data
   ExecStartPre=/home/ovaledge/.local/bin/poetry install
   ExecStart=/home/ovaledge/.local/bin/poetry run service
   Restart=always
   StandardOutput=append:/home/ovaledge/edgi_data/logs/edgi-data.log
   StandardError=append:/home/ovaledge/edgi_data/logs/edgi-data.log
   Environment="PATH=/home/ovaledge/.local/bin:/usr/local/bin:/usr/bin"
   [Install]
   WantedBy=multi-user.target

3. Enable and start:

   sudo systemctl daemon-reload
   sudo systemctl start data.service
   sudo systemctl enable data.service
   sudo systemctl status data.service

Service Management Commands

Action	Command
Reload Service	systemctl daemon-reload
Start Service	systemctl start data.service
Enable Service	Systemctl enable data.sevice
Check Status	systemctl status data.service

Edgi Insight Service Deployment

Directory Setup

1. Inside the edgi_insight folder, we need to create the following folders and an '.env' file.

   cd /home/ovaledge/edgi_insight
   mkdir logs docu dbfolder storefolder
   touch .env

   Sample Reference Screenshot:

   

Environment Configuration (.env)

1. In the $ vi .env file, add the following environment variables.

   # Deployment
   DEPLOYMENT_TYPE=vm
   ENV=production
   # MySQL
   mysql_url=jdbc:mysql://<MYSQL_HOST>:3306/ovaledgedb?useUnicode=true&character_set_server=utf8mb4&useSSL=false&allowPublicKeyRetrieval=true
   mysql_user=<MYSQL_USER>
   mysql_password=<MYSQL_PASSWORD>
   # Workspace
   WORKSPACE_PROJECT_ID=0001
   WORKSPACE_USER=unknown
   # Logging
   LOG_PATH=/home/ovaledge/edgi_insight/logs
   LOG_MODE=DEBUG
   EDGI_DEBUG_MODE=False
   ENABLE_LLM_RESPONSE_CAPTURE=False
   ALLOW_RAG_CRAWLING=False
   # Elasticsearch
   elasticsearch.enabled=true
   elasticsearch.index.name.prefix=ovaledge
   elasticsearch.index.name.seperator=_
   elasticsearch.ovaledge.env=dev
   es_host=<ELASTIC_HOST>
   es_port=9200
   es_username=elastic
   es_password=<ELASTIC_PASSWORD>
   es_protocol=http
   # Edgi Data Service
   EDGI_WORKSPACE_DISCOVERY=static
   EDGI_WORKSPACE_PROTOCOL=http
   EDGI_WORKSPACE_HOST=localhost
   EDGI_WORKSPACE_PORT=8001
   # Storage Paths
   DB_FOLDER=/home/ovaledge/edgi_insight/dbfolder
   DOCS_FOLDER=/home/ovaledge/edgi_insight/docu
   STORE_FOLDER=/home/ovaledge/edgi_insight/storefolder

   Sample Reference Screenshot:

   

Package Installation

1. Download the Edgi insight tar. gz file inside the edgi_data.

   For the Edgi insight package file, the DevOps team will provide a link.

   Sample Reference Screenshots:

   

   
2. Use the tar -xvf command to extract the tar. gz file. Sample Reference Screenshot:

   
3. Extract the Insight package and install dependencies:

   poetry install

   Sample Reference Screenshot:

   
4. Validate service manually:

   poetry run service

   Once it runs without errors, cancel the running process by clicking Ctrl-C.

systemd Configuration

1. Create as a Service

   sudo vim /etc/systemd/system/insight.service
   

   [Unit]
   Description=Edgi Insight Service
   After=network.target
   [Service]
   User=ovaledge
   WorkingDirectory=/home/ovaledge/edgi_insight
   ExecStartPre=/home/ovaledge/.local/bin/poetry install
   ExecStart=/home/ovaledge/.local/bin/poetry run service
   Restart=always
   StandardOutput=append:/home/ovaledge/edgi_insight/logs/edgi-insight.log
   StandardError=append:/home/ovaledge/edgi_insight/logs/edgi-insight.log
   Environment="PATH=/home/ovaledge/.local/bin:/usr/local/bin:/usr/bin"
   [Install]
   WantedBy=multi-user.target

   Enable and start:

   sudo systemctl daemon-reload
   sudo systemctl start insight.service
   sudo systemctl enable insight.service
   sudo systemctl status insight.service

Service Management Commands

Action	Command
Reload Service	systemctl daemon-reload
Start Service	systemctl start insight.service
Enable Service	systemctl enable insight.service
Check Status	systemctl status insight.service

OvalEdge Oasis Configuration

1. Update the Oasis configuration file:

   oe.edgi.enabled=true
   oe.edgi.credential.type=static
   oe.edgi.workspace.host=localhost
   oe.edgi.workspace.port=8001
   oe.edgi.insight.service.host=localhost
   oe.edgi.insight.service.port=8000

   Sample Reference Screenshot:

   
2. Restart Tomcat:

   sudo systemctl restart tomcat

OvalEdge UI Configuration

1. Log in to OvalEdge.

2. Validate the -1 MySQL connector and perform crawl & profiling.