Deployment Guide

Complete guide for deploying Hexabot + Prophunt in development and production environments.

Prerequisites

Node.js 18+ and npm
Docker and Docker Compose
MongoDB 5.0+ (via Docker or standalone)
Git for version control

Environment Variables

Required Variables

Create hexabot-jarvis/docker/.env.development:

# API Configuration
API_PORT=4000
NODE_ENV=development

# Frontend Origins (CORS)
FRONTEND_DOMAIN=localhost
FRONTEND_BASE_URL=http://localhost:8100
FRONTEND_ORIGIN=${FRONTEND_BASE_URL},http://${FRONTEND_DOMAIN}:5173,http://${FRONTEND_DOMAIN}:8100,http://${FRONTEND_DOMAIN}:8101

# MongoDB
MONGO_HOST=mongo
MONGO_PORT=27017
MONGO_DB=hexabot
MONGO_USER=<your_mongo_user>
MONGO_PASSWORD=<your_mongo_password>
MONGO_URL=mongodb://${MONGO_USER}:${MONGO_PASSWORD}@${MONGO_HOST}:${MONGO_PORT}/${MONGO_DB}?authSource=admin

# Prophunt Webserver
PROPHUNT_API_URL=http://localhost:3000/api

# Security
JWT_SECRET=<generate_random_secret>
SESSION_SECRET=<generate_random_secret>

# Optional: Logging
LOG_LEVEL=debug

Production Variables

Create hexabot-jarvis/docker/.env.production:

NODE_ENV=production
API_PORT=4000

# Use your production domain
FRONTEND_DOMAIN=chat.prophunt.com
FRONTEND_BASE_URL=https://${FRONTEND_DOMAIN}
FRONTEND_ORIGIN=${FRONTEND_BASE_URL}

# Production MongoDB (use managed service recommended)
MONGO_URL=mongodb+srv://user:password@cluster.mongodb.net/hexabot?retryWrites=true&w=majority

# Production Prophunt API
PROPHUNT_API_URL=https://api.prophunt.com

# Strong secrets (use password generator)
JWT_SECRET=<64_char_random_string>
SESSION_SECRET=<64_char_random_string>

# Logging
LOG_LEVEL=info

# Optional: Redis for session storage
REDIS_URL=redis://redis:6379

# Optional: S3 for file uploads
S3_BUCKET=prophunt-chat-uploads
AWS_ACCESS_KEY_ID=<your_key>
AWS_SECRET_ACCESS_KEY=<your_secret>
AWS_REGION=ap-south-1

Development Setup

1. Clone Repository

git clone https://github.com/yourorg/ProphuntChatbot.git
cd ProphuntChatbot/hexabot-jarvis

2. Install Dependencies

npm install

3. Configure Environment

cp docker/.env.example docker/.env.development
# Edit docker/.env.development with your values

4. Start Docker Containers

npm run dev

This starts:

MongoDB on port 27017
Hexabot API on port 4000 (host) → 3000 (container)
Hot reload enabled

5. Verify

# Check containers
docker ps

# Check logs
docker logs -f api

# Test API
curl http://localhost:4000/health

6. Start Frontend (Angular)

cd ../prophunt-webapp
npm install
npm start
# Open http://localhost:8101

Production Deployment

Option 1: Docker Compose (Recommended)

1. Prepare Production Environment

# Create production env file
cp docker/.env.example docker/.env.production
# Fill in production values

2. Build Production Image

docker-compose -f docker/docker-compose.production.yml build

3. Start Services

docker-compose -f docker/docker-compose.production.yml up -d

4. Setup Nginx Reverse Proxy

/etc/nginx/sites-available/hexabot:

upstream hexabot_api {
    server localhost:4000;
}

server {
    listen 80;
    server_name chat-api.prophunt.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name chat-api.prophunt.com;

    # SSL Configuration
    ssl_certificate /etc/letsencrypt/live/chat-api.prophunt.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat-api.prophunt.com/privkey.pem;

    # API
    location / {
        proxy_pass http://hexabot_api;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket (Socket.io)
    location /socket.io/ {
        proxy_pass http://hexabot_api;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 86400;
    }
}

5. Enable Site

sudo ln -s /etc/nginx/sites-available/hexabot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

6. Setup SSL with Let's Encrypt

sudo certbot --nginx -d chat-api.prophunt.com

Option 2: PM2 (Node Process Manager)

1. Install PM2

npm install -g pm2

2. Build Application

npm run build

3. Create PM2 Ecosystem File

ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'hexabot-api',
    script: 'dist/main.js',
    instances: 'max',
    exec_mode: 'cluster',
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      PORT: 4000
    },
    env_file: './docker/.env.production',
    error_file: './logs/err.log',
    out_file: './logs/out.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
    merge_logs: true
  }]
};

4. Start with PM2

pm2 start ecosystem.config.js
pm2 save
pm2 startup

5. Monitor

pm2 list
pm2 logs hexabot-api
pm2 monit

Option 3: Kubernetes

1. Create ConfigMap

k8s/configmap.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: hexabot-config
data:
  NODE_ENV: "production"
  API_PORT: "4000"
  LOG_LEVEL: "info"

2. Create Secret

kubectl create secret generic hexabot-secrets \
  --from-literal=MONGO_URL='mongodb://...' \
  --from-literal=JWT_SECRET='...' \
  --from-literal=SESSION_SECRET='...'

3. Create Deployment

