Skip to content

SETUP

Jump to bottom
AutoBotSolutions edited this page Apr 29, 2026 · 1 revision

NEXUS System Setup Guide

Complete setup instructions for NEXUS Support System.

Table of Contents

System Requirements

Minimum Requirements

  • CPU: 1 core
  • RAM: 2GB
  • Storage: 20GB
  • OS: Linux, macOS, or Windows

Software Requirements

  • Node.js: Version 14.0.0 or higher
  • npm: Version 6.0.0 or higher
  • MongoDB: Version 4.4 or higher
  • Git: Version 2.0 or higher (optional)

Recommended Requirements

  • CPU: 2+ cores
  • RAM: 4GB+
  • Storage: 50GB+
  • MongoDB: Version 6.0+

Installation

Step 1: Obtain the Source Code

Option A: Clone from Git Repository

git clone <repository-url>
cd nexus

Option B: Download Release

  1. Download the latest release from GitHub
  2. Extract the archive
  3. Navigate to the extracted directory

Step 2: Install Node.js Dependencies

npm install

This installs all required packages:

  • express, mongoose, dotenv, cors, axios
  • helmet, express-rate-limit
  • jsonwebtoken, bcryptjs
  • nodemon (development)

Step 3: Verify Installation

npm list

Ensure all dependencies are installed without errors.

Configuration

Step 1: Create Environment File

cp .env.example .env

Step 2: Configure Basic Settings

Edit .env with your configuration:

# Server
PORT=3000
NODE_ENV=development

# CORS Configuration (optional - restrict to specific domains in production)
CORS_ORIGIN=*

# Database
MONGODB_URI=mongodb://localhost:27017/nexus-support

# MongoDB SSL/TLS Configuration (optional - for production)
MONGODB_SSL=false
MONGODB_TLS=false
MONGODB_TLS_ALLOW_INVALID_CERTS=false
MONGODB_TLS_CA_FILE=
MONGODB_TLS_CERT_KEY_FILE=
MONGODB_TLS_CERT_KEY_PASSWORD=

# JWT Secret (required)
JWT_SECRET=<generate-secure-random-string>

Step 3: Generate Secure Secrets

Generate JWT Secret:

# Linux/macOS
openssl rand -hex 64

# Windows PowerShell
-join ((48..57) + (65..90) + (97..122) | Get-Random -Count 64 | % {[char]$_})

Step 4: Configure Optional Features

GitHub Integration (optional):

GITHUB_WEBHOOK_SECRET=<generate-secure-random-string>
GITHUB_TOKEN=<github-personal-access-token>
GITHUB_REPO_OWNER=<your-github-username>
GITHUB_REPO_NAME=<your-repository-name>

Database Setup

Option A: Local MongoDB

Install MongoDB

Ubuntu/Debian:

wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
sudo apt update
sudo apt install -y mongodb-org

macOS:

brew tap mongodb/brew
brew install mongodb-community

Windows: Download from mongodb.com

Start MongoDB

# Linux/macOS
mongod --dbpath /path/to/data/directory

# Or use service
sudo systemctl start mongod  # Linux
brew services start mongodb-community  # macOS

Verify MongoDB

mongo
> show dbs

Option B: MongoDB Atlas (Cloud)

  1. Create account at mongodb.com/cloud/atlas
  2. Create a free cluster (M0 tier)
  3. Create database user
  4. Whitelist IP address (0.0.0.0/0 for all)
  5. Get connection string
  6. Update .env:
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/nexus-support?retryWrites=true&w=majority

Option C: Docker MongoDB

docker run -d -p 27017:27017 --name mongodb mongo:6.0

Update .env:

MONGODB_URI=mongodb://localhost:27017/githhbb-support

GitHub Integration Setup

Step 1: Create GitHub Personal Access Token

  1. Go to GitHub Settings → Developer settings → Personal access tokens
  2. Click "Generate new token" (classic)
  3. Select scopes:
    • repo - Full control of private repositories
    • issues - Read and write issues
  4. Generate and copy the token
  5. Add to .env as GITHUB_TOKEN

Step 2: Generate Webhook Secret

# Linux/macOS
openssl rand -hex 32

# Windows PowerShell
-join ((48..57) + (65..90) + (97..122) | Get-Random -Count 32 | % {[char]$_})

