🚀 Voralis Complete Installation & Configuration Guide

This comprehensive guide covers installation and configuration for both Voralis Web (Next.js) and Voralis App (Expo React Native).

📋 Table of Contents

Part 1: Voralis Web Installation

Prerequisites (Voralis Web)

Before starting, ensure you have:

  • ✅ Node.js 18.x or higher installed
  • ✅ npm or yarn package manager
  • ✅ Git installed
  • ✅ A code editor (VS Code recommended)
  • ✅ Access to terminal/command line

Installation Steps (Voralis Web)

Step 1: Clone or Download the Project

# If using Git
git clone <your-repository-url>
cd voralis-web

# Or extract the downloaded ZIP file

Step 2: Install Dependencies

# Using npm
npm install

# Or using yarn
yarn install

Step 3: Create Environment File

# Create .env.local file
touch .env.local

# Or on Windows
type nul > .env.local

Environment Variables Setup (Voralis Web)

Create a .env.local file in the root directory of voralis-web with all the following variables.

# ============================================
# DATABASE CONFIGURATION (REQUIRED)
# ============================================
NEON_DATABASE_URL=postgresql://username:password@host:port/database
DATABASE_URL=postgresql://username:password@host:port/database

# ============================================
# LICENSE VERIFICATION (REQUIRED)
# ============================================
# Brain Server URL (provided by your vendor/developer)
NEXT_PUBLIC_BRAIN_SERVER_URL=https://your-brain-server.vercel.app

# License Key (provided by your vendor/developer)
NEXT_PUBLIC_LICENSE_KEY=your-license-key-here

# ============================================
# AI SERVICES (REQUIRED)
# ============================================
# Grok (xAI) - Primary AI Chat
GROK_API_KEY=your-grok-api-key
GROK4_API_KEY=your-grok-api-key
GROK4_BASE_URL=https://api.x.ai/v1

# OpenAI - For DALL-E and GPT models
OPENAI_API_KEY=sk-your-openai-api-key

# Google Gemini
GEMINI_API_KEY=your-gemini-api-key

# DeepSeek (Optional)
DEEPSEEK_API_KEY=your-deepseek-api-key

# Anthropic Claude (Optional)
ANTHROPIC_API_KEY=your-anthropic-api-key

# ============================================
# VIDEO GENERATION & WORKERS (REQUIRED for Video Ads)
# ============================================
HEYGEN_API_KEY=your-heygen-api-key
RESEND_API_KEY=your-resend-api-key

# Redis (for Job Queue)
UPSTASH_REDIS_REST_URL=https://your-redis-url.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-redis-token

# Firebase (for Push Notifications)
FIREBASE_API_KEY=your-api-key
FIREBASE_AUTH_DOMAIN=your-app.firebaseapp.com
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_STORAGE_BUCKET=your-app.appspot.com
FIREBASE_MESSAGING_SENDER_ID=123456789
FIREBASE_APP_ID=1:123456:web:abcdef
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxx@your-project.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
..."

# ============================================
# FAL API KEY (REQUIRED)
# ============================================
FAL_API_KEY=your-fal-api-key

# ============================================
# TEXT-TO-SPEECH (REQUIRED)
# ============================================
ELEVENLABS_API_KEY=your-elevenlabs-api-key

# ============================================
# OTHER SERVICES (OPTIONAL)
# ============================================

SERPAPI_KEY=your-serpapi-api-key
TAVILY_API_KEY=your-tavily-api-key
WEATHER_API_KEY=your-weather-api-key

# ============================================
# PAYMENT PROVIDERS (OPTIONAL - Choose one or more)
# ============================================
# Stripe
STRIPE_SECRET_KEY=sk_live_your-stripe-secret-key
STRIPE_PUBLISHABLE_KEY=pk_live_your-stripe-publishable-key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_your-stripe-publishable-key
STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret

# PayPal
PAYPAL_CLIENT_ID=your-paypal-client-id
PAYPAL_CLIENT_SECRET=your-paypal-client-secret
PAYPAL_MODE=sandbox
NEXT_PUBLIC_PAYPAL_CLIENT_ID=your-paypal-client-id

# Paystack
PAYSTACK_SECRET_KEY=sk_live_your-paystack-secret-key
PAYSTACK_PUBLIC_KEY=pk_live_your-paystack-public-key
NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY=pk_live_your-paystack-public-key

