Initial commit - PromptTech
This commit is contained in:
253
docs/guides/PM2_GUIDE.md
Normal file
253
docs/guides/PM2_GUIDE.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
./check_status.sh
|
||||
# or
|
||||
pm2 status
|
||||
```
|
||||
|
||||
### Stop Everything
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
pm2 restart techzone-frontend # Restart frontend
|
||||
pm2 restart techzone-backend # Restart backend
|
||||
pm2 restart all # Restart everything
|
||||
```
|
||||
|
||||
### Stop/Start Individual Services
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
pm2 monit # Interactive terminal dashboard
|
||||
```
|
||||
|
||||
### View Detailed Info
|
||||
|
||||
```bash
|
||||
pm2 show techzone-frontend
|
||||
pm2 show techzone-backend
|
||||
```
|
||||
|
||||
### Remove from PM2
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Check why they're crashing
|
||||
pm2 logs --lines 100
|
||||
|
||||
# View detailed process info
|
||||
pm2 show techzone-frontend
|
||||
pm2 show techzone-backend
|
||||
```
|
||||
|
||||
### High memory usage
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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!
|
||||
Reference in New Issue
Block a user