On-Premise Deployment

This guide covers the full installation and configuration of Turqoa on hardware within your terminal's data center. On-premise deployment provides the lowest latency for gate operations and complete data sovereignty.

Hardware Requirements

Minimum Specifications (up to 4 gate lanes)

Component	Specification
CPU	Intel Xeon Silver 4314 (16 cores) or AMD EPYC 7313 (16 cores)
GPU	NVIDIA T4 (16 GB VRAM) x 1
RAM	64 GB DDR4 ECC
Storage (OS + Application)	500 GB NVMe SSD
Storage (Data + Images)	4 TB NVMe SSD (RAID 1)
Network	Dual 10 GbE NICs
Power	Redundant PSU (750W+)

Recommended Specifications (5-12 gate lanes)

Component	Specification
CPU	Intel Xeon Gold 6338 (32 cores) or AMD EPYC 7543 (32 cores)
GPU	NVIDIA A30 (24 GB VRAM) x 2
RAM	128 GB DDR4 ECC
Storage (OS + Application)	1 TB NVMe SSD
Storage (Data + Images)	8 TB NVMe SSD (RAID 10)
Network	Dual 25 GbE NICs
Power	Redundant PSU (1200W+)

Network Requirements

Requirement	Details
Camera VLAN	Isolated VLAN for all camera traffic. Minimum 1 Gbps per 8 cameras.
Management VLAN	Separate VLAN for Turqoa management traffic and Command Center UI.
TOS connectivity	Routable path to TOS API endpoint. Latency < 50ms.
DNS	Internal DNS resolution for Turqoa hostname and TOS endpoints.
NTP	Time synchronization within 1 second across all gate controllers and cameras.
Firewall	Outbound HTTPS (443) for license validation and optional telemetry.

Operating System Requirements

Turqoa is supported on the following operating systems:

Ubuntu Server 22.04 LTS (recommended)
Red Hat Enterprise Linux 9.x
Rocky Linux 9.x

Required packages: Docker Engine 24+, NVIDIA Container Toolkit, and curl.

Installation Steps

1. Prepare the Host

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker

# Install NVIDIA drivers and container toolkit
sudo apt install -y nvidia-driver-535
sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

2. Verify GPU Access

docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

You should see your GPU(s) listed with driver version and CUDA version.

3. Deploy Turqoa

# Download the Turqoa installer
curl -fsSL https://install.turqoa.com/on-premise | sudo bash

# Run the installer with your license key
sudo turqoa-install \
  --license-key ${TURQOA_LICENSE_KEY} \
  --hostname turqoa.terminal.local \
  --gpu-count 1 \
  --gate-lanes 4

4. Configure the Environment

# Edit the main configuration file
sudo nano /etc/turqoa/turqoa.env

Key configuration parameters:

# Database
TURQOA_DB_HOST=localhost
TURQOA_DB_PORT=5432
TURQOA_DB_NAME=turqoa
TURQOA_DB_PASSWORD=<generated-during-install>

# AI Inference
TURQOA_GPU_DEVICES=0
TURQOA_MODEL_CACHE=/var/lib/turqoa/models

# Camera ingestion
TURQOA_CAMERA_MAX_STREAMS=24
TURQOA_CAMERA_BUFFER_SIZE_MB=512

# TOS
TURQOA_TOS_PROVIDER=navis-n4
TURQOA_TOS_BASE_URL=https://n4.terminal.local/apex/api/v1

5. Start Services

sudo turqoa up

This starts all Turqoa services: API server, AI inference workers, event bus, database, and the Command Center web interface.

Health Check

Verify the deployment is operational:

# Check all service statuses
sudo turqoa status

# Expected output:
# turqoa-api         ✓ running  (port 8080)
# turqoa-inference   ✓ running  (GPU 0)
# turqoa-events      ✓ running  (Kafka)
# turqoa-db          ✓ running  (PostgreSQL 15)
# turqoa-ui          ✓ running  (port 443)

# Run the built-in diagnostic
sudo turqoa diagnose

# Checks: GPU availability, DB connectivity, TOS reachability,
#          camera stream connectivity, disk space, NTP sync

Access the Command Center at https://turqoa.terminal.local to verify the web interface loads and displays connected cameras and gate lane status.

Note: The initial startup may take 5-10 minutes as AI models are loaded into GPU memory. Subsequent restarts are faster due to model caching.