Environment Variables

Overview

Voxora uses environment variables to configure both the web application and API server. This guide covers all available variables and their purposes.

API Server Variables

Located in apps/api/.env

Server Configuration

PORT

number

default:"3002"

Port number for the API server

NODE_ENV

string

default:"development"

Environment mode: development, staging, or production

LOG_LEVEL

string

default:"info"

Logging level: error, warn, info, debug, or verbose

Database

MONGODB_URI

string

required

MongoDB connection stringDevelopment:

mongodb://admin:password@localhost:27017/voxora?authSource=admin

Production:

mongodb+srv://user:pass@cluster.mongodb.net/voxora

MONGODB_MAX_POOL_SIZE

number

default:"10"

Maximum number of connections in the MongoDB connection pool

Redis Cache

REDIS_HOST

string

default:"localhost"

Redis server hostname

REDIS_PORT

number

default:"6379"

Redis server port

REDIS_PASSWORD

string

Redis authentication password (optional for local dev)

REDIS_DB

number

default:"0"

Redis database number (0-15)

Authentication

JWT_SECRET

string

required

Secret key for signing JWT tokens

Never commit this to version control! Use a strong, random value in production.

Generate a secure secret:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

JWT_EXPIRES_IN

string

default:"7d"

JWT token expiration time (e.g., 1h, 7d, 30d)

JWT_REFRESH_EXPIRES_IN

string

default:"30d"

Refresh token expiration time

CORS

CORS_ORIGIN

string

required

Allowed origins for CORSSingle origin:

http://localhost:3000

Multiple origins:

http://localhost:3000,https://app.voxora.cloud

All origins (dev only):

Email (SMTP)

SMTP_HOST

string

required

SMTP server hostname

Development: localhost (MailHog)
Production: Your SMTP provider

SMTP_PORT

number

required

SMTP server port

MailHog: 1025
Gmail: 587
SendGrid: 587

SMTP_USER

string

SMTP authentication username

SMTP_PASS

string

SMTP authentication password

SMTP_SECURE

boolean

default:"false"

Use TLS/SSL for SMTP connection

EMAIL_FROM

string

default:"noreply@voxora.cloud"

Default sender email address

File Uploads

UPLOAD_DIR

string

default:"./uploads"

Directory for storing uploaded files

MAX_FILE_SIZE

number

default:"10485760"

Maximum file size in bytes (default: 10MB)

ALLOWED_FILE_TYPES

string

default:"image/jpeg,image/png,image/gif,application/pdf"

Comma-separated list of allowed MIME types

Rate Limiting

RATE_LIMIT_WINDOW_MS

number

default:"900000"

Rate limit window in milliseconds (default: 15 minutes)

RATE_LIMIT_MAX_REQUESTS

number

default:"100"

Maximum requests per window

CDN URL for serving widget assets (optional)

Comma-separated list of domains allowed to embed the widget

example.com,*.example.com,localhost:*

Web Application Variables

Located in apps/web/.env

API Configuration

NEXT_PUBLIC_API_URL

string

required

Base URL for API requestsDevelopment:

http://localhost:3002

Production:

https://api.voxora.cloud

NEXT_PUBLIC_SOCKET_URL

string

required

WebSocket server URL (usually same as API URL)

URL for the embeddable chat widget

http://localhost:3002/widget

Features

NEXT_PUBLIC_ENABLE_ANALYTICS

boolean

default:"false"

Enable analytics tracking

NEXT_PUBLIC_ENABLE_NOTIFICATIONS

boolean

default:"true"

Enable browser notifications

NEXT_PUBLIC_MAX_FILE_SIZE

number

default:"10485760"

Maximum file upload size (must match API setting)

Analytics

NEXT_PUBLIC_GA_MEASUREMENT_ID

string

Google Analytics measurement ID

NEXT_PUBLIC_SENTRY_DSN

string

Sentry DSN for error tracking

Docker Environment

Variables in docker/docker-compose.dev.yml

services:
  mongodb:
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password
      MONGO_INITDB_DATABASE: voxora
  
  redis:
    # No authentication in dev mode
  
  mongo-express:
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password
      ME_CONFIG_MONGODB_URL: mongodb://admin:password@mongodb:27017/
      ME_CONFIG_BASICAUTH_USERNAME: admin
      ME_CONFIG_BASICAUTH_PASSWORD: pass

