Document Nexus with Global Namespaces (multi-region failover) for self-hosted by stephanos · Pull Request #4906 · temporalio/documentation

stephanos · 2026-07-17T01:06:43Z

WISOTT

Documents how Nexus Operation completion callbacks behave when a Global Namespace fails over between clusters, and the configuration required for worker-target endpoints: endpoint registry parity, replicated Namespaces, auto-forwarding, and a frontend httpPort plus advertised httpAddress on every cluster. Reorders "Build and use Nexus Services" above the new section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel · 2026-07-17T01:06:49Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
temporal-documentation	Ready	Preview, Comment	Jul 17, 2026 8:40pm

github-actions · 2026-07-17T01:07:15Z

📖 Docs PR preview links

Production Deployment
- Self Hosted Guide
  - Temporal Nexus

- Capitalize Temporal proper nouns (Cluster, Namespace, Workflow, Worker, Task Queue, Endpoint, Nexus Operation) to match sibling multi-cluster docs. - Replace em-dashes with plain punctuation; drop "e.g."/"via" per style guide. - Add that caller and handler Namespaces can be active on different Clusters (per-Namespace active cluster), so cross-Cluster completion forwarding is a steady state, handled automatically once httpAddress is advertised. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Move the target-type scope into a note that also mentions external-target Endpoints (--target-url) for completeness. - Vale pass: fix Worker casing, use contractions, split the long intro sentence, and use "automatic forwarding" instead of "auto-forwarding". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…tion - Split auto-forwarding into its two required parts: the static dcRedirectionPolicy (defaults to no redirection) and the per-Namespace system.enableNamespaceNotActiveAutoForwarding dynamic config. - Trim the httpAddress step to the Nexus-specific delta (httpPort + httpAddress) and defer base clusterMetadata/rpcAddress setup to the Multi-Cluster Replication page it links to. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ion entry - Link dcRedirectionPolicy to references/configuration, its canonical entry. - Clarify that the per-Cluster clusterInformation entry already contains the replication fields (enabled, rpcName, rpcAddress, initialFailoverVersion) and that httpAddress is added to it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Step 3 repeated the httpPort/httpAddress config already shown in Enable Nexus. Reference that section and keep only the multi-cluster delta: set them on every Cluster, plus the operator cluster upsert caveat. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Compress the 'What to expect on failover' list from five verbose bullets to four, folding the async-replication caveat into the permanent-loss point. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

It conflated the dynamic cluster-connection flow with the static-config instruction; httpAddress is set in static clusterInformation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Explain system.enableNamespaceNotActiveAutoForwarding (per-Namespace, defaults to true) and note it has the opposite default of dcRedirectionPolicy. - Redraw the failover sequence so replication (not a failover-time handoff) carries state to Cluster B; remove the misleading A->B arrow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Remove semicolon from a sequence-diagram Note (mermaid treats ; as a statement separator, causing a render-time parse error). - Reword enableNamespaceNotActiveAutoForwarding as 'make sure it isn't turned off' since it defaults to true. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Drop the literal quotes and wrap the replication note across two lines so the Note-over box doesn't overflow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Nexus forwarding is on by default (enableNamespaceNotActiveAutoForwarding). dcRedirectionPolicy is an optional client-API convenience, not a requirement (default noop; not mandated by the multi-cluster docs). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The CI mermaid linter parses headless (no DOM) and can't handle sequence 'box'. A flowchart with subgraphs shows the same Cluster boxes containing the Namespaces and passes the linter. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

lint-mermaid runs mermaid.parse() headless, which fails on syntaxes that need browser DOM APIs (e.g. sequence-diagram 'box': 'window is not defined'). Set up a jsdom DOM before loading mermaid, and add jsdom as a devDependency (it was only a transitive dep before). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Use the sequence diagram with Cluster boxes (now that the linter parses it). - dcRedirectionPolicy: mention selected-apis-forwarding forwards StartNexusOperationExecution for standalone Nexus Operations. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

stephanos · 2026-07-17T20:30:48Z

+   default via `system.enableNamespaceNotActiveAutoForwarding` (per-Namespace
+   dynamic config).
+
+   Optionally, set the server's


I wasn't sure if this should be optional or recommended?

Replace the manual jsdom global-copy loop with a one-line 'import global-jsdom/register'. (jsdom-global is unmaintained and doesn't expose the globals mermaid's box syntax needs; global-jsdom does.) Swap the direct jsdom devDependency for global-jsdom. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

stephanos · 2026-07-17T20:33:29Z

