Quickstart

This guide walks you through installing Turqoa, configuring a single gate lane, and processing your first automated gate transaction.

Prerequisites

Hardware Requirements

Software Requirements

• Linux (Ubuntu 22.04 LTS or RHEL 9)
• Docker Engine 24.0+
• NVIDIA Container Toolkit
• Helm 3.12+ (for Kubernetes deployments)
• A valid Turqoa license key

Note: Windows and macOS are supported for development environments only. Production deployments require Linux.

Installation

Step 1 — Install the Turqoa CLI

curl -fsSL https://get.turqoa.com/cli | bash
turqoa version

Step 2 — Authenticate

turqoa auth login --license <YOUR_LICENSE_KEY>

Step 3 — Initialize a Site

A site represents a physical terminal or port facility. Initialization creates the local configuration directory and pulls the required container images.

turqoa site init --name "my-terminal" --type gate

This creates a configuration directory at ~/.turqoa/sites/my-terminal/ with default configuration files.

Step 4 — Configure Cameras

Edit the camera configuration to point to your IP cameras:

# ~/.turqoa/sites/my-terminal/cameras.yaml
cameras:
  - id: lane-01-front
    endpoint: rtsp://192.168.1.100:554/stream1
    role: container_front
    lane: 01

  - id: lane-01-rear
    endpoint: rtsp://192.168.1.101:554/stream1
    role: container_rear
    lane: 01

  - id: lane-01-plate
    endpoint: rtsp://192.168.1.102:554/stream1
    role: license_plate
    lane: 01

Step 5 — Start Services

turqoa site start --name "my-terminal"

This launches all required containers: perception engines, decision engine, orchestration service, and the operator dashboard.

Verify all services are running:

turqoa site status --name "my-terminal"

Expected output:

Service              Status    Health
─────────────────────────────────────
perception-ocr       running   healthy
perception-damage    running   healthy
decision-engine      running   healthy
orchestration        running   healthy
command-center       running   healthy
audit-service        running   healthy

Initial Configuration

Connect to Your TOS

Turqoa integrates with your Terminal Operating System to validate appointments and update transaction records:

# ~/.turqoa/sites/my-terminal/integrations.yaml
tos:
  provider: navis_n4  # or tideworks, cosmos, custom
  endpoint: https://tos.my-terminal.com/api/v2
  auth:
    type: oauth2
    client_id: turqoa-client
    client_secret_env: TOS_CLIENT_SECRET
  sync_interval: 30s

Set Decision Mode

For initial deployment, start in Shadow mode. In this mode, the decision engine runs but does not actuate barriers — all decisions are logged for review.

turqoa config set decision.mode shadow --site "my-terminal"

Warning: Do not switch to live mode until you have validated decision accuracy in shadow mode for at least 48 hours of production traffic.

First Gate Transaction

With the system running in shadow mode, drive a truck through the instrumented lane. Turqoa will:

1. Detect the vehicle via motion trigger on the front camera
2. Capture images from all configured cameras for the lane
3. Run OCR on the license plate and container code
4. Run damage detection on the container surface images
5. Validate the container code against your TOS appointment list
6. Evaluate rules in the decision engine and produce a decision
7. Log the full transaction to the audit trail

Viewing the Transaction

Open the Command Center dashboard:

turqoa dashboard open --site "my-terminal"

Navigate to Transactions > Recent to see the processed transaction. The detail view shows:

• Captured images with OCR overlays
• Confidence scores for each read
• Decision engine rule evaluations
• Final decision (approve/review/deny) and reasoning

Inspecting via CLI

turqoa transactions list --site "my-terminal" --limit 5
turqoa transactions inspect <TRANSACTION_ID>

Verifying the Installation

Run the built-in diagnostic suite to confirm all components are functioning correctly:

turqoa diagnose --site "my-terminal"

This checks:

• Camera connectivity and frame capture
• GPU availability and model loading
• TOS integration connectivity
• Decision engine rule compilation
• Audit service write capability
• Barrier controller communication (if configured)

Note: If any checks fail, consult the troubleshooting guide or run turqoa logs --service <service_name> to inspect container logs.

Next Steps

• Core Concepts — Understand decision modes, zones, and events
• Gate OS — Configure OCR, damage detection, and decision rules
• Terminal Security — Set up perimeter monitoring