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

```bash
# 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

```bash
# 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:

```bash
# 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:**
   ```bash
   cd /root/biblical-guide
   pm2 resurrect  # Restore PM2 processes
   pm2 save
   ```

## Add Swap (Recommended)

To prevent future crashes, add swap:

```bash
# 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)

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

### 2. Disable Source Maps in Production

In `next.config.js`:
```javascript
productionBrowserSourceMaps: false,
```

### 3. Use TypeScript Without Type Checking

```bash
# 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:

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

## Monitoring During Build

```bash
# 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