PromptTech/docs/guides/PM2_GUIDE.md

TechZone Application - PM2 Management Guide

Permanent Solution for Frontend/Backend Stability

This application now uses PM2 (Process Manager 2) to ensure both the frontend and backend run reliably with automatic restarts on crashes or system reboots.

Quick Start

Start Everything (Recommended)

./start_with_pm2.sh

This will:

• Stop any existing manual processes
• Start both backend and frontend with PM2
• Enable auto-restart on crashes
• Create log files for monitoring

Check Status

./check_status.sh
# or
pm2 status

Stop Everything

./stop_pm2.sh
# or
pm2 stop all

Benefits of PM2 Solution

✅ Auto-Restart: If frontend crashes, PM2 automatically restarts it
✅ Process Monitoring: Real-time CPU/memory monitoring
✅ Log Management: Centralized logs with rotation
✅ Zero Downtime: Graceful reloads without dropping connections
✅ Startup Script: Can configure to start on system boot
✅ Resource Limits: Automatic restart if memory exceeds threshold

PM2 Commands

View Logs

pm2 logs                      # All logs (live tail)
pm2 logs techzone-frontend    # Frontend logs only
pm2 logs techzone-backend     # Backend logs only
pm2 logs --lines 100          # Last 100 lines

Restart Services

pm2 restart techzone-frontend  # Restart frontend
pm2 restart techzone-backend   # Restart backend
pm2 restart all                # Restart everything

Stop/Start Individual Services

pm2 stop techzone-frontend     # Stop frontend
pm2 start techzone-frontend    # Start frontend
pm2 stop techzone-backend      # Stop backend
pm2 start techzone-backend     # Start backend

Monitor in Real-Time

pm2 monit   # Interactive terminal dashboard

View Detailed Info

pm2 show techzone-frontend
pm2 show techzone-backend

Remove from PM2

pm2 delete techzone-frontend
pm2 delete techzone-backend
pm2 delete all

Configuration File

The ecosystem.config.json file contains all PM2 configuration:

• Backend: Runs uvicorn with auto-reload

  • Port: 8181
  • Max memory: 500MB (restarts if exceeded)
  • Logs: logs/backend-*.log

• Frontend: Runs npm start

  • Port: 5300
  • Max memory: 1GB (restarts if exceeded)
  • Logs: logs/frontend-*.log
  • Wait ready: Up to 60s for compilation

System Boot Auto-Start (Optional)

To make services start automatically on system reboot:

# Save current PM2 process list
pm2 save

# Generate and configure startup script
pm2 startup

# Follow the instructions shown (may need sudo)

To disable auto-start:

pm2 unstartup

Log Files

Logs are stored in /media/pts/Website/PromptTech_Solution_Site/logs/:

• backend-error.log - Backend errors
• backend-out.log - Backend output
• frontend-error.log - Frontend errors
• frontend-out.log - Frontend output

Troubleshooting

Frontend won't start

# Check logs
pm2 logs techzone-frontend --lines 50

# Common issues:
# - Port 5300 already in use
# - npm dependencies missing
# - Build errors in code

# Fix: Stop other processes and restart
pkill -f "node.*5300"
pm2 restart techzone-frontend

Backend won't start

# Check logs
pm2 logs techzone-backend --lines 50

# Common issues:
# - Port 8181 already in use
# - Database connection failed
# - Python virtual environment issue

# Fix: Check database and restart
pm2 restart techzone-backend

Services keep restarting

# Check why they're crashing
pm2 logs --lines 100

# View detailed process info
pm2 show techzone-frontend
pm2 show techzone-backend

High memory usage

# Monitor in real-time
pm2 monit

# PM2 will auto-restart if memory exceeds:
# - Frontend: 1GB
# - Backend: 500MB

Switching Back to Manual Mode

If you want to run services manually without PM2:

# Stop PM2 processes
pm2 stop all
pm2 delete all

# Start backend manually
cd backend
source venv/bin/activate
uvicorn server:app --reload --host 0.0.0.0 --port 8181

# Start frontend manually (new terminal)
cd frontend
npm start

What Was Fixed

Previous Issues

1. ❌ Frontend would stop randomly
2. ❌ No auto-restart on crashes
3. ❌ Manual process management required
4. ❌ No centralized logs
5. ❌ React StrictMode causing double renders

Permanent Solutions

1. ✅ PM2 process manager with auto-restart
2. ✅ Memory limits with automatic restarts
3. ✅ Centralized log management
4. ✅ Error boundary in React app
5. ✅ StrictMode already removed (done earlier)
6. ✅ Improved craco configuration
7. ✅ Startup/stop/status scripts

URLs

• Frontend: http://localhost:5300
• Backend API: http://localhost:8181/api
• Health Check: http://localhost:8181/api/health
• Services: http://localhost:5300/services

Support

If issues persist after using PM2:

1. Check pm2 logs for error details
2. Verify ./check_status.sh shows all green
3. Check disk space: df -h
4. Check memory: free -h
5. Review error logs in logs/ directory

---

Note: The PM2 solution is production-ready and used by thousands of Node.js applications worldwide. Your application will now stay running reliably!