MyClub/DOCS/DOCKER_BUILD_MEMORY_FIX.md

# Docker Build Memory Fix Guide

## Problem
Frontend Docker build fails with "ResourceExhausted: cannot allocate memory" during React/webpack build.

## Applied Fixes

### 1. Dockerfile Optimizations ✅
**File:** `frontend/Dockerfile`

- Reduced Node memory from 4GB to 2GB (`--max-old-space-size=2048`)
- Added Node GC optimizations: `--optimize-for-size --max-semi-space-size=1`
- Set `CI=true` to limit webpack parallelism
- Added `npm cache clean` before build to free memory

### 2. Docker Compose Updates ✅
**File:** `docker-compose.yml`

- Increased frontend memory limit: 512M → 1GB
- Increased CPU limit: 1.0 → 2.0 cores
- Added `shm_size: 256m` for build stage

## How to Apply

### Method 1: Standard Build (Recommended)
```bash
# Clean previous build artifacts
docker compose down -v
docker system prune -f

# Rebuild with new settings
docker compose build frontend --no-cache
docker compose up -d
```

### Method 2: If Still Out of Memory

#### Option A: Increase Docker Desktop Memory
1. Open Docker Desktop Settings
2. Go to Resources → Advanced
3. Increase Memory to at least **6GB** (recommended 8GB)
4. Click "Apply & Restart"
5. Retry build

#### Option B: Build Outside Docker (Fastest)
```bash
cd frontend

# Install dependencies
npm install

# Build locally
npm run build

# Then use the pre-built files with Docker
docker compose up -d
```

#### Option C: Use Docker BuildKit with More Memory
```bash
# Set Docker BuildKit memory limit
export DOCKER_BUILDKIT=1
export BUILDKIT_STEP_LOG_MAX_SIZE=50000000

# Build with explicit memory limit
docker buildx build \
  --memory 4g \
  --memory-swap 6g \
  -t myclub-frontend:latest \
  ./frontend
```

## Verification

### Check Build Success
```bash
# View build logs
docker compose logs frontend

# Verify container is running
docker compose ps

# Test frontend access
curl http://localhost:3000
```

### Monitor Memory During Build
```bash
# In another terminal, watch Docker stats during build
docker stats --no-stream
```

## Troubleshooting

### Error: "Still running out of memory"
**Solutions:**
1. **Close other applications** to free system RAM
2. **Increase Docker Desktop memory** to 8GB
3. **Use local build** (Option B above)
4. **Enable swap memory** on your system

### Error: "webpack: Compilation failed"
**Solutions:**
1. Check `frontend/package.json` dependencies
2. Clear npm cache: `npm cache clean --force`
3. Delete `node_modules` and reinstall: `rm -rf node_modules && npm install`

### Error: "Cannot find ESLint plugin"
This is **expected** - ESLint is disabled during build with `DISABLE_ESLINT_PLUGIN=true` to save memory.

## Performance Tips

### Speed Up Rebuilds
```bash
# Use Docker build cache
docker compose build frontend

# Or parallel builds
docker compose build --parallel
```

### Monitor Build Progress
```bash
# Build with verbose output
docker compose build frontend --progress=plain
```

## System Requirements

### Minimum for Docker Build
- **RAM:** 6GB available
- **CPU:** 2 cores
- **Disk:** 5GB free space

### Recommended
- **RAM:** 8GB+ available
- **CPU:** 4 cores
- **Disk:** 10GB+ free space
- **SSD:** For faster builds

## Alternative: Pre-built Images

If memory is consistently an issue, consider:

1. **Build on CI/CD** (GitHub Actions, GitLab CI)
2. **Use pre-built images** from registry
3. **Build on more powerful machine** and export image

```bash
# Export built image
docker save myclub-frontend:latest | gzip > frontend-image.tar.gz

# Import on target machine
docker load < frontend-image.tar.gz
```

## Summary

The applied fixes optimize memory usage during build:
- **Reduced memory footprint** from 4GB to 2GB
- **Limited parallel processing** to prevent memory spikes
- **Cleaned cache** before build
- **Increased Docker resources** for build stage

Try the standard build first. If it still fails, use Option A (increase Docker memory) or Option B (build locally).