k8s/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hexabot-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: hexabot-api
  template:
    metadata:
      labels:
        app: hexabot-api
    spec:
      containers:
      - name: hexabot
        image: prophunt/hexabot:latest
        ports:
        - containerPort: 4000
        envFrom:
        - configMapRef:
            name: hexabot-config
        - secretRef:
            name: hexabot-secrets
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1000m"
        livenessProbe:
          httpGet:
            path: /health
            port: 4000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port:4000
          initialDelaySeconds: 5
          periodSeconds: 5

4. Create Service

k8s/service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: hexabot-service
spec:
  selector:
    app: hexabot-api
  ports:
  - protocol: TCP
    port: 80
    targetPort: 4000
  type: LoadBalancer

5. Deploy

kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

Database Setup

MongoDB Atlas (Recommended for Production)

Create cluster at mongodb.com/atlas
Create database hexabot
Create user with read/write permissions
Whitelist your server IPs
Copy connection string to MONGO_URL

Self-Hosted MongoDB

# Install MongoDB 5.0+
sudo apt-get install mongodb-org

# Start service
sudo systemctl start mongod
sudo systemctl enable mongod

# Create database and user
mongo
> use hexabot
> db.createUser({
    user: "hexabot_user",
    pwd: "secure_password",
    roles: [{ role: "readWrite", db: "hexabot" }]
  })

Scaling

Horizontal Scaling

Use load balancer to distribute across multiple instances:

upstream hexabot_cluster {
    least_conn;
    server hexabot1:4000;
    server hexabot2:4000;
    server hexabot3:4000;
}

server {
    location / {
        proxy_pass http://hexabot_cluster;
    }
}

Vertical Scaling

Increase container resources in docker-compose.yaml:

services:
  api:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
        reservations:
          cpus: '1.0'
          memory: 2G

Monitoring & Logging

PM2 Monitoring

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 30

Docker Logging

# View logs
docker logs -f api --tail 100

# Configure logging driver
# In docker-compose.yaml
services:
  api:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Application Monitoring (Optional)

Install monitoring tools:

npm install @nestjs/terminus @nestjs/axios

Create health check:

@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private db: MongooseHealthIndicator
  ) {}

  @Get()
  check() {
    return this.health.check([
      () => this.db.pingCheck('database')
    ]);
  }
}

Security Checklist

Troubleshooting

Cannot connect to MongoDB

# Check MongoDB is running
docker ps | grep mongo

# Check connection string
echo $MONGO_URL

# Test connection
mongosh "$MONGO_URL"

Socket.io connection timeout

# Check CORS configuration
# Ensure FRONTEND_ORIGIN includes your frontend URL

# Check firewall
sudo ufw status
sudo ufw allow 4000/tcp

# Check Nginx proxy headers for WebSocket

High memory usage

# Check PM2 cluster mode
pm2 list

# Reduce instances or increase memory limit
pm2 restart hexabot-api --max-memory-restart 500M

Messages not persisting

# Verify ConversationManager is being used
# Check MongoDB write permissions
# Review application logs for errors
docker logs api | grep -i error

Backup Strategy

Automated MongoDB Backups

#!/bin/bash
# /usr/local/bin/backup-hexabot.sh

BACKUP_DIR="/backups/hexabot"
DATE=$(date +%Y%m%d_%H%M%S)

mongodump --uri="$MONGO_URL" --out="$BACKUP_DIR/$DATE"

# Keep only last 7 days
find $BACKUP_DIR -type d -mtime +7 -exec rm -rf {} +

Add to crontab:

0 2 * * * /usr/local/bin/backup-hexabot.sh

Rollback Plan

# Tag before deployment
git tag -a v1.2.3 -m "Release 1.2.3"
git push origin v1.2.3

# If issues occur, rollback
git checkout v1.2.2
npm run build
pm2 restart hexabot-api

# Or with Docker
docker-compose down
docker-compose pull prophunt/hexabot:v1.2.2
docker-compose up -d

Next Steps

Configure Monitoring Dashboard
Setup CI/CD Pipeline
Implement Rate Limiting
Enable Analytics

Prerequisites​

Environment Variables​

Required Variables​

Production Variables​

Development Setup​

1. Clone Repository​

2. Install Dependencies​

3. Configure Environment​

4. Start Docker Containers​

5. Verify​

6. Start Frontend (Angular)​

Production Deployment​

Option 1: Docker Compose (Recommended)​

1. Prepare Production Environment​

2. Build Production Image​

3. Start Services​

4. Setup Nginx Reverse Proxy​

5. Enable Site​

6. Setup SSL with Let's Encrypt​

Option 2: PM2 (Node Process Manager)​

1. Install PM2​

2. Build Application​

3. Create PM2 Ecosystem File​

4. Start with PM2​

5. Monitor​

Option 3: Kubernetes​

1. Create ConfigMap​

2. Create Secret​

3. Create Deployment​

4. Create Service​

5. Deploy​

Database Setup​

MongoDB Atlas (Recommended for Production)​

Self-Hosted MongoDB​

Scaling​

Horizontal Scaling​

Vertical Scaling​

Monitoring & Logging​

PM2 Monitoring​

Docker Logging​

Application Monitoring (Optional)​

Security Checklist​

Troubleshooting​

Cannot connect to MongoDB​

Socket.io connection timeout​

High memory usage​

Messages not persisting​

Backup Strategy​

Automated MongoDB Backups​

Rollback Plan​

Next Steps​