Update synchronizer deployment guide

[coldice]

The synchronizer deployment guide (Deploying a Private Synchronizer) is very basic, it could be extended further.

Proposed updates: Deploying a Private Synchronizer

Target file: docs-main/global-synchronizer/extension-synchronizers/deployment.mdx
Context: Reviewer feedback (#622) on /global-synchronizer/extension-synchronizers/synchronizer-operations asked for a separate tutorial-style setup page. deployment.mdx is the right home for that walkthrough. Operations was reordered (configure → bootstrap → day-2) and now links here; this page is also in the Extension Synchronizers nav.

---

Current state (gaps)

The page is a short Helm-oriented draft:

1. Prerequisites (K8s/Helm-heavy)
2. Ordering backends (centralized Alpha vs BFT/CometBFT)
3. Database setup (high level)
4. Deploy sequencer / mediator via Helm values
5. Initialize (console snippet)
6. Connect validators (console + Helm)
7. Verification (brief)
8. Production considerations (bullets)

It does not yet work as a complete “how to set up a synchronizer” tutorial: little architecture guidance, no end-to-end Canton config story, thin verification, and weak cross-links into the operations reference.

---

Goals for the updated page

• One happy path a private/extension synchronizer operator can follow end to end.
• Clear decision points (what to choose and when), then deep-links into synchronizer-operations for variants.
• Align with the documented setup order: configure → start → bootstrap → connect → verify → (optional) harden.
• Stay CN/extension-synchronizer aware (vs Global Synchronizer / SV docs).

---

Proposed content updates

1. Positioning and audience

• Open with who this is for (operators deploying a private / extension synchronizer, not Global Synchronizer SV setup).
• One sentence contrasting this tutorial vs Synchronizer Operations (walkthrough vs reference).
• Link related concept pages: private synchronizers, hybrid pattern, linking validators to multiple synchronizers.

2. Architecture choice (enrich — do not only extract)

Add a short decision section before deploy steps:

Choose…	When…	Then follow…
Centralized, single-operator	One org owns sequencer + mediator	This tutorial’s default path
Decentralized / multi-owner	Distinct operators must co-sign topology	Ops: decentralized bootstrap
HA / multi-sequencer	Production redundancy	Ops: HA (+ this tutorial’s “next steps”)
Hybrid (private + Global Synchronizer)	Need CN connectivity as well	Hybrid pattern + linking multi-sync

Clarify ordering-backend wording so it matches current Canton product language (BFT sequencer vs legacy/centralized options) and keep the Alpha warning where still accurate.

3. Prerequisites (enrich)

Keep K8s/Helm path, but also call out:

• When a non-Helm / local Canton process path is acceptable (dev/test).
• Postgres sizing baseline (or link to production notes).
• TLS material expectations (public API).
• Console access to sequencer (and mediator if separate).
• Link to synchronizer overview / architecture.

4. Configure before deploy (enrich — pull framing from ops, not all snippets)

Insert an explicit Configure stage matching ops H1s:

1. Sequencer/mediator APIs (ports, addresses)
2. Sequencer backend (minimal BFT for the default path)
3. TLS on the public API
4. Storage (Postgres) — note that Canton configure/storage.rst is still thin/WIP; keep practical Helm/Postgres guidance here

Show one minimal, copy-pasteable config shape (Helm values and/or equivalent Canton config). Point to ops for peers, auth, dedicated storage, external sequencer, client auth, etc.

5. Deploy / start nodes

• Keep Helm install steps; verify they match real chart names/values (or mark as illustrative if charts are placeholders).
• Add “confirm pods/processes healthy / health endpoint” before bootstrap.
• Optional short non-Helm “start nodes with config file” note for readers not on K8s.

6. Bootstrap / initialize (light extract + framing)

• Keep the existing initialize snippet as the default centralized path.
• Explicitly say: nodes must be fresh and started; config must already include backend + APIs.
• Link out for decentralized, permissioned, and “subset of sequencers as owners” — do not inline those flows.
• After success: what identity/topology state the operator should expect.

7. Connect validators

• Keep console + Helm additionalSynchronizerConnections.
• Link linking a validator to multiple synchronizers for hybrid / multi-sync.
• Mention alias naming and reconnect after config changes if relevant.

8. Verification checklist (enrich)

Expand beyond a one-line ping / “create a contract”:

• Sequencer health HTTP 200
• Mediator registered in synchronizer topology
• participant.synchronizers.list_connected() (or equivalent)
• Participant ping across the synchronizer
• Optional: allocate party + create contract on the private synchronizer

9. Production / next steps (enrich lightly)

Keep TLS, network policy, monitoring, backups. Add outbound links:

• HA configuration
• Traffic management (if applicable to private sync)
• Pruning
• Backup and restore
• Synchronizer monitoring page

10. Nav / cross-links (already partly done)

• Page listed under Extension Synchronizers in docs.json (before operations).
• Operations page intro + bootstrap note link here.
• From this page, bidirectional links to operations sections (configure / bootstrap / HA).
• Confirm private-synchronizers “Deployment” related link still accurate after rewrite.

---

What to reuse vs rewrite

Reuse with light edits	Prefer rewrite / new prose
Helm values skeletons (after validating against real charts)	Intro, audience, decision table
Initialize + connect console snippets	Configure-before-bootstrap narrative
Alpha/production warning (if still true)	Verification checklist
High-level DB and TLS bullets	CN-specific hybrid / multi-sync glue

---

Suggested outline (target structure)

# Deploying a Private Synchronizer
## Who this guide is for
## Choose your topology (default vs advanced)
## Prerequisites
## 1. Configure APIs, backend, and TLS
## 2. Set up databases
## 3. Deploy and start sequencer and mediator
## 4. Bootstrap (initialize) the synchronizer
## 5. Connect validators
## 6. Verify the deployment
## Production hardening and next steps
## Related reference

---

Open questions before implementing

1. Default path: Confirm centralized + BFT (or Helm’s actual default backend) as the tutorial default.
2. Helm authenticity: Are canton/canton-sequencer / canton/canton-mediator and the sample values accurate for the docs audience, or do they need replacing with supported CN packaging?
3. CometBFT wording: Current “BFT with CometBFT” may need alignment with Canton BFT Orderer docs (bft-orderer page).
4. Scope: Tutorial only for private/extension sync, or also a short “when to use Global Synchronizer instead” callout?
5. Storage howto: Whether to wait on Canton configure/storage maturity or keep Postgres guidance local to this page.

---

Done when

• A new operator can configure → start → bootstrap → connect → verify on the default path without reading the full operations page first.
• Advanced variants are linked, not duplicated.
• Ops and deployment pages agree on setup order and cross-link cleanly.