PresBot UI Deployment

This document describes the deployment process for PresBot UI to Production and UAT environments.

Environments Overview

Environment	Branch	Server Path	Port	PM2 App Name
Production	`workingui-tanvi`	`/home/dash_ra/dmsb-dash-labs/presbot-ui-prod`	`3002`	`presbot-ui-prod`
UAT	`release/uat`	`/home/dash_ra/dmsb-dash-labs/presbot-ui-uat`	`3009`	`presbot-ui-uat`

Deployment Triggers

Deployments are triggered automatically via GitHub Actions when:

Push to release/uat branch → Deploys to UAT
Push to workingui-tanvi branch → Deploys to Production
Manual trigger via GitHub Actions workflow_dispatch with environment selection

CI/CD Pipeline Overview

The deployment workflow (.github/workflows/deploy.yml) consists of three jobs:

1. Setup Job

Detects the target environment and sets configuration variables:

# Outputs for UAT
deploy-path: /home/dash_ra/dmsb-dash-labs/presbot-ui-uat
pm2-namespace: uat
app-name: presbot-ui-uat
port: 3009
branch: release/uat

# Outputs for Production
deploy-path: /home/dash_ra/dmsb-dash-labs/presbot-ui-prod
pm2-namespace: prod
app-name: presbot-ui-prod
port: 3002
branch: workingui-tanvi

2. Deploy Job

Executes the following steps:

Step	Description
Send Start Notification	Posts to MS Teams that deployment started
Setup Directories	Creates `logs/` and `backups/` directories
Create Backup	Creates tar.gz backup of current deployment (keeps 3 latest)
Pull Latest Code	Fetches and resets to latest commit on target branch
Read Environment Variables	Extracts env vars from `ecosystem.config.js`
Install Dependencies	Runs `npm ci` or `npm install`
Build Application	Clears `.next` cache and runs `npm run build`
Restart PM2 Service	Stops, deletes, and starts fresh PM2 process
Health Check	Verifies service responds on expected port
Send Success Notification	Posts to MS Teams on successful deployment

3. Rollback Job

Triggered automatically on deployment failure:

Restores from the latest backup
Restarts PM2 with previous version
Sends failure notification to MS Teams

Manual Deployment

Via GitHub Actions UI

Go to Actions → Deploy PresBot UI
Click Run workflow
Select environment: uat or production
Click Run workflow

Via Command Line (on Blackwell Server)

# Navigate to the environment directory
cd /home/dash_ra/dmsb-dash-labs/presbot-ui-prod  # or presbot-ui-uat

# Pull latest changes
git fetch origin
git checkout workingui-tanvi  # or release/uat
git reset --hard origin/workingui-tanvi  # or release/uat

# Install dependencies
npm ci

# Build application
npm run build

# Restart PM2
pm2 restart ecosystem.config.js --namespace prod  # or uat

PM2 Management Commands

# View running processes
pm2 status --namespace prod    # Production
pm2 status --namespace uat     # UAT

# View logs
pm2 logs presbot-ui-prod --lines 100    # Production
pm2 logs presbot-ui-uat --lines 100     # UAT

# Restart application
pm2 restart presbot-ui-prod --namespace prod
pm2 restart presbot-ui-uat --namespace uat

# Stop application
pm2 stop presbot-ui-prod --namespace prod
pm2 stop presbot-ui-uat --namespace uat

# Delete application
pm2 delete presbot-ui-prod --namespace prod
pm2 delete presbot-ui-uat --namespace uat

# Save PM2 state (persist across reboots)
pm2 save --force

Log Files

Logs are stored in the logs/ directory of each environment:

Environment	Log Location
Production	`/home/dash_ra/dmsb-dash-labs/presbot-ui-prod/logs/`
UAT	`/home/dash_ra/dmsb-dash-labs/presbot-ui-uat/logs/`

Log Files:

out.log - Standard output logs
err.log - Error logs
combined.log - Combined logs

Backup & Rollback

Automatic Backups

Created before each deployment
Stored in backups/ directory
Named: backup-YYYYMMDD-HHMMSS.tar.gz
Only 3 most recent backups are retained
Excludes: node_modules/, .next/, *.log, backups/

Manual Rollback

# Navigate to environment
cd /home/dash_ra/dmsb-dash-labs/presbot-ui-prod

# List available backups
ls -la backups/

# Restore from backup
tar -xzf backups/backup-YYYYMMDD-HHMMSS.tar.gz -C .

# Reinstall and rebuild
npm ci
npm run build

# Restart PM2
pm2 restart ecosystem.config.js --namespace prod

Required GitHub Secrets

Secret	Description
`GH_PAT`	GitHub Personal Access Token for pulling code
`TEAMS_WEBHOOK_URL`	MS Teams webhook URL for notifications

Health Check

After deployment, the workflow verifies:

Service responds on the expected port (curl http://localhost:{port})
PM2 process status is online

If health check fails:

PM2 logs are displayed
Deployment continues (warning only)
Rollback job is triggered

Concurrency

Deployments to the same environment are serialized:

Only one deployment per environment at a time
Subsequent deployments wait for current to complete
Prevents race conditions and conflicts

Troubleshooting

Deployment Fails at Build Step

# Clear Next.js cache manually
cd /home/dash_ra/dmsb-dash-labs/presbot-ui-prod
rm -rf .next
npm run build

PM2 Process Not Starting

# Check PM2 logs for errors
pm2 logs presbot-ui-prod --lines 50 --nostream

# Verify ecosystem.config.js syntax
node -e "console.log(require('./ecosystem.config.js'))"

Port Already in Use

# Find process using the port
lsof -i :3002  # or :3009 for UAT

# Kill the process if needed
kill -9 <PID>

Git Pull Fails

# Fix git ownership issue
git config --global --add safe.directory /home/dash_ra/dmsb-dash-labs/presbot-ui-prod

# Force reset to origin
git fetch origin
git reset --hard origin/workingui-tanvi

Environments Overview​

Deployment Triggers​

CI/CD Pipeline Overview​

1. Setup Job​

2. Deploy Job​

3. Rollback Job​

Manual Deployment​

Via GitHub Actions UI​

Via Command Line (on Blackwell Server)​

PM2 Management Commands​

Log Files​

Backup & Rollback​

Automatic Backups​

Manual Rollback​

Required GitHub Secrets​

Health Check​

Concurrency​

Troubleshooting​

Deployment Fails at Build Step​

PM2 Process Not Starting​

Port Already in Use​

Git Pull Fails​