# 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/ ... ``` ## 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`