Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
Required for running MongoDB, Redis, and other services locally. Download Docker Desktop
Voxora requires Node.js version 18 or higher. Download Node.js
Usually comes with Node.js installation. Verify with: npm --version

​
Step 1: Fork and Clone

Fork the repository to your GitHub account: 
# Fork the repository on GitHub first, then clone your fork
git clone <your-fork-url>
cd voxora

​
Step 2: Install Dependencies

Install all dependencies for the monorepo: 
npm install

​
Step 3: Set Up Environment Variables

Copy the development environment files for both apps: 
cd apps/api
cp .env.development .env
The default environment files are pre-configured for local development. You can modify them as needed for your setup.

​
Step 4: Start Everything

Launch Docker services and development servers: 
npm run dev:full
This command will:
  1. Start Redis, MongoDB, and Mongo Express in Docker
  2. Run the web and API dev servers via Turborepo
  3. Set up MailHog for local email testing

​
Step 5: Access Your Applications

Web App

http://localhost:3000

API Server

http://localhost:3002

Mongo Express

http://localhost:8081

MailHog UI

http://localhost:8025

​
API Endpoints

  • REST API: http://localhost:3002/api/v1
  • Health Check: http://localhost:3002/
  • Widget HTML: http://localhost:3002/widget
  • Widget Loader: http://localhost:3002/widget-loader.js

​
Email Testing

  • MailHog SMTP: localhost:1025 (for sending emails)
  • MailHog Web UI: http://localhost:8025 (to view emails)

​
Next Steps

Architecture Overview

Learn about Voxora’s architecture

Development Guide

Detailed development setup

Widget Integration

Add the chat widget to your site

API Reference

Explore the API endpoints

​
Common Issues

If ports 3000, 3002, 8081, or 8025 are already in use, either:
  • Stop conflicting services
  • Change ports in docker/docker-compose.dev.yml and environment files
Ensure Docker Desktop is running before executing npm run dev:full. You can verify with: docker ps
Credentials are seeded from .env files. Check:
  • apps/api/.env.*
  • docker/docker-compose.dev.yml

​
Stopping Services

To stop Docker services: 
npm run docker:stop
To stop development servers, press Ctrl+C in the terminal where they’re running.