UneeQ

Complete Setup Guide

Step-by-Step Instructions for Local Development

View on GitLab
Complete Setup: This guide walks through setting up both frontend and backend components for local development. Both services must run together for full functionality.
1
Prerequisites & System Requirements

Minimum Requirements

  • Node.js: v20.0.0 or higher
  • npm: v8.0.0 or higher
  • Memory: 4GB RAM minimum
  • Browser: Chrome, Firefox, Safari, or Edge (latest versions)

Recommended Setup

  • Node.js: v20.17.0 LTS
  • npm: v10.0.0 or higher
  • Memory: 8GB RAM or more
  • OS: macOS, Linux, or Windows 10/11
Node.js Version Check: Run node --version to verify. If you need to install or update Node.js, use nodejs.org or nvm (Node Version Manager).
2
Repository Setup

Clone and Navigate to Repository

git clone <repository-url>
cd kiosk-application

Repository Structure Overview

kiosk-application/ ├── interface/ # Frontend React Application │ ├── src/assets/config.sample.yaml # Configuration template │ └── README.md # Frontend documentation ├── websocket-api/ # Backend Serverless API │ ├── .env.example # Environment template │ └── README.md # Backend documentation └── public/ # This documentation site
3
Required Service Accounts
Required: You need API keys from Deepgram and UneeQ to run the application. Set these up before proceeding with configuration.

🎤 Deepgram Account (Speech-to-Text)

  1. Sign up at Deepgram Console
  2. Create a new project
  3. Generate an API key from project settings
  4. Copy the key - you'll need it for backend configuration

🤖 UneeQ Account (Digital Human)

  1. Get UneeQ account and persona access
  2. Obtain persona IDs for your digital humans
  3. Get CDN and API endpoints
  4. Copy the credentials - you'll need them for frontend configuration
4
Backend Configuration & Setup

Navigate to Backend Directory

cd websocket-api/

Create Environment Configuration

# Copy the sample environment file
cp .env.example .env
Edit .env File: Open the .env file and add your actual API keys. Generate a secure HTTP_SERVICE_API_KEY using openssl rand -base64 32.

Required Environment Variables

# .env file configuration
DEEPGRAM_API_KEY=your_deepgram_api_key_from_step_3
HTTP_SERVICE_API_KEY=your_secure_random_key_here

# Optional settings (defaults provided)
AWS_REGION=us-east-2
NODE_RUNTIME=nodejs20.x
LOG_LEVEL=info
WEBSOCKET_PORT=3001
HTTP_PORT=3000

Install Backend Dependencies

npm install

Start Backend Development Server

# Start local development server
npm run dev

# You should see:
# Serverless: Offline [http for lambda] listening on http://localhost:3000
# Serverless: [websocket] listening on ws://localhost:3001
Backend Running: Leave this terminal open and running. The backend provides WebSocket (port 3001) and HTTP (port 3000) services that the frontend requires.
5
Frontend Configuration & Setup

Open New Terminal and Navigate to Frontend

# Open a new terminal window/tab
cd interface/

Create Configuration File

# Copy the sample configuration file
cp src/assets/config.sample.yaml src/assets/config.yaml
Critical: The application will not work without this configuration file. You must create it from the sample and edit it with your settings.

Edit Configuration File

Open src/assets/config.yaml and configure the following sections:

1. Application Settings

app:
  name: "Your Kiosk Name"
  environment: "development"  # development/staging/production

2. UneeQ Persona Configuration

personas:
  en:  # Language code (en, fr, de, es, pt, ja, ar)
    cloud:
      CDN: "https://cdn-eu.uneeq.io/hosted-experience/deploy/index.js"
      API: "https://api-eu.uneeq.io"
      id: "your-persona-id-from-uneeq-account"
    miniprem:
      CDN: "https://cdn-eu.uneeq.io/hosted-experience/deploy/index.js"
      API: "https://api-eu.uneeq.io"
      id: "your-persona-id-from-uneeq-account"

3. Backend Connection (for local development)

backend:
  endpoints:
    ws: "ws://localhost:3001"      # WebSocket endpoint
    http: "http://localhost:3000"  # HTTP API endpoint
  key: "your-backend-api-key-from-step-4"  # HTTP_SERVICE_API_KEY value

Install Frontend Dependencies

npm install

Start Frontend Development Server

# Start the frontend development server
npm run dev

# You should see:
# VITE v6.x.x ready in xxx ms
# ➜  Local:   http://localhost:5173/
6
Verification & Testing

Open the Application

Navigate to http://localhost:5173 in your browser.

Successful Setup Indicators: When everything is working correctly, you should see the following status indicators on the start screen.

✅ Expected Status Indicators

On the Start Screen

  • Uneeq Script: Ready (green)
  • WebSocket: Connected (green)
  • Session ID: A generated UUID
  • Start Button: Enabled (clickable)

In Browser Console (F12)

  • No red error messages
  • Messages like "Uneeq initialized"
  • "WebSocket connection established"
  • Configuration loaded successfully
7
Common Issues & Solutions
Issue Symptom Solution
Config Not Found Blank page or config errors Create config.yaml from sample (Step 5)
WebSocket Disconnected Red "Disconnected" status Start backend service (Step 4) on port 3001
Start Button Disabled Button is grayed out Check both WebSocket and UneeQ status indicators
Port Already in Use Error when starting servers Change port: npm run dev -- --port 5174
Node Version Error Build/install failures Update to Node.js v20+ (Step 1)
Missing API Keys "Missing required environment variable" Add Deepgram API key to backend .env file
8
Next Steps & Development

🚀 Test the Application

  • Click "Start Experience" to begin
  • Try different language options
  • Test with mobile remote control
  • Verify voice input functionality

⚙️ Customize Configuration

  • Add your own UneeQ persona keys
  • Configure additional languages
  • Adjust backend endpoints for production
  • Set environment modes appropriately

📚 Explore Documentation

9
Development Workflow

Making Changes

  1. Edit source files in interface/src/ or websocket-api/src/
  2. Hot-reload automatically applies changes in development mode
  3. Check browser console for errors and debugging information
  4. Use debug panels available in development environment

Useful Development Commands

Frontend Commands (interface/)

# Build for production
npm run build

# Preview production build
npm run preview

# Run linting
npm run lint

# View integrated documentation
npm run docs

Backend Commands (websocket-api/)

# Run tests
npm run test

# Type checking
npm run typecheck

# Lint and fix
npm run lint:fix

# Build for deployment
npm run build
Development Mode Features: In development environment, you have access to performance monitoring overlays, debug panels, detailed console logging, and React Developer Tools integration.
10
Getting Help

If you encounter issues during setup:

  1. Check browser console (F12) for error messages and detailed logs
  2. Verify all services are running - both frontend and backend terminals should be active
  3. Ensure configuration files exist and contain valid YAML with correct API keys
  4. Check network ports - ensure 3000, 3001, and 5173 are not blocked or in use
  5. Review status indicators on the application start screen for specific issues
Setup Complete! You now have a fully functional UneeQ Kiosk Application running locally with both digital human interface and mobile remote control capabilities.