From 3f32d8e8284436662abef8cbe49859e84c462129 Mon Sep 17 00:00:00 2001
From: neon <18559658+neonsolstice@users.noreply.github.com>
Date: Wed, 27 May 2026 14:27:12 -0600
Subject: [PATCH] fix(docker): fail fast on CPUs that lack SSE4.2 support
 (#118)

On old hardware (e.g. AMD Turion/Phenom, Intel Core 2), sharp's musl binary
crashes with SIGILL during NestJS module init. Combined with bufferLogs: true
and restart: unless-stopped, this produces a silent infinite restart loop -
only the migration success message is ever visible.

Add check_cpu_sse42 to entrypoint.sh: greps /proc/cpuinfo for sse4_2, exits
with a clear error if absent, no-op when /proc/cpuinfo is unavailable. Also
add a System Requirements section to README documenting the SSE4.2 minimum.

Closes #116
---
 README.md            | 12 ++++++++++++
 server/entrypoint.sh | 16 ++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/README.md b/README.md
index e0d1279aa..a2ab13fcf 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,18 @@ Note: The demo includes a sample library of public domain books. Some features a
 
 ---
 
+## System Requirements
+
+| Component    | Minimum                                                                         |
+| ------------ | ------------------------------------------------------------------------------- |
+| CPU (x86-64) | SSE4.2 support required - Intel Core (Nehalem, 2008+) or AMD (Bulldozer, 2011+) |
+| RAM          | 1 GB (2 GB+ recommended)                                                        |
+| Docker       | 20.10+                                                                          |
+
+> **CPU note:** The image processing library used for book covers requires SSE4.2 instructions. CPUs that pre-date Intel Nehalem (2008) or AMD Bulldozer (2011) do not meet this requirement - including the entire Intel Core 2 series, AMD Phenom, and AMD Turion families. If your CPU is incompatible, the container will exit immediately with a clear error message rather than looping silently.
+
+---
+
 ## Quick Start
 
 ```bash
diff --git a/server/entrypoint.sh b/server/entrypoint.sh
index 80ea7d15e..71bc4cb2a 100644
--- a/server/entrypoint.sh
+++ b/server/entrypoint.sh
@@ -52,6 +52,20 @@ check_writable_current_user() {
   fi
 }
 
+check_cpu_sse42() {
+  if [ ! -f /proc/cpuinfo ]; then
+    return 0
+  fi
+  if ! grep -q 'sse4_2' /proc/cpuinfo; then
+    log "CPU does not support SSE4.2 instructions."
+    log "The image processing library (sharp) requires a CPU with SSE4.2 support."
+    log "Minimum supported CPUs: Intel Core (Nehalem, 2008 or newer) or AMD (Bulldozer, 2011 or newer)."
+    log "Incompatible CPUs include: Intel Core 2 series, AMD Phenom, AMD Turion, and other pre-2011 AMD chips."
+    log "Run 'docker stop <container-name>' to stop this container, then upgrade your hardware."
+    exit 1
+  fi
+}
+
 if [ -z "$DATABASE_URL" ]; then
   export DATABASE_URL="postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST:-postgres}:${POSTGRES_PORT:-5432}/${POSTGRES_DB}"
 fi
@@ -92,6 +106,8 @@ fi
 
 export NODE_MAX_OLD_SPACE_SIZE
 
+check_cpu_sse42
+
 ensure_dir "$APP_DATA_PATH"
 ensure_dir "$APP_DATA_PATH/covers"
 ensure_dir "$book_bucket_path"