Fix Bun Container Crashes - Exit 143, OOM, and CI Failures

Your container dies during shutdown because Bun's acting like a deaf kid when Docker tries to shut it down. When Bun runs as PID 1, it completely ignores the SIGTERM signals Docker's sending. Docker waits around for 10 seconds like a patient parent, then says 'fuck it' and kills everything with SIGKILL - hello exit code 143.

## Breaks during shutdown
CMD [\"bun\", \"run\", \"start\"]

## Actually handles signals
CMD [\"bun\", \"--init\", \"run\", \"start\"]

Add `--init` to your CMD and the crashes stop. This spawns tini - a tiny init process that actually handles shutdown signals and forwards them to Bun. Without it, Docker gives up after 10 seconds and kills your container. Classic PID 1 fuckery that bites every containerized app.

CPU Instruction Crashes on Older Hardware

Bun crashes with "Illegal instruction" on older hardware because it needs AVX2 CPU instructions. This hits GitHub Actions, older AWS instances (anything t2/t3, most m5 instances), Google Cloud Build, and basically any CI runner using budget CPUs. It also fucks over Docker Desktop on older Macs.

oh no: Bun has crashed. This indicates a bug in Bun, not your code.
Illegal instruction at address 0x2B11410

## This cryptic bullshit error means your CPU is too old for Bun's optimized build.
## Took forever to figure out this was AVX2 bullshit.
## Stack Overflow was useless. Found the answer buried in some GitHub issue.
## GitHub Actions is basically guaranteed to not have modern CPU instructions.

Use the baseline binary for older hardware. The baseline build targets x86-64-v1 without modern extensions:

FROM oven/bun:1-baseline

This solves compatibility with older VPS providers, legacy cloud instances, and shared hosting that don't support advanced vector extensions.

Lockfile Platform Issues Break CI

Lockfile problems happen when you develop on macOS but deploy to Linux containers. Bun's binary lockfile format stores platform-specific data that breaks CI builds when platforms don't match.

error: lockfile had changes, but lockfile is frozen

## This happens every damn time you go from Mac dev to Linux container.
## Works fine locally, breaks instantly on every single CI run.
## Took forever to figure out it was binary lockfile platform differences.

Skip the frozen flag or generate the lockfile in Docker:

## Just install normally
RUN bun install

## Or generate lockfile in container first
RUN bun install && bun install --frozen-lockfile

Memory Issues and OOMKilled Containers

Bun's hungrier for memory than Node because it uses JavaScriptCore instead of V8. Same code that sips 300MB in Node suddenly wants 450MB+ in Bun. JavaScriptCore is hungry as hell.

## Exit code 137 = SIGKILL from OOM
## Had our production API running fine locally - using maybe 300MB.
## Deployed to production and everything started OOMing at 700MB.
## Spent hours thinking it was a memory leak before I realized
## Bun just uses way more RAM than Node. Same exact code, 40% more memory usage.

Set explicit memory limits and clear cache location:

ENV BUN_RUNTIME_TRANSPILER_CACHE_PATH=/tmp/bun-cache
RUN mkdir -p /tmp/bun-cache

Build Context Size Problems

Docker builds are slow because standard .dockerignore files don't exclude Bun's cache directories. The .bun folder grows to gigabytes and slows your builds.

.bun/
bun.lockb.old
node_modules/
dist/
build/
*.log

Health Check Failures and Restart Loops

Health checks fail because Bun takes longer to start than Node.js. Bun.serve() needs time to warm up the transpiler and initialize, but Docker expects the server to be ready immediately.

## Give Bun time to start
HEALTHCHECK --start-period=40s \
  CMD curl -f http\://localhost\:3000/health || exit 1

90% of crashes are missing the --init flag. Add that first - 5 minutes if you're lucky, 2 hours if Docker decides to be a pain in the ass. Then worry about memory limits and health check timing. Everything else is just optimization bullshit that doesn't matter until you fix the basics.

Exit Code 143: Containers Die During Shutdown

docker inspect container_name | grep ExitCode
## \"ExitCode\": 143 = signal handling broken

Add --init to your CMD and the crashes stop. This fixes 90% of exit 143 issues. The --init flag spawns tini to handle signal forwarding and zombie reaping. Without it, Bun doesn't respond to SIGTERM and Docker force-kills containers after the shutdown timeout.

CMD [\"bun\", \"--init\", \"run\", \"start\"]

\"Illegal Instruction\" on Old Hardware

Check if your platform supports AVX2 instructions:

grep -m1 avx2 /proc/cpuinfo || echo \"Use bun-baseline\"

Switch to the baseline image for older CPUs:

FROM oven/bun:1-baseline

Lockfile Fails in CI But Works Locally

Your Mac generates different lockfiles than Linux containers because of the binary lockfile format storing platform-specific hashes. This breaks CI every damn time - works fine locally, fails on every single CI build. The binary lockfile format stores platform-specific hashes that CI runners can't handle. Skip `--frozen-lockfile` or generate the lockfile in Docker:

## Generate lockfile in container first
RUN bun install && bun install --frozen-lockfile

Memory Issues and OOMKilled

Bun uses more memory than Node because JavaScriptCore is hungrier than V8. JSC's garbage collector holds onto memory longer and uses more of it. This leads to containers getting OOMKilled and exit code 137. Set cache path and increase limits:

ENV BUN_RUNTIME_TRANSPILER_CACHE_PATH=/tmp/bun-cache
RUN mkdir -p /tmp/bun-cache

Health Checks Fail

Bun takes its sweet time starting up compared to Node. Server initialization includes transpiler setup, module loading, and JSC warmup. Docker health checks fail during this startup period, causing restart loops. Increase the health check start period:

HEALTHCHECK --start-period=40s CMD curl -f http\://localhost\:3000/health || exit 1

Most crashes are missing the --init flag. Fix that first, then check memory limits and health check timing.

Use the Right Base Image

## For new CPUs
FROM oven/bun:1-slim

## For older hardware or CI
FROM oven/bun:1-baseline

Use `bun:1-baseline` for older hardware and CI. Most cloud instances and GitHub Actions need the baseline image because they don't have AVX2 instructions. This includes standard AWS instances, Google Cloud VMs, Azure containers, and most CI environments that use older CPU architectures for compatibility.

Essential Dockerfile Template

FROM oven/bun:1-slim
WORKDIR /app

## Copy and install first (caching)
COPY package.json bun.lockb ./
RUN bun install --production

## Copy source
COPY . .

## Set cache path
ENV BUN_RUNTIME_TRANSPILER_CACHE_PATH=/tmp/bun-cache
RUN mkdir -p /tmp/bun-cache

## Use init flag for signal handling
CMD ["bun", "--init", "run", "start"]

The `--init` flag prevents most crashes. The cache path stops permission errors. Everything else is just optimization.

Monitor Memory Early

Add simple memory logging before things break:

// Add to your main file
setInterval(() => {
  const memMB = Math.round(process.memoryUsage.rss() / 1024 / 1024);
  if (memMB > 400) console.warn(`Memory: ${memMB}MB`);
}, 30000);

// Real example: our API started at 180MB, climbed to 620MB after 6 hours.
// OOMKilled at 700MB limit. Same Node.js code peaked around 450MB.

Bun's hungrier for memory than Node - about 40% more in my experience. Monitor memory usage before containers get OOMKilled. JavaScriptCore just handles memory differently than V8, and not in a good way for containers.

Proper .dockerignore

node_modules/
.bun/
dist/
build/
.cache/
*.log
.DS_Store

Exclude Bun's cache directories or builds take forever. The `.bun` folder grows to gigabytes and kills your build performance.

Health Check Timing

## Bun needs more startup time
HEALTHCHECK --start-period=40s \
  CMD curl -f http\://localhost\:3000/health || exit 1

Bun takes longer to start than Node - sometimes 20-30 seconds vs Node's 5-10 seconds. Give it more time or health checks fail and containers restart in loops. Learned this the hard way when our Kubernetes pods kept crashing on startup and the logs just said 'unhealthy' - which tells you exactly nothing.

Test With Production Constraints

## Test memory limits
docker run --memory=\"1g\" your-image

## Test CPU constraints
docker run --cpus=\"1.0\" your-image

Test with the same memory and CPU limits you'll use in production. Test with production constraints or you'll find out the hard way during deployment.

Most crashes happen because of missing `--init` or memory limits. Fix those first, then optimize. Everything else is just paperwork that makes you feel productive but doesn't solve the real problems.