# Docker Build AVX Fix

## Problem

Docker build was failing with:
```
CPU lacks AVX support. Please consider upgrading to a newer CPU.
panic(main thread): Illegal instruction at address 0x3F3EDB4
oh no: Bun has crashed. This indicates a bug in Bun, not your code.
error: script "build:client" was terminated by signal SIGILL (Illegal instruction)
```

## Root Cause

Bun requires **AVX (Advanced Vector Extensions)** CPU instructions for its build operations. Many Docker build environments, especially:
- Older CPUs
- Some cloud CI/CD systems
- Virtual machines with limited CPU feature passthrough

...do not provide AVX support, causing Bun to crash with "Illegal instruction" errors.

## Solution

Implemented a **hybrid build strategy** in the Dockerfile:

### Architecture

```dockerfile
# Build stage - Use Node.js to avoid AVX CPU requirement
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json bun.lock* ./
RUN npm install
COPY . .
RUN npm run build:client

# Production dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json bun.lock* ./
RUN npm install --production

# Runtime stage - Use Bun for running the app
FROM oven/bun:1.3-alpine AS runner
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/src ./src
COPY --from=builder /app/dist/client ./dist/client
COPY --from=builder /app/package.json ./
CMD ["bun", "run", "start"]
```

### Why This Works

1. **Build Phase (Node.js)**: 
   - Vite (used for React build) runs on Node.js without AVX requirement
   - `npm install` and `npm run build:client` work on all CPU architectures
   - Builds the React client to `dist/client/`

2. **Runtime Phase (Bun)**:
   - Bun **does NOT require AVX for running TypeScript files**
   - Only needs AVX for build operations (which we avoid)
   - Provides better performance at runtime compared to Node.js

## Benefits

✅ **Universal Compatibility**: Builds on all CPU architectures  
✅ **No Performance Loss**: Bun still used for runtime (faster than Node.js)  
✅ **Clean Separation**: Build tools vs. runtime environment  
✅ **Production Ready**: Tested and verified working

## Test Results

```bash
# Build successful
docker build -t ai-stack-deployer:test .
Successfully built 1811daf55502

# Container runs correctly
docker run -d --name test -p 3001:3000 ai-stack-deployer:test
Container ID: 7c4acbf49737

# Health check passes
curl http://localhost:3001/health
{
  "status": "healthy",
  "version": "0.2.0",
  "service": "ai-stack-deployer",
  "features": {
    "productionClient": true,
    "retryLogic": true,
    "circuitBreaker": true
  }
}

# React client serves correctly
curl http://localhost:3001/
<!DOCTYPE html>
<html lang="en">
  <head>
    <script type="module" crossorigin src="/assets/index-kibXed5Q.js"></script>
    ...
```

## Implementation Date

**Date**: January 13, 2026  
**Branch**: dev (following Git Flow)  
**Files Modified**:
- `Dockerfile` - Switched build stage from Bun to Node.js
- `README.md` - Updated Technology Stack and Troubleshooting sections
- `CLAUDE.md` - Documented Docker build architecture

## Alternative Solutions Considered

### ❌ Option 1: Use Debian-based Bun image
```dockerfile
FROM oven/bun:1.3-debian
```
**Rejected**: Debian images are larger (~200MB vs ~50MB Alpine), and still require AVX support.

### ❌ Option 2: Use older Bun version
```dockerfile
FROM oven/bun:1.0-alpine
```
**Rejected**: Loses new features, security patches, and performance improvements.

### ❌ Option 3: Build locally and commit dist/
```bash
bun run build:client
git add dist/client/
```
**Rejected**: Build artifacts shouldn't be in source control. Makes CI/CD harder.

### ✅ Option 4: Hybrid Node.js/Bun strategy (CHOSEN)
**Why**: Best of both worlds - universal build compatibility + Bun runtime performance.

## Future Considerations

If Bun removes AVX requirement in future versions, we could:
1. Simplify Dockerfile back to single Bun stage
2. Keep current approach for maximum compatibility
3. Monitor Bun release notes for AVX-related changes

## References

- Bun Issue #1521: AVX requirement discussion
- Docker Multi-stage builds: https://docs.docker.com/build/building/multi-stage/
- Vite Documentation: https://vitejs.dev/guide/build.html

## Verification Commands

```bash
# Clean build test
docker build --no-cache -t ai-stack-deployer:test .

# Run and verify
docker run -d --name test -p 3001:3000 -e DOKPLOY_API_TOKEN=test ai-stack-deployer:test
sleep 3
curl http://localhost:3001/health | jq .
docker logs test
docker stop test && docker rm test

# Production build
docker build -t ai-stack-deployer:latest .
docker-compose up -d
docker-compose logs -f
```

## Troubleshooting

If you still encounter AVX errors:

1. **Verify you're using the latest Dockerfile**:
   ```bash
   git pull origin dev
   head -10 Dockerfile
   # Should show: FROM node:20-alpine AS builder
   ```

2. **Clear Docker build cache**:
   ```bash
   docker builder prune -a
   docker build --no-cache -t ai-stack-deployer:latest .
   ```

3. **Check Docker version**:
   ```bash
   docker --version
   # Recommended: Docker 20.10+ with BuildKit
   ```

## Contact

For issues or questions about this fix, refer to:
- `CLAUDE.md` - Development guidelines
- `README.md` - Troubleshooting section
- Docker logs: `docker-compose logs -f`
