biblical-guide.com/BUILD_GUIDE.md

Safe Build Guide

⚠️ IMPORTANT: Building Without Crashing the Server

The Next.js build process can consume 4-6 GB of RAM. Without proper safeguards, this can crash the production server by triggering the Linux OOM (Out of Memory) killer.

Problem

Your server has:

• 16 GB RAM total
• NO SWAP configured (SwapTotal: 0 kB)
• Running production services (PM2, PostgreSQL, etc.)

When next build runs without limits, it can:

1. Consume all available memory
2. Trigger Linux OOM killer
3. Kill critical processes (PM2, database, SSH)
4. Crash the entire server

Solution: Safe Build Script

Use the Safe Build Script

# Always use this instead of 'npm run build'
bash scripts/safe-build.sh

What the Safe Build Script Does

1. ✓ Checks available memory (requires 4GB minimum)
2. ✓ Stops PM2 services to free memory during build
3. ✓ Sets memory limits (4GB max for Node.js)
4. ✓ Monitors memory during build (kills if >90%)
5. ✓ Restarts services after build completes
6. ✓ Verifies build artifacts before finishing

Build Process

Before Build: Check Memory (need 4GB+ free)
    ↓
Stop PM2: Free up 500MB-1GB
    ↓
Clear Cache: Free up 200MB-500MB
    ↓
Build with Limits: Max 4GB RAM
    ↓
Monitor: Kill if >90% memory used
    ↓
Verify: Check .next/BUILD_ID exists
    ↓
Restart PM2: Restore services

Memory Limits Explained

# This limits Node.js to use maximum 4GB RAM
NODE_OPTIONS="--max-old-space-size=4096"

Why 4GB?

• Server has 16GB total
• System needs ~2GB
• PostgreSQL needs ~1GB
• PM2/services need ~500MB (when stopped)
• Leaves ~12GB available
• 4GB limit = Safe buffer of 8GB unused

Manual Build (NOT RECOMMENDED)

If you must build manually:

# 1. Stop PM2 first
pm2 stop all

# 2. Build with memory limit
NODE_OPTIONS="--max-old-space-size=4096" npx next build --no-lint

# 3. Restart PM2
pm2 restart all

⚠️ WARNING: This doesn't monitor memory - can still crash!

Emergency: Server Crashed

If the server crashed during build:

1. SSH may be dead - Use console/VNC from hosting provider
2. Reboot the server if unresponsive
3. After reboot:

   cd /root/biblical-guide
   pm2 resurrect  # Restore PM2 processes
   pm2 save
   

Add Swap (Recommended)

To prevent future crashes, add swap:

# Create 8GB swap file
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# Verify
free -h

Build Optimization Tips

1. Use Build Cache (When Possible)

# Don't delete .next/cache unless necessary
# Speeds up builds and uses less memory

2. Disable Source Maps in Production

In next.config.js:

productionBrowserSourceMaps: false,

3. Use TypeScript Without Type Checking

# Already using --no-lint flag
npx next build --no-lint

4. Increase Memory for Large Sites

If build fails with OOM even with safe-build.sh:

# Edit safe-build.sh line 70:
NODE_OPTIONS="--max-old-space-size=6144"  # Use 6GB instead of 4GB

Monitoring During Build

# In another terminal, monitor memory:
watch -n 2 'free -h && echo "---" && ps aux | grep next | grep -v grep'

Common Build Errors

Error: "JavaScript heap out of memory"

Cause: Node.js hit memory limit Fix: Increase --max-old-space-size in safe-build.sh

Error: "Killed" (exit code 137)

Cause: Linux OOM killer terminated the process Fix: You need more free RAM - stop more services or add swap

Error: "Could not find BUILD_ID"

Cause: Build was interrupted or failed Fix: Run safe-build.sh again

Production Deployment Checklist

Before running builds on production:

• Check free memory: free -h (need 4GB+ available)
• Use safe-build.sh script
• Monitor in separate terminal
• Have console access ready (in case SSH dies)
• Consider adding swap if not present

Best Practice: Build Elsewhere

Recommended Approach:

1. Build on local machine or CI/CD
2. Commit .next folder to git (or use artifacts)
3. Deploy to server without building
4. Just run pm2 restart all

This avoids building on production entirely!

---

Summary

✅ ALWAYS use bash scripts/safe-build.sh ❌ NEVER run npm run build directly ⚠️ MONITOR memory during builds 💾 ADD SWAP to prevent OOM kills