# Adyen
ADYEN_API_KEY=your-adyen-api-key
ADYEN_MERCHANT_ACCOUNT=your-merchant-account
ADYEN_CLIENT_KEY=your-adyen-client-key
NEXT_PUBLIC_ADYEN_CLIENT_KEY=your-adyen-client-key

# Airwallex
AIRWALLEX_API_KEY=your-airwallex-api-key
AIRWALLEX_CLIENT_ID=your-airwallex-client-id
AIRWALLEX_WEBHOOK_SECRET=your-airwallex-webhook-secret

# ============================================
# STORAGE SERVICES (REQUIRED - Choose one)
# ============================================
# Cloudflare R2 (Recommended)
R2_ACCOUNT_ID=your-r2-account-id
R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
R2_BUCKET_NAME=your-bucket-name
R2_PUBLIC_URL_PREFIX=https://pub-xxx.r2.dev


# ============================================
# EMAIL SERVICE (REQUIRED)
# ============================================
# SendGrid (Bulk emails Recommended)
SENDGRID_API_KEY=SG.your-sendgrid-api-key
SENDGRID_FROM_EMAIL=noreply@yourdomain.com

# AWS SES (Bulk emails Alternative)
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_aws_key
AWS_SECRET_ACCESS_KEY=your_aws_secret

# Nodemailer (for transactional emails)
NODEMAILER_HOST=smtp.hostinger.com
NODEMAILER_PORT=587
NODEMAILER_SECURE=false # or true for port 465
NODEMAILER_USER=support@byourdomain.com
NODEMAILER_PASS=password

# Mailtrap (Alternative)
MAILTRAP_USER="api"
MAILTRAP_PASS= # api token key
MAILTRAP_API_KEY= #api token key
MAILTRAP_USE_SANDBOX=true       # true/false toggle
MAILTRAP_INBOX_ID=123456        # Only needed for sandbox 2682584

# Or Nodemailer (Alternative)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# ============================================
# SECURITY (REQUIRED)
# ============================================
# JWT Secret (Generate with: openssl rand -base64 32)
JWT_SECRET=your-jwt-secret-key

# Admin Secret (Generate with: openssl rand -base64 32)
ADMIN_SECRET_KEY=your-admin-secret-key

# reCAPTCHA (Optional)
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your-recaptcha-site-key
RECAPTCHA_SECRET_KEY=your-recaptcha-secret-key


# ============================================
# MUSIC GENERATION (OPTIONAL)
# ============================================
# Suno AI
SUNO_API_KEY=your-suno-api-key

# Base URL
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Environment
NODE_ENV=development

Database Configuration (NeonDB)

Step 1: Create NeonDB Account

  1. Go to Neon Console
  2. Sign up for a free account (or log in)
  3. Click Create Project
  4. Enter a project name (e.g., Voralis Production)
  5. Select a region closest to your users
  6. Click Create Project

Step 2: Get Database Connection String

  1. In your Neon project dashboard, click on Connection Details
  2. You'll see a connection string like:
postgresql://username:password@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require

3. Copy this entire string

Step 3: Configure in .env.local

NEON_DATABASE_URL=postgresql://username:password@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require
DATABASE_URL=postgresql://username:password@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require

Step 4: Initialize Database Schema

  1. In Neon Console, go to SQL Editor
  2. Open the file: voralis-web/database/database-schema.sql
  3. Copy all SQL statements
  4. Paste into Neon SQL Editor
  5. Click Run to execute

License Verification Setup

The license verification is handled automatically by the system. You only need to configure the license key provided by your vendor/developer.

Step 1: Get Your License Key

Your license key will be provided by:

  • CodeCanyon: Purchase code from your purchase receipt
  • Gumroad: License key from your purchase email
  • Lemon Squeezy: License key from your subscription email

Step 2: Configure License Key

Add your license key to .env.local:

# License Key (provided by your vendor/developer)
NEXT_PUBLIC_LICENSE_KEY=your-license-key-here

# Brain Server URL (provided by your vendor/developer)
NEXT_PUBLIC_BRAIN_SERVER_URL=https://your-brain-server.vercel.app

