Revamp deployment guides with dedicated path pages#6002
Revamp deployment guides with dedicated path pages#6002Lakshan-Banneheke wants to merge 2 commits intowso2:masterfrom
Conversation
WalkthroughThis PR introduces a comprehensive deployment path selection guide for WSO2 Identity Server by adding a new chooser page and four deployment-specific documentation guides covering evaluation, production single-region HA, multi-region disaster recovery, and container platforms. It restructures the mkdocs navigation to prioritize deployment path selection and updates Vale vocabulary configuration. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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 Tip CodeRabbit can use your project's `biome` configuration to improve the quality of JS/TS/CSS/JSON code reviews.Add a configuration file to your project to customize how CodeRabbit runs |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
.vale/styles/config/vocabularies/vocab/accept.txt (1)
48-49: Remove redundantfailovervocabulary entries.
[Ff]ailoveralready covers lowercase and capitalized forms, so keeping both entries is redundant maintenance overhead.♻️ Suggested cleanup
failover -[Ff]ailover +[Ff]ailover🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.vale/styles/config/vocabularies/vocab/accept.txt around lines 48 - 49, Remove the redundant plain "failover" entry from the vocabulary file since the regex "[Ff]ailover" already matches both lowercase and capitalized forms; keep only "[Ff]ailover" and delete the duplicate "failover" line to avoid maintenance overhead.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@en/identity-server/next/docs/deploy/choose-your-deployment-path.md`:
- Around line 45-46: The Path D description contains a double period at the end
("management.."); edit the text in the choose-your-deployment-path.md file to
replace "management.." with a single period so the sentence ends with
"management." (locate the Path D / "management.." string and correct it).
In `@en/identity-server/next/docs/deploy/deployment-paths/evaluation.md`:
- Around line 26-27: Replace the inconsistent heading text "Pre-requisites" with
the standardized term "Prerequisites" in the document (look for the
HTML/Markdown cell containing <td><b>Pre-requisites</b></td> and update to
<td><b>Prerequisites</b></td>) and apply the same exact replacement across the
other new deployment path pages to ensure terminology consistency.
- Line 36: Replace the verb phrase "sign in" with the repository-standard "log
in" in the sentence that currently reads "WSO2 Identity Server starts, and you
can sign in to the Console at `https://localhost:9443/console`." Update that
sentence to use "log in" (e.g., "you can log in to the Console at
`https://localhost:9443/console`.") to match the repository convention of using
"log in" for verbs and "login" for nouns/adjectives.
In `@en/identity-server/next/docs/deploy/deployment-paths/production-dr.md`:
- Line 38: The sentence containing "RTO" and "RPO" uses unexplained acronyms;
update that sentence (the table cell text "Each region operates independently
during normal conditions. Failover to a secondary region completes within the
defined RTO. Data consistency meets the defined RPO.") to expand the acronyms on
first use (e.g., "RTO (recovery time objective)" and "RPO (recovery point
objective)") so readers unfamiliar with DR terminology see the definitions
inline.
In `@en/identity-server/next/docs/deploy/deployment-paths/production-ha.md`:
- Line 57: The summary line "Configure clustering and the membership scheme"
currently restricts options by listing "WKA, AWS EC2"; update that text to
present those as examples (e.g., "WKA, AWS EC2") or use phrasing like "such as
WKA and AWS EC2" so it doesn't conflict with the full list in the linked
"clustering-related-configurations" section—locate the string "Configure
clustering and the membership scheme" and replace the hardcoded "WKA, AWS EC2"
portion accordingly.
---
Nitpick comments:
In @.vale/styles/config/vocabularies/vocab/accept.txt:
- Around line 48-49: Remove the redundant plain "failover" entry from the
vocabulary file since the regex "[Ff]ailover" already matches both lowercase and
capitalized forms; keep only "[Ff]ailover" and delete the duplicate "failover"
line to avoid maintenance overhead.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 81f3d017-1393-49ea-bc3d-cb6037a28a60
📒 Files selected for processing (7)
.vale/styles/config/vocabularies/vocab/accept.txten/identity-server/next/docs/deploy/choose-your-deployment-path.mden/identity-server/next/docs/deploy/deployment-paths/containers.mden/identity-server/next/docs/deploy/deployment-paths/evaluation.mden/identity-server/next/docs/deploy/deployment-paths/production-dr.mden/identity-server/next/docs/deploy/deployment-paths/production-ha.mden/identity-server/next/mkdocs.yml
| A containerized, orchestrated deployment on Kubernetes or OpenShift with automated scaling, rolling updates, and declarative configuration management.. | ||
|
|
There was a problem hiding this comment.
Fix punctuation typo in Path D description.
Line 45 ends with management..; please remove the extra period.
✏️ Suggested wording fix
-A containerized, orchestrated deployment on Kubernetes or OpenShift with automated scaling, rolling updates, and declarative configuration management..
+A containerized, orchestrated deployment on Kubernetes or OpenShift with automated scaling, rolling updates, and declarative configuration management.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| A containerized, orchestrated deployment on Kubernetes or OpenShift with automated scaling, rolling updates, and declarative configuration management.. | |
| A containerized, orchestrated deployment on Kubernetes or OpenShift with automated scaling, rolling updates, and declarative configuration management. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@en/identity-server/next/docs/deploy/choose-your-deployment-path.md` around
lines 45 - 46, The Path D description contains a double period at the end
("management.."); edit the text in the choose-your-deployment-path.md file to
replace "management.." with a single period so the sentence ends with
"management." (locate the Path D / "management.." string and correct it).
| <td><b>Pre-requisites</b></td> | ||
| <td> |
There was a problem hiding this comment.
Use “Prerequisites” consistently.
Line 26 uses “Pre-requisites”. Please standardize to “Prerequisites” (and mirror the same fix in the other new path pages for consistency).
✏️ Suggested wording fix
-<td><b>Pre-requisites</b></td>
+<td><b>Prerequisites</b></td>As per coding guidelines, "Use one term per concept; do not switch terminology mid-document or randomly mix expanded and abbreviated forms."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@en/identity-server/next/docs/deploy/deployment-paths/evaluation.md` around
lines 26 - 27, Replace the inconsistent heading text "Pre-requisites" with the
standardized term "Prerequisites" in the document (look for the HTML/Markdown
cell containing <td><b>Pre-requisites</b></td> and update to
<td><b>Prerequisites</b></td>) and apply the same exact replacement across the
other new deployment path pages to ensure terminology consistency.
| </tr> | ||
| <tr> | ||
| <td><b>Exit criteria</b></td> | ||
| <td>WSO2 Identity Server starts, and you can sign in to the Console at <code>https://localhost:9443/console</code>.</td> |
There was a problem hiding this comment.
Use repository-standard login verb form.
Line 36 uses “sign in”; this repository convention is “log in” (verb) and “login” (noun/adjective).
✏️ Suggested wording fix
-<td>WSO2 Identity Server starts, and you can sign in to the Console at <code>https://localhost:9443/console</code>.</td>
+<td>WSO2 Identity Server starts, and you can log in to the Console at <code>https://localhost:9443/console</code>.</td>Based on learnings: use 'log in' as the verb and 'login' as the noun/adjective consistently across Markdown documentation in this repository.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <td>WSO2 Identity Server starts, and you can sign in to the Console at <code>https://localhost:9443/console</code>.</td> | |
| <td>WSO2 Identity Server starts, and you can log in to the Console at <code>https://localhost:9443/console</code>.</td> |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@en/identity-server/next/docs/deploy/deployment-paths/evaluation.md` at line
36, Replace the verb phrase "sign in" with the repository-standard "log in" in
the sentence that currently reads "WSO2 Identity Server starts, and you can sign
in to the Console at `https://localhost:9443/console`." Update that sentence to
use "log in" (e.g., "you can log in to the Console at
`https://localhost:9443/console`.") to match the repository convention of using
"log in" for verbs and "login" for nouns/adjectives.
| </tr> | ||
| <tr> | ||
| <td><b>Exit criteria</b></td> | ||
| <td>Each region operates independently during normal conditions. Failover to a secondary region completes within the defined RTO. Data consistency meets the defined RPO.</td> |
There was a problem hiding this comment.
Define RTO and RPO on first use.
Line 38 introduces RTO and RPO without expansion, which can reduce clarity for readers new to DR terminology.
✏️ Suggested wording fix
-<td>Each region operates independently during normal conditions. Failover to a secondary region completes within the defined RTO. Data consistency meets the defined RPO.</td>
+<td>Each region operates independently during normal conditions. Failover to a secondary region completes within the defined recovery time objective (RTO). Data consistency meets the defined recovery point objective (RPO).</td>As per coding guidelines, "Define acronyms on first use unless universally known."
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <td>Each region operates independently during normal conditions. Failover to a secondary region completes within the defined RTO. Data consistency meets the defined RPO.</td> | |
| <td>Each region operates independently during normal conditions. Failover to a secondary region completes within the defined recovery time objective (RTO). Data consistency meets the defined recovery point objective (RPO).</td> |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@en/identity-server/next/docs/deploy/deployment-paths/production-dr.md` at
line 38, The sentence containing "RTO" and "RPO" uses unexplained acronyms;
update that sentence (the table cell text "Each region operates independently
during normal conditions. Failover to a secondary region completes within the
defined RTO. Data consistency meets the defined RPO.") to expand the acronyms on
first use (e.g., "RTO (recovery time objective)" and "RPO (recovery point
objective)") so readers unfamiliar with DR terminology see the definitions
inline.
| 3. [Change the hostname]({{base_path}}/deploy/change-the-hostname) to your production hostname. | ||
| 4. [Configure TLS]({{base_path}}/deploy/security/configure-transport-level-security) for transport-level security. | ||
| 5. [Separate keystores]({{base_path}}/deploy/security/keystores/) for signing, encryption, and TLS. | ||
| 6. [Configure clustering and the membership scheme]({{base_path}}/deploy/deployment-guide#clustering-related-configurations) (WKA, AWS EC2). |
There was a problem hiding this comment.
Avoid over-restricting clustering scheme options in the summary.
Line 57 currently lists only WKA, AWS EC2, while the linked clustering reference includes additional schemes. Consider phrasing these as examples to avoid mismatch with en/identity-server/next/docs/deploy/deployment-guide.md.
✏️ Suggested wording fix
-6. [Configure clustering and the membership scheme]({{base_path}}/deploy/deployment-guide#clustering-related-configurations) (WKA, AWS EC2).
+6. [Configure clustering and the membership scheme]({{base_path}}/deploy/deployment-guide#clustering-related-configurations) (for example, WKA or AWS membership).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 6. [Configure clustering and the membership scheme]({{base_path}}/deploy/deployment-guide#clustering-related-configurations) (WKA, AWS EC2). | |
| 6. [Configure clustering and the membership scheme]({{base_path}}/deploy/deployment-guide#clustering-related-configurations) (for example, WKA or AWS membership). |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@en/identity-server/next/docs/deploy/deployment-paths/production-ha.md` at
line 57, The summary line "Configure clustering and the membership scheme"
currently restricts options by listing "WKA, AWS EC2"; update that text to
present those as examples (e.g., "WKA, AWS EC2") or use phrasing like "such as
WKA and AWS EC2" so it doesn't conflict with the full list in the linked
"clustering-related-configurations" section—locate the string "Configure
clustering and the membership scheme" and replace the hardcoded "WKA, AWS EC2"
portion accordingly.
1 participant
Summary
deploy/deployment-paths/with detailed overviews, prerequisites, key steps, and next steps for each path.mkdocs.ymlnavigation to reflect the new structure, reorganizing the Setup section for clarity.hostnames,keystores,vCPUs,failover,liveness) to the Vale vocabulary accept list.Test plan
mkdocs build).Summary by CodeRabbit