Skip to content

Setup

Tursio consists of three core components: a data agent, an AI service, and an admin portal.

  • The data agent manages connections to data sources along with any encryption.
  • The AI service does the heavy lifting of processing user queries through a web portal.
  • The admin portal handles access control, user management, and other related services.

On-premises

Screenshot

On-premises deployment places Tursio entirely within the customer's security boundary, either as a Docker image or an AKS container.

Pre-requisites

Before installing Tursio, ensure your system meets the following requirements:

System Requirements

  • CPU: 4 cores (x86_64 architecture)
  • Memory: Minimum 8 GB RAM
  • Operating System: Ubuntu 24.04 LTS (recommended)
  • Storage: At least 20 GB of free disk space

Software Requirements

  • Docker with Docker Compose — Official Installation Guide
  • curl and wget — for downloading the image tarballs
  • unzip — for extracting deployment archives (AKS or K8s manifests)
  • kubectl — required only for AKS/Kubernetes deployments (Install Guide)
  • Azure CLI — required only for Azure VM or AKS deployments (Install Guide)

Standalone Docker

  • Request the Tursio image for Docker Compose here.
  • The image URL on S3 will be shared. Use curl or wget to download the image tarball.
  • Once downloaded, load the image with the following command:

docker load -i <path-to-image-tarball>
- Run the following command to get the loaded image name and tag:

docker image ls
- Open the compose.yaml file and verify the following: - All environment variables are valid. - Postgres settings are correct (update them if you are using a different instance). - The image name and tag match the ones from the loaded tarball. - Run docker compose up -d - Verify the deployment as shown in the screenshot below:

Screenshot

  • Based on where and how the VM is hosted, allow port 8080 to be accessible from the internal network (use per-user IP filtering on cloud deployments for security). Then access the portal at the VM's public IP address on port 8080. Example: http://public-ip:8080

AKS Cluster

Prerequisites

  • Active Azure subscription with sufficient permissions to:
    • Create resource groups
    • Provision AKS clusters
    • Assign roles (if using private registries)
  • Azure CLI installed — Official Documentation
  • Kubernetes CLI (kubectl) for interacting with the cluster — Official Documentation
  • Container Registry Access: If using Azure Container Registry (ACR) to store custom Docker images (e.g., PostgreSQL with pgvector), ensure the ACR is attached to the AKS cluster:
    • az aks update --name <yourAKSClustername> --resource-group <your-resource-group> --attach-acr <your-acr-name>
    • Replace <your-acr-name> with the ACR name (e.g., myregistry).
    • This ensures the AKS cluster can pull private images from the registry.
  • PostgreSQL with pgvector Extension: Tursio uses pgvector for vector search in PostgreSQL. If using a private PostgreSQL image:

Installation

  • Request the Tursio image for AKS cluster here.
  • The AKS manifests and the image URL on S3 will be shared. Use curl or wget to download the image tarball and the K8s zip files.
  • Once downloaded, load the image: 
    docker load -i <path-to-image-tarball>
  • Run the following command to get the loaded image name and tag:

docker image ls
- Open deployment-portal.yaml and verify the following: - All environment variables are valid. - Postgres settings are correct (update them if you are using a different instance). - The image name and tag match the ones from the loaded tarball. - Run kubectl apply -f . - Verify the deployment as shown in the screenshot below:

Screenshot

Azure VM Extension

Create VM

  • Go to Microsoft Azure to create a new VM.
  • Select a supported region: Central US EUAP, East US EUAP, or West Central US, along with your subscription and resource group as shown below.
  • Use Ubuntu 24.04 as the image. Ubuntu 22.04 has GLIBC issues that prevent the Tursio binary from running.

Create a virtual machine

  • Proceed through the VM creation wizard until you reach the Advanced tab.
  • Go to the Extensions section and click "Select an extension to install".
  • Scroll to the bottom of the extensions list, select the Tursio Agent, click "Next", and then "Create" to add the extension.

Create a virtual machine - Advanced tab

  • Back on the Advanced tab, add the following initialization script in the Custom data section to set up the VM for the Tursio Agent: 
    #cloud-config