Step 3: License Activation

  1. Start your development server: npm run dev
  2. Visit http://localhost:3000
  3. The license setup wizard will appear automatically
  4. Enter your license key when prompted
  5. The system will automatically verify and activate your license

Note: The license key format varies by provider:

  • CodeCanyon: UUID format (e.g., 8392af4b-1a2c-4d5e-9f0a-1234567890ab)
  • Gumroad: Four blocks format (e.g., XXXX-XXXX-XXXX-XXXX)
  • Lemon Squeezy: Variable format (provided in email)

AI Services Configuration

Grok (xAI) - Primary AI Chat

Step 1: Create xAI Account
  1. Go to xAI Console
  2. Sign up or log in
  3. Complete account verification
Step 2: Generate API Key
  1. Navigate to API Keys section
  2. Click Create API Key
  3. Give it a name: Voralis Web
  4. Copy the API key
Step 3: Configure in .env.local
GROK_API_KEY=xai-your-api-key-here
GROK4_API_KEY=xai-your-api-key-here
GROK4_BASE_URL=https://api.x.ai/v1

OpenAI - DALL-E and GPT Models

Step 1: Create OpenAI Account
  1. Go to OpenAI Platform
  2. Sign up or log in
  3. Add payment method (required for API access)
Step 2: Generate API Key
  1. Go to API Keys section
  2. Click Create new secret key
  3. Give it a name: Voralis Web
  4. Copy the key immediately (starts with sk-)
Step 3: Configure in .env.local
OPENAI_API_KEY=sk-your-openai-api-key-here

Google Gemini

Step 1: Get Gemini API Key
  1. Go to Google AI Studio
  2. Sign in with your Google account
  3. Click Create API Key
  4. Select or create a Google Cloud project
  5. Copy the API key
Step 2: Configure in .env.local
GEMINI_API_KEY=your-gemini-api-key-here

ElevenLabs - Text-to-Speech

Step 1: Create ElevenLabs Account
  1. Go to ElevenLabs
  2. Sign up or log in
  3. Choose a subscription plan (free tier available)
Step 2: Get API Key
  1. Go to Profile → API Keys
  2. Click Generate API Key
  3. Give it a name: Voralis Web
  4. Copy the API key
Step 3: Configure in .env.local
ELEVENLABS_API_KEY=your-elevenlabs-api-key-here

Video Generation AI Services

Fal.ai (Required for Video Generation)

Step 1: Create Fal.ai Account
  1. Go to Fal.ai Dashboard
  2. Sign up with GitHub
  3. Add a payment method (required for API access)
Step 2: Generate API Key
  1. Go to API Keys section
  2. Click Create Key
  3. Copy the key secrets
Step 3: Configure in .env.local
FAL_KEY=your-fal-key-here

HeyGen (Avatar Video Generation)

Step 1: Create HeyGen Account
  1. Go to HeyGen
  2. Sign up or log in
  3. Subscribe to a plan that supports API access (Creator/Team)
Step 2: Get API Key
  1. Go to Settings → API
  2. Generate a new API Key
  3. Copy the key
Step 3: Configure in .env.local
HEYGEN_API_KEY=your-heygen-api-key

Payment Providers Setup

Stripe Setup

Step 1: Create Stripe Account
  1. Go to Stripe
  2. Sign up or log in
  3. Complete business verification
Step 2: Get API Keys
  1. Go to Developers → API Keys
  2. Copy Publishable key (starts with pk_)
  3. Click Reveal test key or Reveal live key for Secret key (starts with sk_)
Step 3: Configure Webhook
  1. Go to Developers → Webhooks
  2. Click Add endpoint
  3. Endpoint URL: https://your-domain.com/api/payments/stripe/webhook
  4. Select events:
    • checkout.session.completed
    • customer.subscription.updated
    • customer.subscription.deleted
    • invoice.payment_succeeded
    • invoice.payment_failed
  5. Copy the Webhook signing secret (starts with whsec_)
Step 4: Configure in .env.local
STRIPE_SECRET_KEY=sk_live_your-stripe-secret-key
STRIPE_PUBLISHABLE_KEY=pk_live_your-stripe-publishable-key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_your-stripe-publishable-key
STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret

PayPal Setup

Step 1: Create PayPal Business Account
  1. Go to PayPal Developer
  2. Sign up or log in
  3. Create a new app