Environment Templates

Development Template

# Server
PORT=3002
NODE_ENV=development
LOG_LEVEL=debug

# Database
MONGODB_URI=mongodb://admin:password@localhost:27017/voxora?authSource=admin

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# Auth
JWT_SECRET=dev-secret-change-in-production
JWT_EXPIRES_IN=7d

# CORS
CORS_ORIGIN=http://localhost:3000

# Email (MailHog)
SMTP_HOST=localhost
SMTP_PORT=1025
EMAIL_FROM=noreply@voxora.local

Production Template

# Server
PORT=3002
NODE_ENV=production
LOG_LEVEL=info

# Database
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/voxora

# Redis
REDIS_HOST=your-redis.cloud
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password

# Auth
JWT_SECRET=your-super-secret-key-here
JWT_EXPIRES_IN=7d

# CORS
CORS_ORIGIN=https://app.voxora.cloud

# Email
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=your-sendgrid-api-key
SMTP_SECURE=true
EMAIL_FROM=support@voxora.cloud

Best Practices

Never Commit Secrets

Add .env files to .gitignore

Use Templates

Commit .env.example as a reference

Validate on Startup

Check required variables exist

Document Changes

Update docs when adding variables

Validation Example

apps/api/src/config/env.js

const required = [
  'MONGODB_URI',
  'JWT_SECRET',
  'CORS_ORIGIN'
];

required.forEach(key => {
  if (!process.env[key]) {
    throw new Error(`Missing required environment variable: ${key}`);
  }
});

Loading Environment Variables

Next.js

Next.js automatically loads .env* files:

.env - All environments
.env.local - Local overrides (not committed)
.env.development - Development only
.env.production - Production only

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

Node.js (API)

Use dotenv package:

import dotenv from 'dotenv';

dotenv.config();

const config = {
  port: process.env.PORT || 3002,
  mongoUri: process.env.MONGODB_URI,
  jwtSecret: process.env.JWT_SECRET
};

Security Considerations

Production Security Checklist:

✓ Use strong, random JWT secrets
✓ Enable HTTPS/TLS everywhere
✓ Restrict CORS to specific domains
✓ Use secure SMTP with authentication
✓ Store secrets in a secure vault (not .env files)
✓ Rotate secrets regularly
✓ Use environment-specific values

Next Steps

Development Setup

Complete development guide

Docker Services

Managing local services

Deployment

Deploy to production

Security

Security best practices

Getting Started

Core Concepts

Development

Deployment

Overview

API Server Variables

Server Configuration

Database

Redis Cache

Authentication

CORS

Email (SMTP)

File Uploads

Rate Limiting

Widget

Web Application Variables

API Configuration

Widget

Features

Analytics

Docker Environment

Environment Templates

Development Template

Production Template

Best Practices

Never Commit Secrets

Use Templates

Validate on Startup

Document Changes

Validation Example

Loading Environment Variables

Next.js

Node.js (API)

Security Considerations

Next Steps

Development Setup

Docker Services

Deployment

Security

Getting Started

Core Concepts

Development

Deployment

​Overview

​API Server Variables

​Server Configuration

​Database

​Redis Cache

​Authentication

​CORS

​Email (SMTP)

​File Uploads

​Rate Limiting

​Widget

​Web Application Variables

​API Configuration

​Widget

​Features

​Analytics

​Docker Environment

​Environment Templates

​Development Template

​Production Template

​Best Practices

Never Commit Secrets

Use Templates

Validate on Startup

Document Changes

​Validation Example

​Loading Environment Variables

​Next.js

​Node.js (API)

​Security Considerations

​Next Steps

Development Setup

Docker Services

Deployment

Security

Overview

API Server Variables

Server Configuration

Database

Redis Cache

Authentication

CORS

Email (SMTP)

File Uploads

Rate Limiting

Widget

Web Application Variables

API Configuration

Widget

Features

Analytics

Docker Environment

Environment Templates

Development Template

Production Template

Best Practices

Validation Example

Loading Environment Variables

Next.js

Node.js (API)

Security Considerations

Next Steps