Add to .env as GITHUB_WEBHOOK_SECRET

Step 3: Configure Repository Details

GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=your-repository-name

Step 4: Set Up GitHub Webhook

  1. Go to your GitHub repository
  2. Settings → Webhooks → Add webhook
  3. Configure:
    • Payload URL: https://your-domain.com/api/github/webhook
    • For local testing, use ngrok: https://your-ngrok-url.ngrok.io/api/github/webhook
    • Content type: application/json
    • Secret: Your GITHUB_WEBHOOK_SECRET
    • Events: "Issues" and "Issue comments"
  4. Click "Add webhook"

Step 5: Test Webhook (Optional)

For local testing with ngrok:

# Install ngrok
brew install ngrok  # macOS
snap install ngrok  # Linux

# Start ngrok
ngrok http 3000

# Use the ngrok URL for GitHub webhook

Running the Application

Development Mode

Auto-restart on file changes:

npm run dev

Production Mode

npm start

Or with environment variable:

NODE_ENV=production npm start

Using PM2 (Recommended for Production)

# Install PM2
npm install -g pm2

# Start application
pm2 start server.js --name githhb-uupportb-support

# View logs
pm2 logs githhb-uupportb-support

# Restart
pm2 restart nexus

# Stop
pm2 stop nexus

# Configure to start on boot
pm2 startup
pm2 save

Verification

1. Check Server Status

curl http://localhost:3000/api/health

Expected response:

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

2. Access Web Interface

Open browser: http://localhost:3000

3. Create Test Ticket

Via web interface or API:

curl -X POST http://localhost:3000/api/tickets \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Setup Test",
    "description": "Testing the system",
    "createdBy": "Test User",
    "createdByEmail": "test@example.com"
  }'

4. Verify Database

mongo
> use nexus-support
> show collections
> db.tickets.find()

5. Test GitHub Integration (if configured)

Create a GitHub issue and verify it creates a ticket, or sync a ticket to GitHub.

Troubleshooting

MongoDB Connection Issues

Error: "MongoNetworkError"

Solutions:

  • Verify MongoDB is running
  • Check MONGODB_URI in .env
  • Ensure MongoDB port (27017) is accessible
  • Check firewall settings

Port Already in Use

Error: "EADDRINUSE: address already in use :::3000"

Solutions:

  • Change PORT in .env
  • Kill process using port 3000: 
    lsof -i :3000
kill -9 <PID>

Dependencies Not Installing

Solutions:

  • Clear npm cache: npm cache clean --force
  • Delete node_modules and package-lock.json
  • Run npm install again
  • Try with different Node.js version

GitHub Webhook Not Working

Solutions:

  • Verify webhook URL is publicly accessible
  • Use ngrok for local testing
  • Check webhook secret matches
  • Review GitHub webhook delivery logs
  • Check server logs

Authentication Issues

Solutions:

  • Verify JWT_SECRET is set in .env
  • Check token format: Bearer <token>
  • Verify token hasn't expired (7 days)

For more issues, see Troubleshooting Guide.

Security Considerations

Production Deployment

  1. Change all secrets from default values
  2. Use strong, random secrets for JWT and webhook
  3. Enable HTTPS with SSL/TLS
  4. Restrict CORS to specific origins
  5. Enable rate limiting (already configured)
  6. Use environment-specific configs
  7. Never commit .env file
  8. Regular security updates for dependencies

Environment Variables

Never commit .env to version control. Use .env.example as template.

Database Security

  • Enable MongoDB authentication
  • Use strong passwords
  • Restrict network access
  • Use TLS/SSL for connections
  • Regular backups

Performance Tuning

Database Indexing

Add indexes for frequently queried fields:

// In models/Ticket.js
ticketSchema.index({ ticketId: 1 });
ticketSchema.index({ status: 1 });
ticketSchema.index({ priority: 1 });
ticketSchema.index({ createdAt: -1 });

Connection Pooling

Configure MongoDB connection pool:

mongoose.connect(uri, {
  maxPoolSize: 10,
  minPoolSize: 5,
  socketTimeoutMS: 45000,
  serverSelectionTimeoutMS: 5000
});

Caching

Consider implementing caching for:

  • User sessions
  • Ticket lists
  • GitHub repository info

Next Steps

After successful NEXUS setup:

Additional Resources

Clone this wiki locally