Step 2: Get API Credentials
  1. Go to Dashboard → My Apps & Credentials
  2. Create a new app or use existing
  3. Copy Client ID and Secret
Step 3: Configure in .env.local
PAYPAL_CLIENT_ID=your-paypal-client-id
PAYPAL_CLIENT_SECRET=your-paypal-client-secret
PAYPAL_MODE=live  # or 'sandbox' for testing
NEXT_PUBLIC_PAYPAL_CLIENT_ID=your-paypal-client-id

Paystack Setup

Step 1: Create Paystack Account
  1. Go to Paystack
  2. Sign up for a business account
  3. Complete business verification
Step 2: Get API Keys
  1. Go to Settings → API Keys & Webhooks
  2. Copy Public key (starts with pk_)
  3. Copy Secret key (starts with sk_)
Step 3: Configure in .env.local
PAYSTACK_SECRET_KEY=sk_live_your-paystack-secret-key
PAYSTACK_PUBLIC_KEY=pk_live_your-paystack-public-key
NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY=pk_live_your-paystack-public-key

Adyen Setup

Step 1: Create Adyen Account
  1. Go to Adyen
  2. Sign up for a business account
  3. Complete business verification
Step 2: Get API Credentials
  1. Log in to Adyen Customer Area
  2. Go to Developers → API credentials
  3. Create or select a credential
  4. Copy API key
  5. Copy Client key
  6. Note your Merchant Account name
Step 3: Configure in .env.local
ADYEN_API_KEY=your-adyen-api-key
ADYEN_MERCHANT_ACCOUNT=your-merchant-account
ADYEN_CLIENT_KEY=your-adyen-client-key
NEXT_PUBLIC_ADYEN_CLIENT_KEY=your-adyen-client-key

Airwallex Setup

Step 1: Create Airwallex Account
  1. Go to Airwallex
  2. Sign up for a business account
  3. Complete business verification (KYB)
Step 2: Get API Credentials
  1. Log in to Airwallex Dashboard
  2. Go to Settings → Developer → API Keys
  3. Create a new API key
  4. Copy API Key
  5. Copy Client ID
Step 3: Configure Webhook
  1. In Airwallex Dashboard, go to Settings → Webhooks
  2. Add endpoint URL: https://your-domain.com/api/payments/airwallex/webhook
  3. Select relevant events (payment success, payment failed)
  4. Copy the Webhook Secret
Step 4: Configure in .env.local
AIRWALLEX_API_KEY=your-airwallex-api-key
AIRWALLEX_CLIENT_ID=your-airwallex-client-id
AIRWALLEX_WEBHOOK_SECRET=your-airwallex-webhook-secret

Storage Services Setup

Cloudflare R2 (Recommended)

Step 1: Create Cloudflare Account
  1. Go to Cloudflare
  2. Sign up or log in
  3. Add payment method (R2 requires paid plan)
Step 2: Create R2 Bucket
  1. Go to R2 → Create bucket
  2. Enter bucket name (e.g., voralis-media)
  3. Select location
  4. Click Create bucket
Step 3: Create API Token
  1. Go to Manage R2 API Tokens
  2. Click Create API Token
  3. Permissions: Object Read & Write
  4. Copy Access Key ID and Secret Access Key
