Skip to main content

​
System Requirements

Operating System

macOS, Windows, or Linux

Node.js

Version 18 or higher

npm

Version 10 or higher

Docker

Docker Desktop for local services

​
Step-by-Step Installation

​
1. Fork the Repository

Navigate to https://github.com/voxora-cloud/voxora and click the “Fork” button to create your own copy of the repository.

​
2. Clone Your Fork

git clone https://github.com/<your-username>/voxora.git
cd voxora

​
3. Install Node Dependencies

Install all dependencies for the monorepo: 
npm install
This will install dependencies for:
  • The root workspace
  • apps/web (Next.js frontend)
  • apps/api (Express backend)
  • All shared packages

​
4. Configure Environment Variables

​
API Environment Variables

Navigate to apps/api and create your .env file: 
cd apps/api
cp .env.development .env
Key environment variables for the API:
.env
# Server Configuration
PORT=3002
NODE_ENV=development

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

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT Secret
JWT_SECRET=your-secret-key-here

# CORS Origin
CORS_ORIGIN=http://localhost:3000

# Email Configuration (MailHog for local dev)
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USER=
SMTP_PASS=
EMAIL_FROM=noreply@voxora.cloud

​
Web Environment Variables

Navigate to apps/web and create your .env file: 
cd apps/web
cp .env.development .env
Key environment variables for the web app:
.env
# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3002
NEXT_PUBLIC_SOCKET_URL=http://localhost:3002

# Widget Configuration
NEXT_PUBLIC_WIDGET_URL=http://localhost:3002/widget

​
5. Set Up Docker Services

Voxora uses Docker for local development services. The following services are configured:
  • MongoDB: Database for storing users, conversations, and messages
  • Redis: Caching and session management
  • Mongo Express: Web-based MongoDB admin interface
  • MailHog: Local email testing server
Start Docker services: 
npm run docker:start
This command runs docker-compose from the docker/docker-compose.dev.yml file.

​
6. Verify Docker Services

Check that all services are running: 
docker ps
You should see containers for:
  • MongoDB (port 27017)
  • Redis (port 6379)
  • Mongo Express (port 8081)
  • MailHog (ports 1025, 8025)

​
7. Start Development Servers

Start both web and API development servers: 
npm run dev
Or start everything (Docker + dev servers) at once: 
npm run dev:full

​
Verification

​
Check Web App

Navigate to http://localhost:3000 in your browser. You should see the Voxora web interface.

​
Check API Server

Test the API health endpoint: 
curl http://localhost:3002/
You should receive a successful response.

​
Check MongoDB

Access Mongo Express at http://localhost:8081 to view your databases. Default credentials:
  • Username: admin
  • Password: pass

​
Check Email Testing

Access MailHog at http://localhost:8025 to view emails sent by the application during development. For the best development experience, install these VS Code extensions:

Better Comments

aaron-bond.better-comments

Prettier

esbenp.prettier-vscode

ESLint

dbaeumer.vscode-eslint

Tailwind CSS IntelliSense

bradlc.vscode-tailwindcss

​
Troubleshooting

Try clearing npm cache and reinstalling:
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
Ensure Docker Desktop is running and you have sufficient system resources. Check Docker logs:
docker-compose -f docker/docker-compose.dev.yml logs
If you have services running on the default ports, either:
  1. Stop the conflicting services
  2. Modify ports in docker/docker-compose.dev.yml and .env files
Verify MongoDB is running:
docker ps | grep mongo
Check connection string in apps/api/.env matches Docker configuration.

​
Next Steps

Development Setup

Learn about the development workflow

Architecture

Understand Voxora’s architecture

API Reference

Explore the API

Widget Integration

Add the widget to your site