oussamadouhou/ai-stack-deployer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: Docker build AVX issue with Node.js/Bun hybrid strategy

Browse Source 
- 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
This commit is contained in:
Oussama Douhou
2026-01-13 11:42:15 +01:00
parent 5c7522bf1d
commit 55378f74e0
4 changed files with 244 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
CLAUDE.md
View File

@@ -316,6 +316,13 @@ Missing (needs implementation):
### Docker Build and Run
**Build Architecture**: The Dockerfile uses a hybrid approach to avoid AVX CPU requirements:
- **Build stage** (Node.js 20): Builds React client with Vite (no AVX required)
- **Runtime stage** (Bun 1.3): Runs the API server (Bun only needs AVX for builds, not runtime)
This approach ensures the Docker image builds successfully on all CPU architectures, including older systems and some cloud build environments that lack AVX support.
```bash
# Build the Docker image
docker build -t ai-stack-deployer:latest .
@@ -331,6 +338,8 @@ docker run -d \
ai-stack-deployer:latest
```
**Note**: If you encounter "CPU lacks AVX support" errors during Docker builds, ensure you're using the latest Dockerfile which implements the Node.js/Bun hybrid build strategy.
### Deploying to Dokploy
1. **Prepare Environment**:

25
Dockerfile
View File

@@ -1,22 +1,25 @@
# Use official Bun image
# ***NEVER FORGET THE PRINCIPLES RULES***
FROM oven/bun:1.3-alpine AS base
# Set working directory
# Build stage - Use Node.js to avoid AVX CPU requirement
FROM node:20-alpine AS builder
WORKDIR /app
# Copy package files
COPY package.json bun.lock* ./
# Install dependencies
FROM base AS deps
RUN bun install --frozen-lockfile --production
# Install dependencies using npm (works without AVX)
RUN npm install
# Build stage
FROM base AS builder
RUN bun install --frozen-lockfile
COPY . .
RUN bun run build
# Client: Vite build via Node.js
# API: Skip bun build, copy src files directly (Bun will run them at runtime)
RUN npm run build:client
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json bun.lock* ./
RUN npm install --production
# Production stage
FROM oven/bun:1.3-alpine AS runner

25
README.md
View File

@@ -36,13 +36,16 @@ User's AI Stack Container (OpenCode + ttyd)
### Technology Stack
- **Runtime**: Bun 1.3+
- **Runtime**: Bun 1.3+ (production), Node.js 20 (build)
- **Framework**: Hono 4.11.3
- **Language**: TypeScript
- **Container**: Docker with multi-stage builds
- **Frontend**: React 19 + Vite + Tailwind CSS 4
- **Container**: Docker with multi-stage builds (Node.js build, Bun runtime)
- **Orchestration**: Dokploy
- **Reverse Proxy**: Traefik with wildcard SSL
**Build Strategy**: Uses Node.js for building (avoids AVX CPU requirement) and Bun for runtime (performance).
## Quick Start
### Prerequisites
@@ -344,6 +347,24 @@ If a deployment fails but the name is marked as taken:
2. Delete the partial deployment if present
3. Try deployment again
### Docker Build Fails with "CPU lacks AVX support"
**Error**: `panic(main thread): Illegal instruction at address 0x...`
**Cause**: Bun requires AVX CPU instructions which may not be available in all Docker build environments.
**Solution**: Already implemented in Dockerfile. The build uses Node.js (no AVX requirement) for building and Bun for runtime:
```dockerfile
FROM node:20-alpine AS builder
RUN npm install
RUN npm run build:client
FROM oven/bun:1.3-alpine AS runner
```
If you see this error, ensure you're using the latest Dockerfile from the repository.
## Security Notes
- All API tokens stored in environment variables (never in code)

198
docs/DOCKER_BUILD_FIX.md Normal file
View File

@@ -0,0 +1,198 @@
# 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`