runcmd:
  - |
    #!/bin/bash
    set -e

    echo "Starting Docker Engine installation on Ubuntu..."

    # Uninstall conflicting Docker packages
    echo "Removing conflicting Docker packages if any..."
    for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
      if dpkg -l | grep -qw "$pkg"; then
        sudo apt-get remove -y "$pkg"
      fi
    done

    # Update package index and install prerequisites
    echo "Updating package index and installing prerequisites..."
    sudo apt-get update
    sudo apt-get install -y ca-certificates curl gnupg

    # Setup Docker official GPG key and repository
    echo "Setting up Docker GPG key and repository..."
    sudo install -m 0755 -d /etc/apt/keyrings
    curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
      | sudo tee /etc/apt/keyrings/docker.asc > /dev/null
    sudo chmod a+r /etc/apt/keyrings/docker.asc

    UBUNTU_CODENAME=$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")

    echo "Adding Docker repository for Ubuntu $UBUNTU_CODENAME"
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $UBUNTU_CODENAME stable" \
      | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

    # Update package index again
    echo "Updating package index for Docker packages..."
    sudo apt-get update

    # Install Docker Engine and components
    echo "Installing Docker Engine and related packages..."
    sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

    # Enable and start Docker service
    echo "Enabling and starting Docker service..."
    sudo systemctl enable docker
    sudo systemctl start docker

    # Verify Docker installation
    echo "Verifying Docker installation..."
    sudo docker run --rm hello-world

    echo "Docker Engine installation completed successfully!"
    echo "Tip: To run Docker without 'sudo', add your user to the docker group:"
    echo "  sudo groupadd docker"
    echo "  sudo usermod -aG docker \$USER"
    echo "Log out and back in for group changes to take effect."
  • The Advanced page should look like the screenshot below. Install an Extension
  • Click Create to provision the VM.
  • You will be prompted to download an SSH private key file. Save this securely — it is needed to SSH into the VM.

Connect

  • Once the VM is created, navigate to the VM's Overview page in the Azure Portal.
  • Click the Connect button to get the SSH connection command.
  • Run the SSH command in your terminal using the downloaded key:
chmod 400 <path-to-the-ssh-key>
ssh -i <path-to-the-ssh-key> azureuser@<vm-ip-address>

Connect to VM

Activate and Install Tursio

  • Once logged into the VM, run the following commands:
sudo su

cd /opt/singleportal

./bootstrap activate <license_key> <tursio_version>
  • You will be prompted for an activation key — contact Tursio to obtain one.
  • This installs all required images and artifacts for Tursio.

Access the UI

  • Go to the VM's Networking section in the Azure Portal.
  • Add an Inbound port rule to allow access to port 80.
  • Set the source IP or IP range to your local machine's IP for security.

Network settings

  • Open the VM's public IP address on port 80 in a browser to access the Tursio portal:

portal-with-vm-extension

Cloud

In the cloud deployment model, Tursio manages all components (data agent, AI service, and admin portal). Users can still bring their own LLM keys for privacy. Please contact Tursio to get started with a cloud setup.

Integration

Out of the Box

Once installed, users can log in to the Tursio portal to connect and train their databases. They can manage users and access control, tune the generated semantic model, and run queries and analysis in a self-serve fashion.

For on-premises deployments, the portal runs on localhost (port 8080), which can be mapped to a custom internal URL. For hybrid and cloud deployments, Tursio manages a dedicated single-tenant environment. Users can log in to the portal using their account name. Contact Tursio for the account name and any branding customizations.

Embedding

Tursio provides an embeddable database search widget that enables natural language querying with fine-grained access controls. This includes a frontend component that renders into your existing HTML and backend APIs that handle user authentication, query processing, and access control. Sample code for embedding is available here (contact Tursio for access).

Frontend Integration

Add these two elements to your HTML: 

<div id="tursiosearch"></div>
<script src="./script.min.js"></script>

The search interface automatically renders in place. We will provide the script.min.js file. To initialize the component, the initialize function must be called with the accessToken parameter. 

const accessToken = "<placeholder>"; // call the /api/init to get the accessToken
window.Widgets.initialize(accessToken); // Prepares the component with provided accessToken

Backend APIs

Initialize a search component with user-specific access controls. The access determines data access permissions: 

POST /api/init
Body: { "userType": "string", "userId": "string", "database": "string", "access": "table|column|row" }
Response: { "accessToken": "string", "permissions": {...} }

Process search queries with access control. All requests must include the access token from initialization: 

POST /api/submit-question
Headers: Authorization: Bearer {accessToken}
Body: { "question": "string" }
Response: json

Note: All additional APIs require the same access token validation: 

GET /api/history-questions
POST /api/feedback
/api/xxx (any additional features)

Access Control Implementation

Three access levels are supported:

  • Table Level: User can access specific tables
  • Column Level: User can access specific columns within allowed tables
  • Row Level: User can access specific rows within allowed tables (through filter expression)

The following security requirements are met:

  • Implement CLS and RLS
  • Validate access tokens on all API calls
  • Use HTTPS for all communications

Integration Checklist 

- [ ] Add HTML elements to your page
- [ ] Implement `/api/init` with user type and access level
- [ ] Implement `/api/submit-question` with token validation
- [ ] Set up CLS/RLS based on access levels
- [ ] Test with different user types and access levels
- [ ] Integrate all required features