Step 4: Get Public URL
  1. In your bucket settings, enable Public Access
  2. Copy the public URL (format: https://pub-xxx.r2.dev)
Step 5: Configure in .env.local
R2_ACCOUNT_ID=your-cloudflare-account-id
R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
R2_BUCKET_NAME=your-bucket-name
R2_PUBLIC_URL_PREFIX=https://pub-xxx.r2.dev

Additional Services (Email Configuration)

Configure at least one email service for sending transactional emails, notifications, and bulk emails. You can use multiple services for different purposes.

Resend (Recommended for Modern Stack)

Step 1: Create Resend Account
  1. Go to Resend
  2. Sign up with GitHub or Email
Step 2: Add and Verify Domain
  1. Go to Domains → Add Domain
  2. Enter your domain (e.g., yourdomain.com)
  3. Add the provided DNS records (DKIM, SPF, DMARC) to your DNS provider (Cloudflare, GoDaddy, etc.)
  4. Wait for verification (usually minutes)
Step 3: Generate API Key
  1. Go to API Keys
  2. Create a new API Key with "Sending" permission
  3. Copy the key (starts with re_)
Step 4: Configure in .env.local
RESEND_API_KEY=re_your_resend_api_key

SendGrid (Recommended for Bulk Emails)

Step 1: Create SendGrid Account
  1. Go to SendGrid
  2. Sign up for free account (includes 100 emails/day free)
  3. Verify your email address
Step 2: Create API Key
  1. Go to Settings → API Keys
  2. Click Create API Key
  3. Name: Voralis Web
  4. Permissions: Full Access or Mail Send
  5. Copy the API key (starts with SG.)
Step 3: Verify Sender
  1. Go to Settings → Sender Authentication
  2. Verify a single sender or authenticate entire domain
  3. Use verified email as SENDGRID_FROM_EMAIL
Step 4: Configure in .env.local
SENDGRID_API_KEY=SG.your-sendgrid-api-key
SENDGRID_FROM_EMAIL=noreply@yourdomain.com

AWS SES (Alternative for Bulk Emails)

Step 1: Create AWS Account
  1. Go to AWS
  2. Sign up for an AWS account
  3. Complete payment setup (SES has a free tier)
Step 2: Set Up SES
  1. Go to AWS Console → SES (Simple Email Service)
  2. Select your preferred region (e.g., us-east-1)
  3. Verify your email address or domain
  4. Request production access (required to send to non-verified emails)
Step 3: Create IAM User for SES
  1. Go to IAM → Users → Add users
  2. Username: voralis-ses-user
  3. Access type: Programmatic access
  4. Attach policy: AmazonSESFullAccess
  5. Copy Access Key ID and Secret Access Key
Step 4: Configure in .env.local
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_aws_access_key_id
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key

Note: AWS SES starts in sandbox mode. You can only send to verified email addresses until you request production access.

Mailtrap (Testing & Production)

Step 1: Create Mailtrap Account
  1. Go to Mailtrap
  2. Sign up for free account
  3. Verify your email
Step 2: Get API Token
  1. Go to Settings → API Tokens
  2. Click Create Token
  3. Copy the API token
Step 3: Set Up Inbox (Sandbox Mode)
  1. Go to Email Testing → Inboxes
  2. Select or create an inbox
  3. Note the Inbox ID (shown in URL or inbox settings)
  4. Get SMTP credentials from inbox settings
Step 4: Configure in .env.local
# Mailtrap Configuration
MAILTRAP_USER="api"
MAILTRAP_PASS=your-api-token-key
MAILTRAP_API_KEY=your-api-token-key
MAILTRAP_USE_SANDBOX=true       # true for testing, false for production
MAILTRAP_INBOX_ID=123456        # Only needed for sandbox mode

Sandbox vs Production:

  • Sandbox (MAILTRAP_USE_SANDBOX=true): Emails are caught by Mailtrap, not delivered to real recipients. Perfect for testing.
  • Production (MAILTRAP_USE_SANDBOX=false): Emails are actually delivered. Requires verified sending domain.

Nodemailer (SMTP - Any Email Provider)

Overview

Nodemailer allows you to send emails using any SMTP server. This is useful for custom email hosting or using your existing email provider.

Option 1: Gmail SMTP
  1. Go to your Google Account
  2. Enable 2-Step Verification
  3. Go to Security → App passwords
  4. Select app: Mail, Select device: Other
  5. Name it: Voralis Web
  6. Copy the generated 16-character password
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-16-char-app-password
Option 2: Hostinger SMTP
  1. Log in to your Hostinger account
  2. Go to Email Accounts
  3. Create or use existing email account
  4. Get SMTP settings from Hostinger
NODEMAILER_HOST=smtp.hostinger.com
NODEMAILER_PORT=587
NODEMAILER_SECURE=false        # true for port 465, false for 587
NODEMAILER_USER=support@yourdomain.com
NODEMAILER_PASS=your-email-password
Option 3: Other SMTP Providers

You can use any SMTP server. Common providers:

  • Outlook/Office365: smtp.office365.com (Port 587)
  • Yahoo: smtp.mail.yahoo.com (Port 587)
  • Zoho: smtp.zoho.com (Port 587)
  • Custom hosting: Check your hosting provider's documentation

Port Information:

  • Port 587: TLS/STARTTLS (recommended, set NODEMAILER_SECURE=false)
  • Port 465: SSL (set NODEMAILER_SECURE=true)
  • Port 25: Usually blocked by hosting providers

📊 Which Email Service Should You Use?

For Development/Testing:
  • ✅ Mailtrap (Sandbox) - Best for testing without sending real emails
  • ✅ Nodemailer (Gmail) - Quick setup for small-scale testing
For Production (Low Volume < 1000 emails/day):
  • ✅ SendGrid Free Tier - 100 emails/day free
  • ✅ Nodemailer (Custom SMTP) - If you have email hosting
For Production (High Volume):
  • ✅ SendGrid - Reliable, good deliverability, easy setup
  • ✅ AWS SES - Very cost-effective for high volume ($0.10 per 1000 emails)
  • ✅ Mailtrap (Production) - Testing tools + production sending

💡 Pro Tip: You can configure multiple email services and use different ones for different purposes:

  • Transactional emails (password resets, verifications): Nodemailer or AWS SES
  • Marketing/Bulk emails: SendGrid or AWS SES
  • Testing/Development: Mailtrap Sandbox

Feature: Content Templates System

The Content Templates System allows users to generate content using 72+ pre-built templates across 8 categories (Blog, Email, Social Media, etc.) using OpenAI or Grok.

Step 1: Database Migrations (Required)

Run the following SQL files in your NeonDB SQL Editor to create the necessary tables:

  1. voralis-web/migrations/create_content_templates.sql
  2. voralis-web/migrations/insert_remaining_templates.sql

Step 2: Configuration

Ensure these variables are in your .env.local:

# AI Service (Choose one or both)
OPENAI_API_KEY=sk-your-key
GROK_API_KEY=xai-your-key

# Optional: Use Grok for content generation
USE_GROK_FOR_CONTENT=false

Feature: URL to Video Ads

Automatically convert product URLs (Amazon, Shopify, etc.) into video ads using HeyGen avatars and AI script generation.

Step 1: Background Worker

This feature requires a background worker to process long-running video generation tasks. In development, run:

npm run worker

Production: Deploy scripts/worker.ts as a separate worker service (e.g., on Render or Heroku) to ensure continuous processing.

Step 2: Queue System (Redis)

The worker uses Upstash Redis (or any Redis instance). Ensure UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are set.

Step 3: Required API Keys

# HeyGen (Video Generation)
HEYGEN_API_KEY=your-heygen-api-key

# Notifications
RESEND_API_KEY=re_your_resend_key
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY... (with proper escaping)"
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_CLIENT_EMAIL=your-client-email

# Storage (Video Hosting)
R2_ACCOUNT_ID=...
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_BUCKET_NAME=...

Feature: AI Presentation Maker

Create multi-slide presentations from a simple topic description using OpenAI.

Configuration

This feature primarily uses the standard OpenAI configuration. No additional specialized keys are required beyond what is listed in the AI Services section.

# Required for presentation generation
OPENAI_API_KEY=sk-your-openai-key

Database Schema

Ensure you have run the main database schema migration (database-schema.sql), which includes the presentations and presentation_slides tables.

Final Configuration (Voralis Web)

Step 1: Generate Security Secrets

# Generate JWT Secret
openssl rand -base64 32

# Generate Admin Secret
openssl rand -base64 32

Add to .env.local:

JWT_SECRET=your-generated-jwt-secret
ADMIN_SECRET_KEY=your-generated-admin-secret

Step 2: Set Base URL

# Development
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Production (update after deployment)
NEXT_PUBLIC_BASE_URL=https://your-domain.com

Step 3: Configure License Settings

# Brain Server URL (provided by your vendor/developer)
NEXT_PUBLIC_BRAIN_SERVER_URL=https://your-brain-server.vercel.app

# License Key (provided by your vendor/developer)
NEXT_PUBLIC_LICENSE_KEY=your-license-key-here

Step 4: Test Configuration

# Start development server
npm run dev

# Or
yarn dev

Visit http://localhost:3000 and check:

  • ✅ License setup wizard appears if no license
  • ✅ Database connection works
  • ✅ No console errors

Troubleshooting (Voralis Web)

1. Database Connection Failed

Error: Database not configured - missing NEON_DATABASE_URL

Solution:

  • Verify NEON_DATABASE_URL is set correctly
  • Check connection string format
  • Ensure database schema is initialized
  • Test connection in Neon Console

2. License Verification Failed

Error: License verification failed

Solution:

  • Verify NEXT_PUBLIC_BRAIN_SERVER_URL is correct (contact your vendor/developer)
  • Verify NEXT_PUBLIC_LICENSE_KEY is correct
  • Check license key format matches your purchase
  • Ensure you're using the license key from your purchase receipt/email
  • Contact support if the issue persists

3. API Key Errors

Error: API key not configured

Solution:

  • Verify API key is in .env.local (not .env)
  • Check for typos or extra spaces
  • Restart development server after adding keys
  • Verify API key is active in provider dashboard

Part 2: Voralis App Installation

Prerequisites (Voralis App)

  • Node.js 18+ installed
  • npm or yarn
  • Git (if using version control)
  • Expo CLI (optional but recommended):
    npm install -g expo-cli
  • EAS CLI (for cloud builds):
    npm install -g eas-cli
  • Android:
    • Android Studio with Android SDK and at least one Android Virtual Device (AVD), or a physical Android device with USB debugging enabled.
  • iOS (on macOS only):
    • Xcode installed
    • iOS Simulator or physical device with Apple developer account (for builds).

Project Structure (Voralis App)

Key files and folders:

  • package.json – scripts and dependencies
  • app.json – Expo app configuration (name, icons, bundle IDs, etc.)
  • eas.json – EAS build profiles (development/production/app1/app2)
  • App.tsx – main app entry
  • src/ – app source (screens, components, services, contexts, etc.)

Install Dependencies (Voralis App)

From the voralis-app directory:

cd voralis-app
npm install
# or
yarn install

Environment Variables (Voralis App)

Expo uses EXPO_PUBLIC_ prefix for variables that should be available on the client.

Create .env (or .env.local)

In voralis-app/:

touch .env

Example content:

# License
EXPO_PUBLIC_LICENSE_KEY=your-mobile-license-key-here

# Brain Server URL (provided by your vendor/developer)
EXPO_PUBLIC_BRAIN_SERVER_URL=https://your-brain-server.vercel.app

# API base URLs (for calling voralis-web backend)
EXPO_PUBLIC_API_BASE_URL=https://www.voralisai.com
EXPO_PUBLIC_API_URL=https://www.voralisai.com

Note: For EAS builds, you typically configure env vars via EAS secrets or eas.json profiles, not by committing .env to git.

Where They Are Used

  • EXPO_PUBLIC_LICENSE_KEY - Used in HomeScreen.tsx, LoginScreen.tsx, RegisterScreen.tsx, ChatScreen.tsx to pass a default license key to useLicense.
  • EXPO_PUBLIC_BRAIN_SERVER_URL - Used in src/services/licenseVerification.ts for license verification.
  • EXPO_PUBLIC_API_URL - Used in src/api/speech-to-text.ts as base URL for speech-to-text API.

Running the App (Development)

From voralis-app/:

Start Metro Bundler

npm start
# or
expo start

You will see a QR code and options for Android, iOS, and Web.

Run on Android

With an emulator:

npm run android
# or
expo run:android

With a physical device:

  • Install Expo Go from Play Store.
  • Ensure device and dev machine are on same network.
  • Scan QR from the terminal (or web UI opened by expo start).

Run on iOS (macOS only)

With Simulator:

npm run ios
# or
expo run:ios

With physical device:

Requires Apple developer account and proper provisioning via Xcode / EAS.

Run on Web

npm run web

app.json Configuration

File: voralis-app/app.json

Basic Info

{
  "expo": {
    "name": "Voralis AI",
    "slug": "voralis-ai",
    "version": "1.0.0",
    "description": "Advanced AI-powered assistant...",
    "userInterfaceStyle": "automatic",
    "sdkVersion": "54.0.0",
    ...
  }
}

Icons & Splash

"icon": "./assets/logo.png",
"splash": {
  "image": "./assets/logo.png",
  "resizeMode": "contain",
  "backgroundColor": "#ffffff"
}

To customize branding:

  • Replace ./assets/logo.png, ic_launcher.png, and adaptive-icon.png with your assets.
  • Update backgroundColor to match your theme.

Platforms

"platforms": ["ios", "android", "web"]

Extra Config

"extra": {
  "googleClientId": "your-google-client-id",
  "eas": {
    "projectId": "20acf715-d397-4002-ab97-233acd09fea4"
  },
  "apiUrl": "https://www.voralisai.com"
}

You can access extra via expo-constants in code if needed.

iOS

"ios": {
  "icon": "./assets/ic_launcher.png",
  "bundleIdentifier": "com.yourcompany.yourapp"
}

Change bundleIdentifier to your own reverse-DNS string before App Store submission.

Android

"android": {
  "package": "com.yourcompany.yourapp",
  "permissions": [
    "android.permission.READ_EXTERNAL_STORAGE",
    "android.permission.WRITE_EXTERNAL_STORAGE",
    "android.permission.INTERNET",
    ...
  ]
}

Change package to your own (must be unique on Play Store). Adjust permissions if you add/remove features.

eas.json Configuration

File: voralis-app/eas.json

This file defines multiple build profiles:

  • app1-development, app2-development – internal dev builds for two app variants.
  • app1-production, app2-production – production builds per variant.
  • development, preview, release, production – generic profiles.

Example Profile

{
  "build": {
    "app1-development": {
      "developmentClient": true,
      "environment": "development",
      "distribution": "internal",
      "android": {
        "buildType": "apk",
        "gradleCommand": ":app:assembleDebug"
      },
      "ios": {
        "buildConfiguration": "Debug",
        "image": "latest"
      },
      "env": {
        "NODE_ENV": "development",
        "APP": "app1"
      }
    },
    ...
  }
}

Using Build Profiles

From voralis-app/:

# App 1 production build (Android)
npx eas build --platform android --profile app1-production

# App 1 production build (iOS)
npx eas build --platform ios --profile app1-production

# Generic production build
npx eas build --platform android --profile production

The APP env var is used by scripts/set-project-id.js to swap project IDs or configs between variants.

Adding Environment Variables per Profile

You can add additional env keys under each profile:

"env": {
  "NODE_ENV": "production",
  "EXPO_PUBLIC_API_BASE_URL": "https://api.yourdomain.com",
}

These are injected at build time on EAS.

Android Configuration (Native)

If you eject or use expo run:android, Android native project is under android/.

Key files:

  • android/app/build.gradle – app-level Gradle config
  • android/app/src/main/AndroidManifest.xml – permissions and intents
  • android/app/src/main/res/ – icons, adaptive icons, splash images

Most configuration can be handled via app.json + EAS, but for advanced changes (custom permissions, deep links) you may need to edit these files.

iOS Configuration (Native)

If you run expo run:ios or build with EAS, the iOS project lives under ios/.

Key files:

  • ios/VoralisAI/Info.plist – app metadata, permissions (camera, microphone, photo library)
  • ios/VoralisAI/AppDelegate.swift – app entry
  • ios/VoralisAI/Images.xcassets/ – icons, splash images
  • ios/VoralisAI.entitlements – capabilities (Push, iCloud, etc.)

You generally:

  • Use app.json for bundle ID and display name.
  • Use EAS for signing and distribution.
  • Only modify native files for special cases (e.g., custom URL schemes).

License System (Voralis App)

The mobile app uses the same unified licensing system as the web:

  • EXPO_PUBLIC_LICENSE_KEY (or per-user key) is used.
  • License Setup Wizard equivalent exists on web; in mobile, screens like HomeScreen, LoginScreen, RegisterScreen, and ChatScreen check isLicensed and block access until license is valid.

As an integrator:

  • You only need to provide license keys.
  • Do not modify license verification logic.

Typical Setup Workflow Summary

  1. Clone voralis-app or download and install dependencies.
  2. Create .env with:
    • license key
    • Brain server URL
    • API base URLs
    • OpenAI / other model keys (optional)
    • R2 storage keys (if used)
  3. Adjust app.json:
    • App name, slug, icons, splash
    • iOS bundle ID and Android package name
  4. (Optional) Tweak eas.json profiles and env vars.
  5. Run npm start and test on device/emulator.
  6. Use eas build for production Android/iOS binaries.

Support

For additional help:

  • 📧 Email: support@somatechglobalventures.com

License

This installation guide is part of the Voralis project. All rights reserved.

Last Updated: January 2026
Version: 1.0.0