Walkthrough

Added a new Node Renderer container deployment guide and updated documentation links; content documents deployment architectures, host binding, memory and performance tuning, autoscaling considerations, startup/error handling, observability, and troubleshooting.

Changes

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

I'm a rabbit in the docs with a nimble hop,
I leave a guide where container tips don't stop.
Sidecars, heaps, and worker counts to chart,
Logs and probes to keep the system smart,
🐇 Deploy with care — a tiny, happy hop!

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Greptile Summary

This PR adds a new container-deployment.md guide for deploying the Node Renderer in containerized environments, plus navigation links in docs/README.md and basics.md. The guide covers architecture options (sidecar vs. separate workloads), host binding, memory/worker tuning, autoscaling, error tracking, and troubleshooting — filling a real operational knowledge gap.

Key points:

• P1 logic error: The "Host Binding" section (line 70) incorrectly states that both sidecar and separate-workload configurations require 0.0.0.0 binding. For Kubernetes pods, sidecar containers share a network namespace and the default localhost binding works correctly. This contradicts the advantages listed for sidecars ("Rails connects to the renderer via localhost") and the Troubleshooting section (line 268) which correctly acknowledges localhost as the default for sidecars. The section needs to distinguish between Kubernetes pods (where localhost works for sidecars) and Docker Compose or separate workloads (where 0.0.0.0 is needed).
• Worker count formula: The /2 divisor in the sizing formula is unexplained. Since each worker handles one synchronous SSR request at a time, the rationale for halving the result should be documented so operators can calibrate it correctly for their workload.
• Minor: The ASCII pod diagram has a visual break in the outer boundary at the localhost junction (┘ should be ┴).

Confidence Score: 3/5

• Documentation-only PR, safe to merge but contains a technically incorrect claim about host binding for sidecar containers that should be corrected before publishing.
• The guide is well-structured and covers the topic thoroughly, but the host binding section contains incorrect guidance for Kubernetes sidecar deployments — claiming 0.0.0.0 is required when localhost is correct and sufficient. This is the canonical use case promoted throughout the document and the error could cause unnecessary security exposure or configuration confusion. The worker sizing formula also has an unexplained factor. No code is changed, so no runtime regressions are possible.
• docs/oss/building-features/node-renderer/container-deployment.md — host binding section (line 70) and worker count formula (line 134) need review.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Rails Container] -->|HTTP via localhost:3800| B[Node Renderer Container]
    B -->|SSR Response| A

    subgraph Sidecar Pod
        A
        B
    end

    subgraph "Separate Workload"
        C[Rails Workload] -->|HTTP via service DNS| D[Node Renderer Workload]
        D -->|SSR Response| C
    end

    subgraph "Node Renderer Internals"
        E[Master Process] -->|fork| F[Worker 1]
        E -->|fork| G[Worker 2]
        E -->|fork| H[Worker N]
        F -->|allWorkersRestartInterval| E
    end

    I[OOM / Container Restart] -->|Exit 137| J[cgroup OOM Kill]
    I -->|Exit 1| K[App Crash - check logs]

_{Last reviewed commit: "docs: add Node Rende..."}

Review: Node Renderer Container Deployment Guide

Good addition — this fills a real operational gap for teams running Node Renderer in containerized environments. The structure is clear and the troubleshooting section is practical. A few issues to address before merging:

Must-fix

1. ASCII diagram broken (line 27) — bottom border has two └ corners. Inline suggestion posted.

2. Host binding claim inaccurate for Kubernetes sidecars (line 70) — The guide states that 0.0.0.0 is required "in both sidecar and separate-workload configurations," but this is incorrect for Kubernetes. Containers within the same pod share a network namespace, so localhost binding works fine and is preferable from a security standpoint (avoids exposing the renderer on all interfaces). The 0.0.0.0 requirement only applies to separate workloads and Docker Compose setups without shared networking. Inline suggestion posted.

3. jemalloc LD_PRELOAD path is x86_64-only (line 177) — The hardcoded path /usr/lib/x86_64-linux-gnu/libjemalloc.so.2 silently fails on ARM containers (Graviton, Apple Silicon builds). Many production Kubernetes clusters now run ARM nodes. Inline suggestion posted.

Suggestions

