Move V8 heap config to Dockerfile with --max-old-space-size-percentage (#60311)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

Dockerfile

@@ -1,7 +1,9 @@
 # This Dockerfile is used solely for production deployments to Moda
 # For building this file locally, see src/deployments/production/README.md
-# Environment variables are set in the Moda configuration:
+# Most environment variables are set in the Moda configuration:
 #   config/moda/configuration/*/env.yaml
+# V8 heap sizing is set here via NODE_OPTIONS and mirrored in
+# the Moda config files for defense-in-depth.
 
 # ---------------------------------------------------------------
 # BASE STAGE: Install linux dependencies and set up the node user
@@ -151,5 +153,11 @@ COPY --chown=node:node --from=precompute_stage $APP_HOME/.pageinfo-cache.json.br
 ARG BUILD_SHA
 ENV BUILD_SHA=$BUILD_SHA
 
+# V8 heap limit as a percentage of the container cgroup memory limit.
+# Uses --max-old-space-size-percentage (Node 24+) so the heap adapts
+# automatically when K8s memory limits change. 75% leaves ~25% headroom
+# for off-heap memory (Buffers, V8 code cache, libuv) and OS overhead.
+ENV NODE_OPTIONS="--max-old-space-size-percentage=75"
+
 # Entrypoint to start the server
 CMD ["node_modules/.bin/tsx", "src/frame/server.ts"]

config/kubernetes/default/deployments/webapp.yaml

@@ -32,9 +32,8 @@ spec:
               # Absolute minimum to start app is 4500Mi
               # Would increase with more pages, versions, or languages supported
               # The additional memory helps during traffic surges
-              # Keep ~600 MB headroom above --max-old-space-size in
-              # config/moda/configuration/default/env.yaml for Node
-              # off-heap memory and OS overhead.
+              # V8 heap is set to 75% of the cgroup memory limit via
+              # --max-old-space-size-percentage in the Dockerfile.
             limits:
               cpu: 8000m
               memory: 16Gi

config/kubernetes/production/deployments/webapp.yaml

@@ -34,9 +34,8 @@ spec:
               # Absolute minimum to start app is 4500Mi
               # Would increase with more pages, versions, or languages supported
               # The additional memory helps during traffic surges
-              # Keep ~600 MB headroom above --max-old-space-size in
-              # config/moda/configuration/production/env.yaml for Node
-              # off-heap memory and OS overhead.
+              # V8 heap is set to 75% of the cgroup memory limit via
+              # --max-old-space-size-percentage in the Dockerfile.
             limits:
               cpu: 16000m
               memory: 16Gi

config/moda/configuration/default/env.yaml

@@ -1,13 +1,9 @@
 data:
   MODA_APP_NAME: docs-internal
   NODE_ENV: production
-  # V8 heap limit (--max-old-space-size) should leave at least ~600 MiB
-  # below the K8s memory request for Node off-heap memory (Buffers,
-  # V8 code cache, libuv) and OS overhead. If you change the memory
-  # request in config/kubernetes/default/deployments/webapp.yaml,
-  # update this value to match.
-  # Current: 8.0 Gi (8192 MiB) request, 7168 MiB heap = 1024 MiB headroom
-  NODE_OPTIONS: '--max-old-space-size=7168'
+  # Matches the Dockerfile ENV. Both set the same value so that
+  # the heap limit is correct regardless of config-layering order.
+  NODE_OPTIONS: '--max-old-space-size-percentage=75'
   PORT: '4000'
   ENABLED_LANGUAGES: 'en,es,ja,pt,zh,ru,fr,ko,de'
   RATE_LIMIT_MAX: '21'

config/moda/configuration/production/env.yaml

@@ -1,13 +1,9 @@
 data:
   MODA_APP_NAME: docs-internal
   NODE_ENV: production
-  # V8 heap limit (--max-old-space-size) should leave at least ~600 MiB
-  # below the K8s memory request for Node off-heap memory (Buffers,
-  # V8 code cache, libuv) and OS overhead. If you change the memory
-  # request in config/kubernetes/production/deployments/webapp.yaml,
-  # update this value to match.
-  # Current: 8.0 Gi (8192 MiB) request, 7168 MiB heap = 1024 MiB headroom
-  NODE_OPTIONS: '--max-old-space-size=7168'
+  # Matches the Dockerfile ENV. Both set the same value so that
+  # the heap limit is correct regardless of config-layering order.
+  NODE_OPTIONS: '--max-old-space-size-percentage=75'
   PORT: '4000'
   ENABLED_LANGUAGES: 'en,es,ja,pt,zh,ru,fr,ko,de'
   RATE_LIMIT_MAX: '21'