fix: make source maps opt-in to restore v1.67.0 memory baseline

Production source maps (--enable-source-maps) caused a ~50% memory increase
(600MB to 1000MB) in v1.68.0. Node.js loads all .map files into memory when
this flag is enabled, and Next.js server chunks generate hundreds of map files.

Changes:
- Guard productionBrowserSourceMaps and serverSourceMaps behind
  HOMARR_ENABLE_SOURCE_MAPS env var (default off)
- Guard .map copy step and NODE_OPTIONS in Dockerfile behind
  ENABLE_SOURCE_MAPS build arg (default false)
- run.sh checks HOMARR_ENABLE_SOURCE_MAPS before setting --enable-source-maps
- Add Docker-based memory regression CI job (<700MB threshold)

Closes #6123

.github/workflows/code-quality.yml

@@ -163,3 +163,58 @@ jobs:
         run: cp .env.example .env
       - name: Build
         run: pnpm turbo build --affected
+
+  memory-regression:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+      - name: Build Docker image
+        uses: docker/build-push-action@v7
+        with:
+          platforms: linux/amd64
+          context: .
+          push: false
+          load: true
+          tags: homarr-memory-test
+          network: host
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+        env:
+          SKIP_ENV_VALIDATION: true
+      - name: Start container and measure memory
+        run: |
+          docker run -d --name homarr-mem-test -p 17575:7575 homarr-memory-test
+          # Wait for container to be healthy (up to 60s)
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:17575/api/health 2>/dev/null; then
+              echo "Container healthy after $((i * 2))s"
+              break
+            fi
+            sleep 2
+          done
+          # Warm up: hit the dashboard page a few times
+          for i in $(seq 1 5); do
+            curl -sf http://localhost:17575/ > /dev/null 2>&1 || true
+            sleep 2
+          done
+          # Measure RSS after warmup
+          MEM_KB=$(docker stats --no-stream --format '{{.MemUsage}}' homarr-mem-test | sed 's| /.*||')
+          echo "Raw memory: $MEM_KB"
+          # Convert to numeric MB (handles GiB and MiB suffixes)
+          MEM_NUM=$(echo "$MEM_KB" | awk '{
+            if ($0 ~ /GiB/) { gsub(/GiB/,""); print $1 * 1024 }
+            else if ($0 ~ /MiB/) { gsub(/MiB/,""); print $1 }
+            else if ($0 ~ /KiB/) { gsub(/KiB/,""); print $1 / 1024 }
+            else { print $1 / 1048576 }
+          }')
+          echo "Memory usage: ${MEM_NUM} MB"
+          MAX_MB=700
+          if awk "BEGIN {exit !($MEM_NUM > $MAX_MB)}"; then
+            echo "ERROR: Memory usage ${MEM_NUM} MB exceeds ${MAX_MB} MB threshold"
+            docker logs homarr-mem-test --tail 50
+            exit 1
+          fi
+          echo "Memory check passed: ${MEM_NUM} MB <= ${MAX_MB} MB"

Dockerfile

@@ -20,16 +20,18 @@ ARG DISABLE_REDIS_LOGS='true'
 
 RUN corepack enable pnpm && pnpm build
 
-# The standalone output tracing omits server chunk source maps (.next/server/**/*.map), which is
-# where production Node stack frames point. Copy the .map files into the standalone tree (preserving
-# directory structure) so the existing standalone COPY ships them, keeping traces readable.
-# See https://github.com/homarr-labs/homarr/issues/5891
-RUN cd apps/nextjs/.next/server && \
-    find . -name '*.map' | while IFS= read -r map; do \
-      dest="../standalone/apps/nextjs/.next/server/$map"; \
-      mkdir -p "$(dirname "$dest")"; \
-      cp "$map" "$dest"; \
-    done
+# Copy server chunk source maps into standalone output when enabled.
+# Off by default to avoid the significant memory overhead of --enable-source-maps in Node.js.
+# See https://github.com/homarr-labs/homarr/issues/6123 and https://github.com/nodejs/node/issues/46140
+ARG ENABLE_SOURCE_MAPS=false
+RUN if [ "$ENABLE_SOURCE_MAPS" = "true" ]; then \
+      cd apps/nextjs/.next/server && \
+      find . -name '*.map' | while IFS= read -r map; do \
+        dest="../standalone/apps/nextjs/.next/server/$map"; \
+        mkdir -p "$(dirname "$dest")"; \
+        cp "$map" "$dest"; \
+      done; \
+    fi
 
 FROM base AS runner
 WORKDIR /app
@@ -75,9 +77,9 @@ ENV DB_DRIVER='better-sqlite3'
 ENV AUTH_PROVIDERS='credentials'
 ENV REDIS_IS_EXTERNAL='false'
 ENV NODE_ENV='production'
-# Tell Node to symbolicate stack traces using the shipped .map files so production logs
-# show original source locations instead of minified frames, see https://github.com/homarr-labs/homarr/issues/5891
-ENV NODE_OPTIONS='--enable-source-maps'
+# Pass through the source maps toggle so run.sh can conditionally set NODE_OPTIONS.
+ARG ENABLE_SOURCE_MAPS=false
+ENV HOMARR_ENABLE_SOURCE_MAPS=$ENABLE_SOURCE_MAPS
 
 ENTRYPOINT [ "/app/entrypoint.sh" ]
 CMD ["sh", "run.sh"]

apps/nextjs/next.config.ts

@@ -31,8 +31,7 @@ const nextConfig: NextConfig = {
   },
   output: "standalone",
   reactStrictMode: true,
-  // Ship browser source maps so production client stack traces are readable, see https://github.com/homarr-labs/homarr/issues/5891
-  productionBrowserSourceMaps: true,
+  productionBrowserSourceMaps: process.env.HOMARR_ENABLE_SOURCE_MAPS === "true",
   // react compiler breaks mantine-react-table, so disabled for now
   //reactCompiler: true,
   /** We already do typechecking as separate tasks in CI */
@@ -43,8 +42,7 @@ const nextConfig: NextConfig = {
    */
   serverExternalPackages: ["dockerode", "isomorphic-dompurify", "jsdom", "better-sqlite3"],
   experimental: {
-    // Ship server source maps so production Node stack traces in logs reference original source, see https://github.com/homarr-labs/homarr/issues/5891
-    serverSourceMaps: true,
+    serverSourceMaps: process.env.HOMARR_ENABLE_SOURCE_MAPS === "true",
     optimizePackageImports: ["@mantine/core", "@mantine/hooks", "@tabler/icons-react"],
     turbopackFileSystemCacheForDev: true,
     preloadEntriesOnStart: false,

scripts/run.sh

@@ -58,6 +58,12 @@ terminate() {
 
 trap terminate TERM INT
 
+# Enable source maps in Node.js when explicitly opted in.
+# Default off — see https://github.com/homarr-labs/homarr/issues/6123
+if [ "${HOMARR_ENABLE_SOURCE_MAPS}" = "true" ]; then
+  export NODE_OPTIONS="--enable-source-maps${NODE_OPTIONS:+ $NODE_OPTIONS}"
+fi
+
 node apps/nextjs/server.js &
 NEXTJS_PID=$!