+// Set up a browser-like DOM before loading mermaid. mermaid.parse() uses DOM
+// APIs for some diagram syntaxes (for example a sequence diagram `box`) and
+// otherwise fails headless with "window is not defined".
+import 'global-jsdom/register';


This was needed to make the mermaid chart above work; the box is crucial to convey the topology clearly.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview July 17, 2026 01:07 View deployment

stephanos and others added 2 commits July 17, 2026 07:49

Update temporal-nexus.mdx

4ac3d82

vercel Bot deployed to Preview July 17, 2026 14:53 View deployment

vercel Bot deployed to Preview July 17, 2026 15:07 View deployment

vercel Bot deployed to Preview July 17, 2026 15:17 View deployment

vercel Bot deployed to Preview July 17, 2026 18:25 View deployment

Update temporal-nexus.mdx

b9b66c8

vercel Bot deployed to Preview July 17, 2026 18:28 View deployment

stephanos and others added 4 commits July 17, 2026 11:36

Tighten failover behavior bullets

1276f5e

Compress the 'What to expect on failover' list from five verbose bullets to four, folding the async-replication caveat into the permanent-loss point. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Shorten the httpAddress configuration step

87d8e8e

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Update temporal-nexus.mdx

88f2f08

vercel Bot deployed to Preview July 17, 2026 18:40 View deployment

stephanos and others added 2 commits July 17, 2026 11:41

Drop operator cluster upsert caveat from httpAddress step

bd91b56

It conflated the dynamic cluster-connection flow with the static-config instruction; httpAddress is set in static clusterInformation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Update temporal-nexus.mdx

af98ee2

vercel Bot deployed to Preview July 17, 2026 18:44 View deployment

vercel Bot deployed to Preview July 17, 2026 18:46 View deployment

stephanos and others added 2 commits July 17, 2026 11:47

Fix cut-off note in failover diagram

70e982c

Drop the literal quotes and wrap the replication note across two lines so the Note-over box doesn't overflow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview July 17, 2026 18:49 View deployment

vercel Bot deployed to Preview July 17, 2026 18:50 View deployment

Update temporal-nexus.mdx

030e6e3

Update temporal-nexus.mdx

b2e663d

vercel Bot deployed to Preview July 17, 2026 19:57 View deployment

stephanos and others added 8 commits July 17, 2026 12:57

Update temporal-nexus.mdx

3c2a9dc

Update temporal-nexus.mdx

7dd7098

Update temporal-nexus.mdx

62a080e

Update temporal-nexus.mdx

b40a311

Update temporal-nexus.mdx

3d71d3e

Update temporal-nexus.mdx

9d37e2f

Update temporal-nexus.mdx

7f04fe6

vercel Bot deployed to Preview July 17, 2026 20:04 View deployment

vercel Bot deployed to Preview July 17, 2026 20:21 View deployment

stephanos and others added 2 commits July 17, 2026 13:26

vercel Bot deployed to Preview July 17, 2026 20:29 View deployment

stephanos added 2 commits July 17, 2026 13:30

Update temporal-nexus.mdx

f7576ed

Update temporal-nexus.mdx

668317e

stephanos commented Jul 17, 2026

View reviewed changes

stephanos and others added 5 commits July 17, 2026 13:34

Update temporal-nexus.mdx

05e3d32

Clarify the advertise-httpAddress step

ff720fd

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Reword step 2 so the reader is the actor, not the section

6ee1921

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Update temporal-nexus.mdx

251345f

Update temporal-nexus.mdx

87a5226

vercel Bot deployed to Preview July 17, 2026 20:40 View deployment

stephanos marked this pull request as ready for review July 17, 2026 20:45

stephanos requested a review from a team as a code owner July 17, 2026 20:45

stephanos requested a review from bergundy July 17, 2026 20:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Document Nexus with Global Namespaces (multi-region failover) for self-hosted#4906

Document Nexus with Global Namespaces (multi-region failover) for self-hosted#4906
stephanos wants to merge 54 commits into
mainfrom
stephan/self-hosted-nexus-global-namespaces

stephanos commented Jul 17, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 17, 2026

Uh oh!

stephanos Jul 17, 2026 •

edited

Loading

Uh oh!

stephanos Jul 17, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

stephanos commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 17, 2026

📖 Docs PR preview links

Uh oh!

stephanos Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephanos Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

stephanos commented Jul 17, 2026 •

edited

Loading

vercel Bot commented Jul 17, 2026 •

edited

Loading

stephanos Jul 17, 2026 •

edited

Loading

stephanos Jul 17, 2026 •

edited

Loading