9.3 KiB

Raw Blame History

🔧 Deployment Troubleshooting Guide - LuckyChit

Common deployment issues and their solutions.

🚨 Critical Issues

1. bcrypt "invalid ELF header" Error

Error Message:

Error: /home/luckychit/apps/chitfund/backend/node_modules/bcrypt/lib/binding/napi-v3/bcrypt_lib.node: invalid ELF header
code: 'ERR_DLOPEN_FAILED'

Why This Happens:

You installed node_modules on Windows
You deployed to a Linux server
bcrypt has native C++ bindings that are platform-specific
Windows binaries cannot run on Linux

✅ Solution (Run on Production Server):

cd /home/luckychit/apps/chitfund/backend

# Stop PM2 process
pm2 stop luckychit-api

# Remove all node modules
rm -rf node_modules package-lock.json

# Reinstall on Linux (this will compile native bindings for Linux)
npm install

# Restart PM2
pm2 restart luckychit-api

# Check logs
pm2 logs luckychit-api

✅ Prevention:

Never copy node_modules/ between different operating systems
Add to your .gitignore (already done):
```
node_modules/
```
Always run npm install on the target server
Use the deployment script which handles this automatically:
```
./deploy.sh production
```

Alternative: Use bcryptjs (Pure JavaScript)

If you continue having issues, you can switch to bcryptjs (no native bindings):

npm uninstall bcrypt
npm install bcryptjs

Then update your code:

// Change this:
const bcrypt = require('bcrypt');

// To this:
const bcrypt = require('bcryptjs');

// The API is identical, no other changes needed!

🔥 Other Native Module Issues

Similar errors with other packages:

node-sass
sharp
sqlite3
canvas
node-gyp related errors

Solution (Same as bcrypt):

rm -rf node_modules package-lock.json
npm install
pm2 restart your-app

📦 Common PM2 Issues

App Won't Start - Crashes Immediately

Check logs first:

pm2 logs luckychit-api --lines 200

Common causes:

1. Missing `.env` File

# Check if .env exists
ls -la /home/luckychit/apps/chitfund/backend/.env

# If not, create it
cp .env.example .env
nano .env  # Edit with production credentials

2. Database Connection Failed

# Check PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -U your_db_user -d chitfund_prod

# Check .env has correct credentials
cat backend/.env | grep DB_

3. Port Already in Use

# Find what's using port 3000
lsof -i :3000
# or
sudo netstat -tulpn | grep 3000

# Kill the process
kill -9 <PID>

# Or change port in .env
echo "PORT=3001" >> .env

4. Missing Dependencies

cd backend
npm install
pm2 restart luckychit-api

PM2 Shows "errored" Status

# Check detailed error
pm2 describe luckychit-api

# View recent logs
pm2 logs luckychit-api --lines 100

# Try manual start to see error
cd backend
node server.js

App Keeps Restarting (Crash Loop)

# Check restart count
pm2 list

# View error logs
pm2 logs luckychit-api --err

# Common causes:
# - Syntax error in code
# - Missing environment variable
# - Database not accessible
# - Port conflict

Reset restart counter:

pm2 reset luckychit-api

🗄️ Database Issues

Connection Refused

Symptoms:

Error: connect ECONNREFUSED 127.0.0.1:5432

Solutions:

Check PostgreSQL is running:

sudo systemctl status postgresql
sudo systemctl start postgresql

Check PostgreSQL is listening:
```
sudo netstat -tulpn | grep 5432
```

Check pg_hba.conf allows connection:

sudo nano /etc/postgresql/*/main/pg_hba.conf

# Should have:
local   all             all                                     md5
host    all             all             127.0.0.1/32            md5

Restart PostgreSQL:
```
sudo systemctl restart postgresql
```

Authentication Failed

Symptoms:

Error: password authentication failed for user "postgres"

Solution:

# Reset password
sudo -u postgres psql
ALTER USER your_db_user WITH PASSWORD 'new_password';
\q

# Update .env file
nano backend/.env
# Change DB_PASSWORD=new_password

Database Does Not Exist

Symptoms:

Error: database "chitfund_prod" does not exist

Solution:

# Create database
sudo -u postgres psql
CREATE DATABASE chitfund_prod;
GRANT ALL PRIVILEGES ON DATABASE chitfund_prod TO your_db_user;
\q

# Run migrations
cd backend
npm run migrate  # If you have migrations

🌐 Network Issues

Cannot Access from External IP

Check firewall:

# Allow port 3000
sudo ufw allow 3000/tcp

# Check status
sudo ufw status

# Or disable temporarily for testing
sudo ufw disable

Check if app is listening on 0.0.0.0:

sudo netstat -tulpn | grep 3000

# Should show 0.0.0.0:3000 not 127.0.0.1:3000

Fix in code:

// In server.js, ensure:
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on port ${PORT}`);
});

nginx 502 Bad Gateway

Symptoms:

nginx returns 502 error
Backend is running but not accessible through nginx

Solutions:

Check backend is running:

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

Check nginx configuration:

sudo nginx -t
sudo systemctl restart nginx

Check nginx error logs:
```
sudo tail -f /var/log/nginx/error.log
```

Verify proxy_pass URL is correct:

sudo nano /etc/nginx/sites-available/luckychit
# Should have: proxy_pass http://localhost:3000;

💾 Permission Issues

EACCES: permission denied

Symptoms:

Error: EACCES: permission denied, open '/path/to/file'

Solutions:

Fix ownership:

sudo chown -R $USER:$USER /home/luckychit/apps/chitfund

Fix log directory permissions:

mkdir -p backend/logs
chmod 755 backend/logs

Run PM2 as correct user:

# Don't use sudo with PM2 unless necessary
pm2 kill
pm2 start ecosystem.config.js --env production

🔄 Auto-Start Issues

PM2 Doesn't Start After Reboot

Check if startup is configured:

pm2 startup
# Run the command it outputs

pm2 save

Verify startup script exists:

# For systemd:
systemctl status pm2-$USER

# Check logs:
journalctl -u pm2-$USER -n 50

Re-configure if needed:

pm2 unstartup
pm2 startup
# Run the command it outputs
pm2 save

📊 Performance Issues

High Memory Usage

Check memory:

pm2 monit
# or
pm2 list

Solutions:

Reduce PM2 instances:

pm2 scale luckychit-api 2  # Reduce to 2 instances

Increase memory limit in ecosystem.config.js:

max_memory_restart: '2G'  // Increase from 1G

Check for memory leaks:

pm2 logs luckychit-api
# Look for memory warnings

High CPU Usage

Check CPU:

top
# or
htop

Solutions:

Reduce instances:
```
pm2 scale luckychit-api 2
```
Check for infinite loops in code
Optimize database queries

🔍 Debugging Tips

Enable Debug Mode

Temporary debugging:

pm2 stop luckychit-api
cd backend
NODE_ENV=production DEBUG=* node server.js

Check All Logs

# PM2 logs
pm2 logs --lines 500

# System logs
journalctl -xe

# nginx logs (if using)
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/access.log

# PostgreSQL logs
sudo tail -f /var/log/postgresql/postgresql-*.log

Test API Manually

# Test from server
curl http://localhost:3000/api/health

# Test with verbose output
curl -v http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"mobile":"9999999999","password":"password123"}'

🆘 Emergency Reset

If everything is broken, start fresh:

# Stop and remove all PM2 processes
pm2 kill

# Remove node_modules
cd /home/luckychit/apps/chitfund/backend
rm -rf node_modules package-lock.json

# Fresh install
npm install

# Start fresh
pm2 start ecosystem.config.js --env production
pm2 save

# Check status
pm2 list
pm2 logs

📞 Getting Help

When asking for help, provide:

Error logs:

pm2 logs luckychit-api --lines 200 > error.log

PM2 status:
```
pm2 list
pm2 describe luckychit-api
```

Environment info:

node --version
pm2 --version
cat /etc/os-release

Configuration:

cat backend/ecosystem.config.js
# (Don't share .env - contains secrets!)

✅ Prevention Checklist

Never commit node_modules/ to Git
Always run npm install on production server
Use .env for environment-specific config
Keep .env out of Git (in .gitignore)
Use PM2 startup for auto-restart
Setup log rotation
Monitor memory/CPU usage
Setup database backups
Test deployment in staging first
Keep dependencies updated
Document your deployment process

Most issues are solved by rebuilding native modules on the production server! 🎯

9.3 KiB Raw Blame History

🔧 Deployment Troubleshooting Guide - LuckyChit

🚨 Critical Issues

1. bcrypt "invalid ELF header" Error

🔥 Other Native Module Issues

📦 Common PM2 Issues

App Won't Start - Crashes Immediately

1. Missing .env File

2. Database Connection Failed

3. Port Already in Use

4. Missing Dependencies

PM2 Shows "errored" Status

App Keeps Restarting (Crash Loop)

🗄️ Database Issues

Connection Refused

Authentication Failed

Database Does Not Exist

🌐 Network Issues

Cannot Access from External IP

nginx 502 Bad Gateway

💾 Permission Issues

EACCES: permission denied

🔄 Auto-Start Issues

PM2 Doesn't Start After Reboot

📊 Performance Issues

High Memory Usage

High CPU Usage

🔍 Debugging Tips

Enable Debug Mode

Check All Logs

Test API Manually

🆘 Emergency Reset

📞 Getting Help

✅ Prevention Checklist

9.3 KiB

Raw Blame History

1. Missing `.env` File