• Worker formula /2 is unexplained (lines 135–141) — Readers will copy the formula but won't understand why dividing by 2 is correct. A sentence explaining the assumption (e.g., rendering is faster than a full request cycle, so each worker can handle N concurrent Rails threads) would help.

• Rolling restart config units not explicit (lines 151–155) — allWorkersRestartInterval and delayBetweenIndividualWorkerRestarts are in minutes; gracefulWorkerRestartTimeout is in seconds. The current comments say "6 hours" / "2 minutes" / "30 seconds" which is correct, but doesn't make the unit of the numeric value obvious. Inline suggestion posted.

Review: Node Renderer Container Deployment Guide

Good addition - this fills a real operational gap. Structure is clear, troubleshooting section is practical, and the architecture progression (single to sidecar to separate) is well motivated. A few issues to fix before merging:

Must-fix:

1. Host binding section is incorrect for Kubernetes sidecars (line 107). The guide claims 0.0.0.0 is required in both sidecar and separate-workload configurations, but this is wrong for Kubernetes pods. Containers in the same pod share a network namespace and the loopback interface, so Rails can reach a localhost-bound renderer without any binding change. 0.0.0.0 is only needed for (a) separate workloads (different pods) and (b) Kubernetes HTTP health probes, which the kubelet initiates from outside the pod network namespace. The current wording conflicts with the sidecar advantages (Rails still connects via localhost) and the troubleshooting section (line 305). Inline suggestion posted.

2. jemalloc LD_PRELOAD path is x86_64-only (line 214). The hardcoded path /usr/lib/x86_64-linux-gnu/libjemalloc.so.2 silently does nothing on ARM64 containers (AWS Graviton, arm64 CI runners). Many production Kubernetes clusters now run mixed or arm64 node pools. At minimum add a comment noting the arm64 path (/usr/lib/aarch64-linux-gnu/libjemalloc.so.2). Inline suggestion posted.

3. Broken ASCII border on sidecar diagram (line 59). The bottom boundary has two closing-corner characters where the first should be a T-junction to connect the localhost line. Inline suggestion posted.

Suggestions:

4. Worker formula /2 divisor is unexplained (lines 169-178). The implicit assumption is that each SSR render takes roughly half the time of a full Rails request, so one worker serves ~2 Rails threads. Without that sentence, operators will either copy the formula blindly or distrust it. Inline suggestion with proposed wording posted.

5. Rolling restart config units are implicit (lines 188-191). allWorkersRestartInterval and delayBetweenIndividualWorkerRestarts are in minutes; gracefulWorkerRestartTimeout is in seconds. The English comments are correct but the unit is not visible on the number itself. Inline suggestion adds explicit unit labels.

Verified:

• All linked files exist (js-configuration.md, error-reporting-and-tracing.md, heroku.md, js-memory-leaks.md, profiling-server-side-rendering-code.md, troubleshooting.md).
• The custom-fastify-configuration anchor referenced in the startup errors section exists in js-configuration.md.
• js-configuration.md confirms units: allWorkersRestartInterval = minutes, delayBetweenIndividualWorkerRestarts = minutes, gracefulWorkerRestartTimeout = seconds, consistent with the comments in the example.

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

PR Review: Node Renderer Container Deployment Guide

This is a high-quality, operationally useful documentation addition. The three-option architecture comparison, worker sizing formula, and OOM diagnosis workflow are genuinely valuable. All internal links verified as valid.

Issues requiring fixes before merge

1. Named import should be default import (copy-paste impact)

Line 111 uses { reactOnRailsProNodeRenderer } (named import), but every other doc in this directory and the package itself uses a default import. Users will copy-paste this and get a silent runtime failure.

2. Sidecar host binding is technically incorrect

The guide states that both sidecar and separate-workload configurations need 0.0.0.0 binding. This is wrong for sidecars: containers in the same Kubernetes pod share a network namespace and communicate over localhost — 0.0.0.0 is not required. The guide then contradicts itself in the Troubleshooting section (line 305) which correctly says sidecars can use localhost. Only separate-workload configurations truly need 0.0.0.0.

Minor issues worth addressing

