Files

Oussama Douhou 55378f74e0 fix: Docker build AVX issue with Node.js/Bun hybrid strategy

- Switch build stage from Bun to Node.js to avoid AVX CPU requirement
- Use Node.js 20 Alpine for building React client (Vite)
- Keep Bun runtime for API server (no AVX needed for runtime)
- Update README.md with build strategy and troubleshooting
- Update CLAUDE.md with Docker architecture documentation
- Add comprehensive docs/DOCKER_BUILD_FIX.md with technical details

Fixes #14 - Docker build crashes with "CPU lacks AVX support"

Tested:
- Docker build: SUCCESS
- Container runtime: SUCCESS
- Health check: PASS
- React client serving: PASS

2026-01-13 11:42:15 +01:00

5.2 KiB

Raw Blame History

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

# 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

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/
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

# 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

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

FROM oven/bun:1.0-alpine

Rejected: Loses new features, security patches, and performance improvements.

❌ Option 3: Build locally and commit dist/

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:

Simplify Dockerfile back to single Bun stage
Keep current approach for maximum compatibility
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

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

Verify you're using the latest Dockerfile:

git pull origin dev
head -10 Dockerfile
# Should show: FROM node:20-alpine AS builder

Clear Docker build cache:

docker builder prune -a
docker build --no-cache -t ai-stack-deployer:latest .

Check Docker version:

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

5.2 KiB Raw Blame History