• Mixed units in config block (lines 189-192): allWorkersRestartInterval is in minutes, gracefulWorkerRestartTimeout is in seconds — the code block does not call this out, which could confuse users who assume the same unit.
• Broken ASCII diagram (line 59): The sidecar diagram's bottom border has a stray └ in the middle of the line.
• Memory estimates need context (lines 135-137): The 500-600 MB figure is stated without specifying worker count or Node version, which could lead to incorrect resource planning.
• README section organization: The 5 new links are appended without subgrouping, mixing operational, reference, upgrade, and troubleshooting docs into an unstructured list.

size-limit report 📦

Review: Node Renderer Container Deployment Guide

Overall this is a well-structured and practically useful guide. The architecture decision tree, memory sizing tables, and troubleshooting section are solid. A few issues to address before merge:

1. Worker count formula — unexplained divisor

The formula divides by 2 without explanation. Readers will ask: why half? The implicit assumption seems to be that SSR workers handle requests faster than Rails threads (Node is async and SSR completes quickly relative to a full Rails request cycle), so fewer workers can serve the same throughput. If that is the reasoning, it should be stated — otherwise the formula looks arbitrary and users tuning for high-load systems may under-provision.

2. Missing readinessProbe in Kubernetes examples

The probe examples show startupProbe and livenessProbe but omit readinessProbe. In Kubernetes, readinessProbe is what prevents the pod from receiving traffic before the renderer is ready — livenessProbe only controls restarts. For the sidecar pattern, the renderer container needs a readiness probe so the pod is only added to service endpoints once both containers are ready.

3. prerender_caching default correction in basics.md — good catch

The PR correctly changes the old claim (the default of prerender_caching is true) to state the actual default is false. The code confirms DEFAULT_PRERENDER_CACHING = false. This is a real bug fix in the existing docs.

4. ASCII diagram label shared memory (minor)

In the Single Container diagram, the shared memory label inside the container box could be misread as shared-memory IPC between processes. The intent is presumably shared cgroup memory limit. A label like shared OS resources or simply removing it would be less ambiguous.

5. gracefulWorkerRestartTimeout comment (minor)

The inline comment says Kill stuck workers after 30 seconds but per the JS config docs, this timeout fires when a worker does not complete its graceful restart within the window — not when a worker is otherwise stuck. Something like Force-kill if graceful restart takes more than 30 seconds is more accurate.

6. README minimum version update

The change from Ruby >= 3.2 / Node >= 20 to Ruby >= 3.0 (package minimum; CI tested: 3.2-3.4) / Node >= 18 (package minimum; CI tested: 20-22) is a useful clarification that separates declared minimums from what is exercised in CI.

Links verified

All internal cross-references in container-deployment.md resolve to existing files: js-configuration.md, error-reporting-and-tracing.md, heroku.md, pro/js-memory-leaks.md, pro/profiling-server-side-rendering-code.md, pro/troubleshooting.md. The custom-fastify-configuration anchor in js-configuration.md also exists.

Review: docs/node-renderer-container-operations

Overall this is a well-structured, detailed operational guide. The architecture diagrams, resource tables, and troubleshooting steps are practical and clearly written. A few things worth addressing before merge:

Missing cross-reference: docs/pro/node-renderer.md "Further Reading" (not in this diff) doesn't link to the new guide. Anyone following the canonical Pro Node Renderer route will miss it. The links added to docs/README.md and basics.md are good, but node-renderer.md should have one too. Suggested line to add: - [Container deployment](../oss/building-features/node-renderer/container-deployment.md) — Sidecar vs. separate workloads, memory tuning, autoscaling, troubleshooting

Version bump scope: This PR bumps both gem versions from 16.5.0 to 16.5.1, but the CHANGELOG already has a 16.5.1 entry (dated 2026-03-27) covering unrelated bug fixes and this PR's doc additions aren't mentioned. If the bump is intentional, a brief changelog entry would keep the history complete.

Minor nits (filed inline):

• Worker count example uses a hardcoded '8' fallback that contradicts the documented auto-detect default (CPU count minus 1)
• Worker formula's / 2 divisor needs a one-line rationale
• Host-binding code example uses ESM import while the generator output and other examples in this doc set use CommonJS require
• The /health endpoint only checks that Fastify is up, not that workers are ready — worth a caveat given the startup race condition this very doc describes

Review posted via inline comments. See discussion threads on the PR for details on 4 issues: stale URL on line 3, Docker Compose localhost caveat on line 71, missing readinessProbe on lines 266-284, and restart interval units on lines 201-207.