Revamp deployment guides with dedicated path pages#6002
Open
Lakshan-Banneheke wants to merge 4 commits intowso2:masterfrom
Open
Revamp deployment guides with dedicated path pages#6002Lakshan-Banneheke wants to merge 4 commits intowso2:masterfrom
Lakshan-Banneheke wants to merge 4 commits intowso2:masterfrom
Conversation
Contributor
WalkthroughAdded a deployment-path chooser and four full deployment guides (Evaluation, Production HA, Production DR, Containers), extensive complete-guide and include pages for each path, restructured MkDocs navigation, updated Vale accepted vocabulary, and added CSS for deployment-path cards. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
⚔️ Resolve merge conflicts
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[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
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
en/identity-server/next/docs/deploy/choose-your-deployment-path.md
Outdated
Show resolved
Hide resolved
Comment on lines
+26
to
+27
| <td><b>Pre-requisites</b></td> | ||
| <td> |
Contributor
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> |
Contributor
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.
Suggested change
| <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> |
Contributor
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.
Suggested change
| <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). |
Contributor
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.
Suggested change
| 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.
Added complete guides for deployment paths
Contributor
There was a problem hiding this comment.
Actionable comments posted: 15
🧹 Nitpick comments (7)
en/includes/complete-guides/deploy-ha/prerequisites.md (1)
10-10: Consider expanding the RDBMS acronym.While RDBMS is widely understood in IT contexts, the coding guidelines recommend defining acronyms on first use unless universally known (with examples: API, URL, JSON, HTTP). Expanding to "Relational Database Management System (RDBMS)" on first use would ensure full compliance.
📝 Proposed expansion
-- An external RDBMS: PostgreSQL, MySQL, Oracle, MSSQL, or MariaDB +- An external Relational Database Management System (RDBMS): PostgreSQL, MySQL, Oracle, MSSQL, or MariaDBAs per coding guidelines: "Define acronyms on first use unless universally known (API, URL, JSON, HTTP)."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/includes/complete-guides/deploy-ha/prerequisites.md` at line 10, Update the phrase "An external RDBMS: PostgreSQL, MySQL, Oracle, MSSQL, or MariaDB" to define the acronym on first use by rewriting it as "An external Relational Database Management System (RDBMS): PostgreSQL, MySQL, Oracle, MSSQL, or MariaDB" so the term "Relational Database Management System (RDBMS)" appears fully expanded before subsequent uses..vale/styles/config/vocabularies/vocab/accept.txt (1)
48-49: Remove redundantfailovervocabulary entry.
failoverand[Ff]ailoveroverlap. Keep one form to avoid duplicate maintenance.Proposed cleanup
-failover [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 duplicate vocabulary entry by keeping only one of the two lines ("failover" or "[Ff]ailover") in the vocabulary file; decide which form you prefer (case-insensitive regex "[Ff]ailover" if you need to match both cases, or the lowercase "failover" for a canonical entry) and delete the other line so the file contains a single, non-redundant entry.en/includes/complete-guides/deploy-eval/introduction.md (1)
36-38: Tighten repeated bullet phrasing for readability.The three bullets repeat the same opening. Consider parallel action verbs to make scanning faster.
As per coding guidelines "Use plain language and short sentences."Possible rewrite
-- You want to test WSO2 Identity Server features in a local environment. -- You need to build a proof of concept or demo. -- You want to familiarize yourself with the product before planning a production deployment. +- Test WSO2 Identity Server features in a local environment. +- Build a proof of concept or demo. +- Familiarize yourself with the product before planning a production deployment.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/includes/complete-guides/deploy-eval/introduction.md` around lines 36 - 38, Replace the three repeated-opening bullets with concise, parallel action-verb phrases for clarity: change the lines "- You want to test WSO2 Identity Server features in a local environment.", "- You need to build a proof of concept or demo.", and "- You want to familiarize yourself with the product before planning a production deployment." to e.g. "Test WSO2 Identity Server locally.", "Build a proof-of-concept or demo.", and "Familiarize yourself with the product before planning a production deployment." Use plain language and short sentences to match the style guide.en/identity-server/next/docs/complete-guides/deploy-containers/configure-keystores.md (2)
6-6: Reduce duplication with the included content.Line 6 duplicates the three-keystore recommendation (token signing, data encryption, TLS) that is already comprehensively covered in the included
keystores/index.mdfile under "Recommendations for setting up keystores." The include provides the same separation rationale plus detailed configuration guidance. Consider simplifying this wrapper to focus only on the container-specific context (mounting as Secrets rather than baking into images) and let the include handle the keystore separation details.♻️ Proposed streamlined introduction
-Create separate keystores for token signing, data encryption, and TLS. Mount these into your pods as Kubernetes Secrets — never bake keystore files into container images. +Mount keystores into your pods as Kubernetes Secrets — never bake keystore files into container images. The included guide covers keystore types and separation recommendations.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/complete-guides/deploy-containers/configure-keystores.md` at line 6, The sentence duplicating "Create separate keystores for token signing, data encryption, and TLS" should be removed and replaced with a concise container-specific note that references the included guidance: keep only a single line stating that keystores must be mounted into pods as Kubernetes Secrets (do not bake into images) and rely on the included file keystores/index.md ("Recommendations for setting up keystores") for the separation rationale and detailed configuration; update the surrounding text to reference that include so readers are directed to the comprehensive guidance while the wrapper focuses solely on container-secret handling.
9-9: Remove redundant mention of keytool availability.The included
keystores/index.mdfile already provides comprehensive keytool commands and usage instructions (including format conversion and keystore creation). Mentioning keytool availability here duplicates that content without adding container-specific value.♻️ Proposed simplification
- TLS is configured (previous step complete). The JDK `keytool` utility is available to generate keystores locally before mounting them as Secrets. + TLS is configured (previous step complete). You have generated the required keystores locally and are ready to mount them as Secrets.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/complete-guides/deploy-containers/configure-keystores.md` at line 9, Remove the redundant sentence that states "The JDK `keytool` utility is available to generate keystores locally before mounting them as Secrets" from configure-keystores.md; instead add a single cross-reference line pointing readers to keystores/index.md for keytool commands and conversion steps (or, if container-specific guidance is needed, replace the sentence with a short note about mounting pre-built keystores into containers and link to keystores/index.md for command examples).en/identity-server/next/docs/complete-guides/deploy-eval/install.md (1)
6-11: Clarify scope around the shared install include for evaluation pathThe page says no external database setup is needed, but the included install content also discusses production DBMS choices. Consider adding a short scoping line before/after the include so evaluation readers do not treat production DB guidance as required here.
As per coding guidelines "Avoid unnecessary background information, repetition, conceptual digressions unrelated to the task, and sections with no actionable value in documentation."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/complete-guides/deploy-eval/install.md` around lines 6 - 11, Add a concise scoping sentence immediately before or after the include "{% include \"../../deploy/get-started/install.md\" %}" clarifying that this evaluation guide uses the embedded H2 database and that any production DBMS configuration described in the included install content is optional and only required for production deployments; reference the evaluation path and explicitly tell readers they can skip production DB setup for this tutorial.en/identity-server/next/mkdocs.yml (1)
970-974: Surface the new path overview pages in the sidebar.Lines 970-974 and 1434-1479 point users straight to
complete-guides/.../introduction.md, so the newdeploy/deployment-paths/*.mdpages are not reachable from sidebar navigation. That skips the overview layer this PR adds and makesDeployment pathsfeel like a second guide entry point instead of the canonical path chooser pages.As per coding guidelines, "Use descriptive link text for internal links and prefer linking to canonical pages (overview or primary reference); avoid linking to unstable or temporary resources".Suggested nav shape
- Deployment paths: - - "Path A: Evaluation (single node)": complete-guides/deploy-eval/introduction.md - - "Path B: Production (single region, HA)": complete-guides/deploy-ha/introduction.md - - "Path C: Production (multi-region, DR)": complete-guides/deploy-dr/introduction.md - - "Path D: Container platforms (Kubernetes and OpenShift)": complete-guides/deploy-containers/introduction.md + - "Path A: Evaluation (single node)": deploy/deployment-paths/evaluation.md + - "Path B: Production (single region, HA)": deploy/deployment-paths/production-ha.md + - "Path C: Production (multi-region, DR)": deploy/deployment-paths/production-dr.md + - "Path D: Container platforms (Kubernetes and OpenShift)": deploy/deployment-paths/containers.md- Deployment guides: - "Path A: Evaluation (single node)": + - Overview: deploy/deployment-paths/evaluation.md - Introduction: complete-guides/deploy-eval/introduction.mdApply the same
Overviewchild entry for Paths B-D.Also applies to: 1434-1479
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/mkdocs.yml` around lines 970 - 974, The sidebar currently links each "Path A/B/C/D" entry directly to complete-guides/.../introduction.md; update the "Deployment paths" nav entries in mkdocs.yml so each Path (Path A, Path B, Path C, Path D) points to its new canonical overview page under deploy/deployment-paths/*.md (e.g., deploy/deployment-paths/path-b-overview.md) instead of the complete-guides intro, and add an "Overview" child entry under Paths B–D (matching Path A's shape) so the overview layer is surfaced for all paths; modify the nav entries named "Deployment paths" and the individual "Path B", "Path C", "Path D" items accordingly.
🤖 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/complete-guides/deploy-containers/change-hostname.md`:
- Around line 11-14: The shared include
("../../../../../includes/deploy/change-the-hostname.md") is generic; add a
container-specific addendum around it that provides concrete, sequential steps
for Kubernetes/OpenShift: (1) edit or patch the ConfigMap containing
deployment.toml (refer to the ConfigMap name used by the app) or update the
mounted file, (2) apply the change (kubectl/oc apply or kubectl patch), (3)
trigger a rolling restart of the Deployment/StatefulSet/Pod (kubectl rollout
restart or oc rollout) so containers pick up the new mounted config, and (4)
verify inside the running pod that deployment.toml contains the updated hostname
and the service responds (kubectl exec + cat/grep and curl). Insert these steps
before or after the existing "Verify" tip and reference the file name
deployment.toml and the ConfigMap/mount so readers can follow exact commands for
containerized deployments.
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/configure-tls.md`:
- Line 6: The page introduces Kubernetes-specific TLS concerns but the included
configure-transport-level-security.md only covers generic filesystem edits; add
a Kubernetes-specific supplement that explains Ingress TLS termination vs
passthrough modes, how to store and manage certificates as Kubernetes Secrets,
patterns for mounting certificates into Identity Server pods (or using projected
volumes), and how to apply deployment.toml or other runtime configuration via
ConfigMaps/Secrets for containerized deployments; update the page to link to the
new supplement and/or create an issue to include this container-platform
guidance in the shared TLS documentation.
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/deploy-on-kubernetes.md`:
- Line 6: The page description incorrectly claims the guide covers manual
Deployment/Service manifests and ConfigMap editing, while the actual content
(deploy-is-on-kubernetes.md) uses a Helm chart; update the single-line summary
to state that this guide demonstrates deploying WSO2 Identity Server to
Kubernetes using the provided Helm chart (which abstracts underlying manifests),
remove or rephrase references to "writing the Deployment and Service manifests"
and "configuring the ConfigMap for `deployment.toml`" and instead mention
configuring Helm values and exposing the service via the chart’s Ingress
configuration.
- Line 14: Replace the phrase "sign in" with "log in" in the sentence that reads
"Run `kubectl get pods -n <namespace>` and confirm all WSO2 Identity Server pods
reach `Running` status. Then open `https://<hostname>/console` and sign in with
admin credentials." to match repository terminology (use "log in" as the verb
and "login" as noun/adjective elsewhere); update only the verb to "log in with
admin credentials" so the rest of the sentence and code snippets remain
unchanged.
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/deploy-on-openshift.md`:
- Line 6: The page description incorrectly implies manual manifest-level
OpenShift configuration (mentioning "restricted pod security contexts" and
"requirement to use Routes instead of Ingress resources"); update the summary to
state that deployment uses a Helm chart (reference deploy-is-on-openshift.md)
which abstracts OpenShift specifics and handles Routes/security contexts for
you, and rephrase the sentence to mention Helm-based deployment and that the
chart adapts to OpenShift rather than instructing users to manually configure
pod security contexts or Routes.
- Line 14: Replace the phrase "sign in" with "log in" in the sentence "Open
`https://<hostname>/console` and sign in with admin credentials" to align with
repository terminology; update the text to "Open `https://<hostname>/console`
and log in with admin credentials" and scan nearby documentation in this file
for any other occurrences of "sign in" to change to "log in" (keeping "login" as
the noun/adjective where applicable).
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/security-hardening.md`:
- Around line 6-11: The paragraph that claims "On Kubernetes, also review pod
security contexts, network policies, and RBAC rules" is misleading because the
included file {% include "../../deploy/security/security-guidelines/index.md" %}
lacks Kubernetes-specific guidance; either add Kubernetes hardening content (a
new include or section covering podSecurityContext examples, NetworkPolicy
patterns, and RBAC role/rolebinding recommendations) and reference it here, or
remove/soften the Kubernetes claim and instead link to a dedicated Kubernetes
hardening include (e.g., create and include
../../deploy/security/security-guidelines/kubernetes.md) so the statement
matches the actual content.
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/verify-deployment.md`:
- Line 14: Replace the two occurrences of "sign in" in the sentence that
references "https://<hostname>/console" with the repository-standard verb "log
in" (keeping "login" as noun/adjective elsewhere); update both phrases so it
reads e.g. "log in to `https://<hostname>/console` with admin credentials, then
test a user log in through a connected application" to ensure consistent
terminology across the document.
In `@en/identity-server/next/docs/complete-guides/deploy-dr/change-hostname.md`:
- Around line 6-11: The page's text describes region-specific per-node hostnames
but still pulls in the generic single-hostname include ("{% include
../../../../../includes/deploy/change-the-hostname.md %}"), causing a mismatch;
update the page so the behavior and verification match by either (a) replacing
that include with a DR-specific include that documents per-region hostname
values and verification steps, or (b) editing the surrounding copy to describe
the single shared-hostname flow and expected verification criteria to match the
included file; search for the include string and the surrounding paragraphs
("Set the production hostname..." and the note block) to locate where to change
the include or the explanatory text and update the verify criteria accordingly.
In
`@en/identity-server/next/docs/complete-guides/deploy-dr/configure-clustering.md`:
- Line 6: The doc lacks explicit instructions to enforce region-only Hazelcast
membership: update the Configure Hazelcast content (referencing the "Enable
Hazelcast clustering" guidance and the configure-hazelcast.md member list) to
state that each region's Hazelcast config must use a curated well-known member
list containing only that region's node IPs, describe the required manual
filtering/automation steps to produce per-region IP lists, and add a
verification step that the region's cluster membership command returns only
those IPs; ensure guidance warns not to include cross-region IPs and suggests
automating list generation per-region (e.g., via tags or metadata) and
replicating the process for every region.
In
`@en/identity-server/next/docs/complete-guides/deploy-dr/configure-keystores.md`:
- Line 6: The guidance in configure-keystores.md says to "use the same signing
and encryption keystores across all regions" but keystores/index.md lacks
operational steps; update keystores/index.md (and add a brief note in
configure-keystores.md near the "Create separate keystores..." sentence) to: 1)
describe a recommended workflow (create canonical signing and encryption
keystores once, export securely, and distribute copies to each region) 2) list
secure transport options (transfer via S3 with SSE+KMS and restricted IAM,
rsync/scp over bastion with SSH keys, or use a secrets/replication system like
HashiCorp Vault or AWS Secrets Manager cross-region replication) 3) show
verification steps to ensure identical keystores (generate and compare sha256
checksums and keystore fingerprints using keytool/openssl) and 4) note that TLS
keystores remain node-local and include rotation/rotation-record guidance; link
the new instructions from configure-keystores.md to keystores/index.md for users
who need the how-to.
In
`@en/identity-server/next/docs/complete-guides/deploy-dr/configure-load-balancer.md`:
- Around line 11-14: The shared NGINX include
(../../deploy/front-with-the-nginx-load-balancer.md) is single-region; update
configure-load-balancer.md to add DR-specific steps immediately after the
include: explicitly instruct operators to repeat the NGINX load‑balancer
configuration for each region, ensure each regional load balancer's
upstream/backend block contains only same‑region backend nodes (no cross‑region
backends), and update the Verify step to run the curl check against each
regional hostname (e.g., curl https://<regional-hostname>/console for every
region). Reference the include and the Verify paragraph so readers perform these
region-specific, per-load-balancer actions in sequence.
In
`@en/identity-server/next/docs/complete-guides/deploy-ha/configure-clustering.md`:
- Line 9: Update the docs to clarify Hazelcast networking: either add to
configure-hazelcast.md (near the members configuration section) a short note
that Hazelcast uses TCP ports 5701–5708 for member-to-member communication (5701
default) and why those ports must be open between nodes, or expand the
prerequisite sentence in configure-clustering.md that currently says "TCP port
5701 (Hazelcast default) is open between all nodes" to explain the full port
range and purpose; reference the "members" section in configure-hazelcast.md or
the existing "TCP port 5701" line in configure-clustering.md when making the
change.
In `@en/identity-server/next/docs/complete-guides/deploy-ha/configure-tls.md`:
- Around line 6-14: The page promises TLS certificate setup but only includes
transport-level settings via the include
"../../deploy/security/configure-transport-level-security.md" and then asks
readers to verify a cert with the command `openssl s_client -connect
<hostname>:9443 -brief 2>/dev/null | head -5`; add the missing certificate
installation content or move the certificate wording to the keystore step:
either (A) add a new "Install production TLS certificate" section to
configure-tls.md that lists prerequisites (PEM or JKS, hostname), step-by-step
commands to import the cert into the Java/WSO2 keystore (keystore alias, keytool
import or PEM-to-JKS conversion), updating relevant config entries (HTTPS
listener keystore config), restart steps, and then keep the existing verify
command; or (B) remove the certificate promise here and instead update the
referenced include (configure-transport-level-security.md) to contain those
certificate installation steps and adjust the opening sentence to avoid saying
"all client-to-server traffic passes in plain text" (clarify default listener
state). Ensure the verify tip remains and that the page follows the task
structure (goal, applicability, prerequisites, sequential steps, confirmation,
troubleshooting).
In `@en/includes/complete-guides/deploy-dr/introduction.md`:
- Line 18: Update the incorrect anchor href in the HTML link that points to Path
D: change the href value in the <a
href="{{base_path}}/complete-guides/deploy-k8s/introduction/">Path D</a> element
so it uses the canonical path
"{{base_path}}/complete-guides/deploy-containers/introduction/" instead of
"deploy-k8s"; leave the surrounding text and template variable unchanged.
---
Nitpick comments:
In @.vale/styles/config/vocabularies/vocab/accept.txt:
- Around line 48-49: Remove the duplicate vocabulary entry by keeping only one
of the two lines ("failover" or "[Ff]ailover") in the vocabulary file; decide
which form you prefer (case-insensitive regex "[Ff]ailover" if you need to match
both cases, or the lowercase "failover" for a canonical entry) and delete the
other line so the file contains a single, non-redundant entry.
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/configure-keystores.md`:
- Line 6: The sentence duplicating "Create separate keystores for token signing,
data encryption, and TLS" should be removed and replaced with a concise
container-specific note that references the included guidance: keep only a
single line stating that keystores must be mounted into pods as Kubernetes
Secrets (do not bake into images) and rely on the included file
keystores/index.md ("Recommendations for setting up keystores") for the
separation rationale and detailed configuration; update the surrounding text to
reference that include so readers are directed to the comprehensive guidance
while the wrapper focuses solely on container-secret handling.
- Line 9: Remove the redundant sentence that states "The JDK `keytool` utility
is available to generate keystores locally before mounting them as Secrets" from
configure-keystores.md; instead add a single cross-reference line pointing
readers to keystores/index.md for keytool commands and conversion steps (or, if
container-specific guidance is needed, replace the sentence with a short note
about mounting pre-built keystores into containers and link to
keystores/index.md for command examples).
In `@en/identity-server/next/docs/complete-guides/deploy-eval/install.md`:
- Around line 6-11: Add a concise scoping sentence immediately before or after
the include "{% include \"../../deploy/get-started/install.md\" %}" clarifying
that this evaluation guide uses the embedded H2 database and that any production
DBMS configuration described in the included install content is optional and
only required for production deployments; reference the evaluation path and
explicitly tell readers they can skip production DB setup for this tutorial.
In `@en/identity-server/next/mkdocs.yml`:
- Around line 970-974: The sidebar currently links each "Path A/B/C/D" entry
directly to complete-guides/.../introduction.md; update the "Deployment paths"
nav entries in mkdocs.yml so each Path (Path A, Path B, Path C, Path D) points
to its new canonical overview page under deploy/deployment-paths/*.md (e.g.,
deploy/deployment-paths/path-b-overview.md) instead of the complete-guides
intro, and add an "Overview" child entry under Paths B–D (matching Path A's
shape) so the overview layer is surfaced for all paths; modify the nav entries
named "Deployment paths" and the individual "Path B", "Path C", "Path D" items
accordingly.
In `@en/includes/complete-guides/deploy-eval/introduction.md`:
- Around line 36-38: Replace the three repeated-opening bullets with concise,
parallel action-verb phrases for clarity: change the lines "- You want to test
WSO2 Identity Server features in a local environment.", "- You need to build a
proof of concept or demo.", and "- You want to familiarize yourself with the
product before planning a production deployment." to e.g. "Test WSO2 Identity
Server locally.", "Build a proof-of-concept or demo.", and "Familiarize yourself
with the product before planning a production deployment." Use plain language
and short sentences to match the style guide.
In `@en/includes/complete-guides/deploy-ha/prerequisites.md`:
- Line 10: Update the phrase "An external RDBMS: PostgreSQL, MySQL, Oracle,
MSSQL, or MariaDB" to define the acronym on first use by rewriting it as "An
external Relational Database Management System (RDBMS): PostgreSQL, MySQL,
Oracle, MSSQL, or MariaDB" so the term "Relational Database Management System
(RDBMS)" appears fully expanded before subsequent uses.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 1e7d0a46-8b4d-4446-b1d3-f88b7e1d6aae
📒 Files selected for processing (76)
.vale/styles/config/vocabularies/vocab/accept.txten/base.ymlen/identity-server/next/docs/complete-guides/deploy-containers/change-hostname.mden/identity-server/next/docs/complete-guides/deploy-containers/configure-keystores.mden/identity-server/next/docs/complete-guides/deploy-containers/configure-tls.mden/identity-server/next/docs/complete-guides/deploy-containers/deploy-on-kubernetes.mden/identity-server/next/docs/complete-guides/deploy-containers/deploy-on-openshift.mden/identity-server/next/docs/complete-guides/deploy-containers/introduction.mden/identity-server/next/docs/complete-guides/deploy-containers/next-steps.mden/identity-server/next/docs/complete-guides/deploy-containers/prerequisites.mden/identity-server/next/docs/complete-guides/deploy-containers/security-hardening.mden/identity-server/next/docs/complete-guides/deploy-containers/verify-deployment.mden/identity-server/next/docs/complete-guides/deploy-dr/change-hostname.mden/identity-server/next/docs/complete-guides/deploy-dr/configure-clustering.mden/identity-server/next/docs/complete-guides/deploy-dr/configure-databases.mden/identity-server/next/docs/complete-guides/deploy-dr/configure-failover.mden/identity-server/next/docs/complete-guides/deploy-dr/configure-keystores.mden/identity-server/next/docs/complete-guides/deploy-dr/configure-load-balancer.mden/identity-server/next/docs/complete-guides/deploy-dr/configure-replication.mden/identity-server/next/docs/complete-guides/deploy-dr/configure-tls.mden/identity-server/next/docs/complete-guides/deploy-dr/install.mden/identity-server/next/docs/complete-guides/deploy-dr/introduction.mden/identity-server/next/docs/complete-guides/deploy-dr/next-steps.mden/identity-server/next/docs/complete-guides/deploy-dr/prerequisites.mden/identity-server/next/docs/complete-guides/deploy-dr/security-hardening.mden/identity-server/next/docs/complete-guides/deploy-dr/verify-deployment.mden/identity-server/next/docs/complete-guides/deploy-eval/install.mden/identity-server/next/docs/complete-guides/deploy-eval/introduction.mden/identity-server/next/docs/complete-guides/deploy-eval/next-steps.mden/identity-server/next/docs/complete-guides/deploy-eval/prerequisites.mden/identity-server/next/docs/complete-guides/deploy-eval/start-the-server.mden/identity-server/next/docs/complete-guides/deploy-ha/change-hostname.mden/identity-server/next/docs/complete-guides/deploy-ha/configure-clustering.mden/identity-server/next/docs/complete-guides/deploy-ha/configure-databases.mden/identity-server/next/docs/complete-guides/deploy-ha/configure-keystores.mden/identity-server/next/docs/complete-guides/deploy-ha/configure-load-balancer.mden/identity-server/next/docs/complete-guides/deploy-ha/configure-tls.mden/identity-server/next/docs/complete-guides/deploy-ha/install.mden/identity-server/next/docs/complete-guides/deploy-ha/introduction.mden/identity-server/next/docs/complete-guides/deploy-ha/next-steps.mden/identity-server/next/docs/complete-guides/deploy-ha/prerequisites.mden/identity-server/next/docs/complete-guides/deploy-ha/security-hardening.mden/identity-server/next/docs/complete-guides/deploy-ha/verify-deployment.mden/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.ymlen/includes/complete-guides/deploy-containers/deploy-on-kubernetes.mden/includes/complete-guides/deploy-containers/deploy-on-openshift.mden/includes/complete-guides/deploy-containers/introduction.mden/includes/complete-guides/deploy-containers/next-steps.mden/includes/complete-guides/deploy-containers/prerequisites.mden/includes/complete-guides/deploy-dr/configure-failover.mden/includes/complete-guides/deploy-dr/configure-replication.mden/includes/complete-guides/deploy-dr/introduction.mden/includes/complete-guides/deploy-dr/next-steps.mden/includes/complete-guides/deploy-dr/prerequisites.mden/includes/complete-guides/deploy-eval/introduction.mden/includes/complete-guides/deploy-eval/next-steps.mden/includes/complete-guides/deploy-eval/prerequisites.mden/includes/complete-guides/deploy-eval/start-the-server.mden/includes/complete-guides/deploy-ha/introduction.mden/includes/complete-guides/deploy-ha/next-steps.mden/includes/complete-guides/deploy-ha/prerequisites.mden/includes/complete-guides/deploy-shared/change-hostname.mden/includes/complete-guides/deploy-shared/configure-clustering.mden/includes/complete-guides/deploy-shared/configure-databases.mden/includes/complete-guides/deploy-shared/configure-keystores.mden/includes/complete-guides/deploy-shared/configure-load-balancer.mden/includes/complete-guides/deploy-shared/configure-tls.mden/includes/complete-guides/deploy-shared/install.mden/includes/complete-guides/deploy-shared/security-hardening.mden/includes/complete-guides/deploy-shared/verify-deployment.mden/theme/material/assets/css/partials/_card.css
✅ Files skipped from review due to trivial changes (38)
- en/identity-server/next/docs/complete-guides/deploy-containers/prerequisites.md
- en/includes/complete-guides/deploy-eval/start-the-server.md
- en/identity-server/next/docs/complete-guides/deploy-ha/introduction.md
- en/includes/complete-guides/deploy-shared/configure-tls.md
- en/identity-server/next/docs/complete-guides/deploy-dr/prerequisites.md
- en/includes/complete-guides/deploy-shared/verify-deployment.md
- en/identity-server/next/docs/complete-guides/deploy-ha/next-steps.md
- en/includes/complete-guides/deploy-shared/configure-load-balancer.md
- en/includes/complete-guides/deploy-containers/deploy-on-kubernetes.md
- en/includes/complete-guides/deploy-shared/configure-databases.md
- en/identity-server/next/docs/complete-guides/deploy-eval/prerequisites.md
- en/includes/complete-guides/deploy-shared/configure-clustering.md
- en/includes/complete-guides/deploy-shared/install.md
- en/identity-server/next/docs/complete-guides/deploy-containers/introduction.md
- en/identity-server/next/docs/complete-guides/deploy-eval/next-steps.md
- en/identity-server/next/docs/complete-guides/deploy-dr/next-steps.md
- en/includes/complete-guides/deploy-shared/change-hostname.md
- en/identity-server/next/docs/complete-guides/deploy-ha/prerequisites.md
- en/includes/complete-guides/deploy-shared/configure-keystores.md
- en/identity-server/next/docs/complete-guides/deploy-containers/next-steps.md
- en/identity-server/next/docs/complete-guides/deploy-eval/introduction.md
- en/base.yml
- en/includes/complete-guides/deploy-containers/prerequisites.md
- en/includes/complete-guides/deploy-shared/security-hardening.md
- en/includes/complete-guides/deploy-containers/introduction.md
- en/includes/complete-guides/deploy-eval/next-steps.md
- en/includes/complete-guides/deploy-dr/prerequisites.md
- en/includes/complete-guides/deploy-containers/next-steps.md
- en/includes/complete-guides/deploy-dr/next-steps.md
- en/includes/complete-guides/deploy-ha/next-steps.md
- en/includes/complete-guides/deploy-ha/introduction.md
- en/theme/material/assets/css/partials/_card.css
- en/includes/complete-guides/deploy-dr/configure-replication.md
- en/includes/complete-guides/deploy-dr/configure-failover.md
- en/identity-server/next/docs/deploy/deployment-paths/production-ha.md
- en/identity-server/next/docs/complete-guides/deploy-dr/introduction.md
- en/includes/complete-guides/deploy-containers/deploy-on-openshift.md
- en/identity-server/next/docs/deploy/deployment-paths/containers.md
🚧 Files skipped from review as they are similar to previous changes (1)
- en/identity-server/next/docs/deploy/choose-your-deployment-path.md
Comment on lines
+11
to
+14
| {% include "../../../../../includes/deploy/change-the-hostname.md" %} | ||
|
|
||
| !!! tip "Verify" | ||
| Confirm `deployment.toml` inside your ConfigMap or mounted configuration file contains the correct `hostname` value before proceeding. |
Contributor
There was a problem hiding this comment.
Add container-specific execution steps around the shared hostname include.
The shared include is generic and does not tell users how to apply hostname changes through Kubernetes/OpenShift configuration objects. This leaves the container path incomplete at execution time.
Suggested container-specific addendum
{% include "../../../../../includes/deploy/change-the-hostname.md" %}
+
+For Kubernetes/OpenShift deployments, apply the hostname through your deployment configuration source:
+
+1. Update the `deployment.toml` content in your ConfigMap or mounted configuration.
+2. Ensure the updated configuration is mounted by all Identity Server pods.
+3. Roll out/restart the workload and confirm all pods use the same `hostname` value.🧰 Tools
🪛 LanguageTool
[style] ~12-~12: Using many exclamation marks might seem excessive (in this case: 6 exclamation marks for a text that’s 645 characters long)
Context: ...udes/deploy/change-the-hostname.md" %} !!! tip "Verify" Confirm `deployment.to...
(EN_EXCESSIVE_EXCLAMATION)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/change-hostname.md`
around lines 11 - 14, The shared include
("../../../../../includes/deploy/change-the-hostname.md") is generic; add a
container-specific addendum around it that provides concrete, sequential steps
for Kubernetes/OpenShift: (1) edit or patch the ConfigMap containing
deployment.toml (refer to the ConfigMap name used by the app) or update the
mounted file, (2) apply the change (kubectl/oc apply or kubectl patch), (3)
trigger a rolling restart of the Deployment/StatefulSet/Pod (kubectl rollout
restart or oc rollout) so containers pick up the new mounted config, and (4)
verify inside the running pod that deployment.toml contains the updated hostname
and the service responds (kubectl exec + cat/grep and curl). Insert these steps
before or after the existing "Verify" tip and reference the file name
deployment.toml and the ConfigMap/mount so readers can follow exact commands for
containerized deployments.
| read_time: 10 mins | ||
| --- | ||
|
|
||
| Enable HTTPS on the WSO2 Identity Server transport layer. In Kubernetes deployments, TLS is typically terminated at the Ingress controller, but WSO2 Identity Server still requires its own TLS configuration for inter-service communication and the management Console. |
Contributor
There was a problem hiding this comment.
Kubernetes-specific TLS guidance is missing from the included content.
The introduction mentions Kubernetes-specific considerations: "TLS is typically terminated at the Ingress controller, but WSO2 Identity Server still requires its own TLS configuration for inter-service communication and the management Console." However, the included content (configure-transport-level-security.md) provides only generic application-level TLS configuration (SSL protocols, ciphers, deployment.toml edits) without addressing:
- Ingress TLS termination vs. passthrough modes
- Managing certificates as Kubernetes Secrets
- Mounting certificates into pods
- ConfigMap-based configuration for containerized deployments
Users following generic file-system instructions may struggle to adapt them to Kubernetes environments.
Would you like me to draft Kubernetes-specific supplemental content for this page, or create an issue to enhance the shared TLS documentation with container-platform guidance?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/configure-tls.md`
at line 6, The page introduces Kubernetes-specific TLS concerns but the included
configure-transport-level-security.md only covers generic filesystem edits; add
a Kubernetes-specific supplement that explains Ingress TLS termination vs
passthrough modes, how to store and manage certificates as Kubernetes Secrets,
patterns for mounting certificates into Identity Server pods (or using projected
volumes), and how to apply deployment.toml or other runtime configuration via
ConfigMaps/Secrets for containerized deployments; update the page to link to the
new supplement and/or create an issue to include this container-platform
guidance in the shared TLS documentation.
| read_time: 30 mins | ||
| --- | ||
|
|
||
| Deploy WSO2 Identity Server to a Kubernetes cluster. This step covers writing the Deployment and Service manifests, configuring the ConfigMap for `deployment.toml`, and exposing WSO2 Identity Server through an Ingress resource. |
Contributor
There was a problem hiding this comment.
Page description misrepresents the included content.
The description states this step covers "writing the Deployment and Service manifests, configuring the ConfigMap for deployment.toml, and exposing WSO2 Identity Server through an Ingress resource." However, the included content (deploy-is-on-kubernetes.md) uses a Helm chart approach, which abstracts away the underlying manifests. The page does not teach manual manifest writing.
✏️ Suggested revision
-Deploy WSO2 Identity Server to a Kubernetes cluster. This step covers writing the Deployment and Service manifests, configuring the ConfigMap for `deployment.toml`, and exposing WSO2 Identity Server through an Ingress resource.
+Deploy WSO2 Identity Server to a Kubernetes cluster using Helm. This step covers installing the WSO2 Identity Server Helm chart, which automates the creation of Deployment, Service, ConfigMap, and Ingress resources.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/deploy-on-kubernetes.md`
at line 6, The page description incorrectly claims the guide covers manual
Deployment/Service manifests and ConfigMap editing, while the actual content
(deploy-is-on-kubernetes.md) uses a Helm chart; update the single-line summary
to state that this guide demonstrates deploying WSO2 Identity Server to
Kubernetes using the provided Helm chart (which abstracts underlying manifests),
remove or rephrase references to "writing the Deployment and Service manifests"
and "configuring the ConfigMap for `deployment.toml`" and instead mention
configuring Helm values and exposing the service via the chart’s Ingress
configuration.
| {% include "../../../../../includes/deploy/deploy-is-on-kubernetes.md" %} | ||
|
|
||
| !!! tip "Verify" | ||
| Run `kubectl get pods -n <namespace>` and confirm all WSO2 Identity Server pods reach `Running` status. Then open `https://<hostname>/console` and sign in with admin credentials. |
Contributor
There was a problem hiding this comment.
Use 'log in' instead of 'sign in' for consistency.
Replace "sign in" with "log in" to align with the established repository terminology.
📝 Proposed fix
- Run `kubectl get pods -n <namespace>` and confirm all WSO2 Identity Server pods reach `Running` status. Then open `https://<hostname>/console` and sign in with admin credentials.
+ Run `kubectl get pods -n <namespace>` and confirm all WSO2 Identity Server pods reach `Running` status. Then open `https://<hostname>/console` and log in with admin credentials.Based on learnings: Enforce the established terminology in the wso2/docs-is repository: use 'log in' as the verb and 'login' as the noun/adjective consistently across all Markdown documentation.
📝 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.
Suggested change
| Run `kubectl get pods -n <namespace>` and confirm all WSO2 Identity Server pods reach `Running` status. Then open `https://<hostname>/console` and sign in with admin credentials. | |
| Run `kubectl get pods -n <namespace>` and confirm all WSO2 Identity Server pods reach `Running` status. Then open `https://<hostname>/console` and log in with admin credentials. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/deploy-on-kubernetes.md`
at line 14, Replace the phrase "sign in" with "log in" in the sentence that
reads "Run `kubectl get pods -n <namespace>` and confirm all WSO2 Identity
Server pods reach `Running` status. Then open `https://<hostname>/console` and
sign in with admin credentials." to match repository terminology (use "log in"
as the verb and "login" as noun/adjective elsewhere); update only the verb to
"log in with admin credentials" so the rest of the sentence and code snippets
remain unchanged.
| read_time: 30 mins | ||
| --- | ||
|
|
||
| Deploy WSO2 Identity Server to an OpenShift cluster. OpenShift applies stricter security policies than standard Kubernetes, including restricted pod security contexts and the requirement to use Routes instead of Ingress resources. |
Contributor
There was a problem hiding this comment.
Page description misrepresents the deployment approach.
The description emphasizes OpenShift-specific considerations including "restricted pod security contexts and the requirement to use Routes instead of Ingress resources," which suggests manual configuration of these resources. However, the included content (deploy-is-on-openshift.md) uses a Helm chart that abstracts these details. The actual deployment is Helm-based, not raw manifest writing.
✏️ Suggested revision
-Deploy WSO2 Identity Server to an OpenShift cluster. OpenShift applies stricter security policies than standard Kubernetes, including restricted pod security contexts and the requirement to use Routes instead of Ingress resources.
+Deploy WSO2 Identity Server to an OpenShift cluster using Helm. OpenShift applies stricter security policies than standard Kubernetes. The Helm chart addresses these requirements, including support for restricted pod security contexts and OpenShift Routes.📝 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.
Suggested change
| Deploy WSO2 Identity Server to an OpenShift cluster. OpenShift applies stricter security policies than standard Kubernetes, including restricted pod security contexts and the requirement to use Routes instead of Ingress resources. | |
| Deploy WSO2 Identity Server to an OpenShift cluster using Helm. OpenShift applies stricter security policies than standard Kubernetes. The Helm chart addresses these requirements, including support for restricted pod security contexts and OpenShift Routes. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/identity-server/next/docs/complete-guides/deploy-containers/deploy-on-openshift.md`
at line 6, The page description incorrectly implies manual manifest-level
OpenShift configuration (mentioning "restricted pod security contexts" and
"requirement to use Routes instead of Ingress resources"); update the summary to
state that deployment uses a Helm chart (reference deploy-is-on-openshift.md)
which abstracts OpenShift specifics and handles Routes/security contexts for
you, and rephrase the sentence to mention Helm-based deployment and that the
chart adapts to OpenShift rather than instructing users to manually configure
pod security contexts or Routes.
| read_time: 10 mins | ||
| --- | ||
|
|
||
| Create separate keystores for token signing, data encryption, and TLS on every node. In a multi-region deployment, use the same signing and encryption keystores across all regions so tokens issued in one region are valid in another. |
Contributor
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add explicit guidance for cross-region keystore distribution.
The page states "use the same signing and encryption keystores across all regions so tokens issued in one region are valid in another," but the included content (keystores/index.md) does not provide specific instructions for implementing cross-region keystore sharing. Users may not understand the operational steps required, such as:
- Whether to create keystores once and copy them to all regions
- How to securely distribute keystores across regions
- How to verify keystores are identical across regions
Would you like me to draft additional content that explains the cross-region keystore distribution workflow, or open an issue to enhance the shared keystores documentation with multi-region guidance?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/identity-server/next/docs/complete-guides/deploy-dr/configure-keystores.md`
at line 6, The guidance in configure-keystores.md says to "use the same signing
and encryption keystores across all regions" but keystores/index.md lacks
operational steps; update keystores/index.md (and add a brief note in
configure-keystores.md near the "Create separate keystores..." sentence) to: 1)
describe a recommended workflow (create canonical signing and encryption
keystores once, export securely, and distribute copies to each region) 2) list
secure transport options (transfer via S3 with SSE+KMS and restricted IAM,
rsync/scp over bastion with SSH keys, or use a secrets/replication system like
HashiCorp Vault or AWS Secrets Manager cross-region replication) 3) show
verification steps to ensure identical keystores (generate and compare sha256
checksums and keystore fingerprints using keytool/openssl) and 4) note that TLS
keystores remain node-local and include rotation/rotation-record guidance; link
the new instructions from configure-keystores.md to keystores/index.md for users
who need the how-to.
Comment on lines
+11
to
+14
| {% include "../../deploy/front-with-the-nginx-load-balancer.md" %} | ||
|
|
||
| !!! tip "Verify" | ||
| Run `curl -k -o /dev/null -s -w "%{http_code}" https://<regional-hostname>/console` against each regional load balancer. Each should return `200`. |
Contributor
There was a problem hiding this comment.
Clarify DR-specific adaptations after the shared NGINX include.
The included guide is single-region oriented. In this DR page, readers still need explicit instructions to (1) repeat configuration per region and (2) use only same-region backend nodes in each regional load balancer. Without that, the step can be misapplied in multi-region DR.
Suggested addition after the include
{% include "../../deploy/front-with-the-nginx-load-balancer.md" %}
+
+After you complete the shared NGINX setup, apply these DR-specific rules:
+
+1. Repeat the load balancer configuration in **each** region.
+2. In each regional load balancer, configure upstream servers from that same region only.
+3. Use a region-specific public hostname per regional load balancer.
+4. Keep global traffic steering (DNS or global load balancer) separate from regional upstream definitions.📝 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.
Suggested change
| {% include "../../deploy/front-with-the-nginx-load-balancer.md" %} | |
| !!! tip "Verify" | |
| Run `curl -k -o /dev/null -s -w "%{http_code}" https://<regional-hostname>/console` against each regional load balancer. Each should return `200`. | |
| {% include "../../deploy/front-with-the-nginx-load-balancer.md" %} | |
| After you complete the shared NGINX setup, apply these DR-specific rules: | |
| 1. Repeat the load balancer configuration in **each** region. | |
| 2. In each regional load balancer, configure upstream servers from that same region only. | |
| 3. Use a region-specific public hostname per regional load balancer. | |
| 4. Keep global traffic steering (DNS or global load balancer) separate from regional upstream definitions. | |
| !!! tip "Verify" | |
| Run `curl -k -o /dev/null -s -w "%{http_code}" https://<regional-hostname>/console` against each regional load balancer. Each should return `200`. |
🧰 Tools
🪛 LanguageTool
[style] ~12-~12: Using many exclamation marks might seem excessive (in this case: 6 exclamation marks for a text that’s 653 characters long)
Context: ...nt-with-the-nginx-load-balancer.md" %} !!! tip "Verify" Run `curl -k -o /dev/n...
(EN_EXCESSIVE_EXCLAMATION)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/identity-server/next/docs/complete-guides/deploy-dr/configure-load-balancer.md`
around lines 11 - 14, The shared NGINX include
(../../deploy/front-with-the-nginx-load-balancer.md) is single-region; update
configure-load-balancer.md to add DR-specific steps immediately after the
include: explicitly instruct operators to repeat the NGINX load‑balancer
configuration for each region, ensure each regional load balancer's
upstream/backend block contains only same‑region backend nodes (no cross‑region
backends), and update the Verify step to run the curl check against each
regional hostname (e.g., curl https://<regional-hostname>/console for every
region). Reference the include and the Verify paragraph so readers perform these
region-specific, per-load-balancer actions in sequence.
| Enable Hazelcast clustering so all nodes share session data and synchronize cache invalidation. Without clustering, a user authenticated on one node is unknown to other nodes, causing authentication errors behind the load balancer. | ||
|
|
||
| !!! note "Before this step" | ||
| All nodes have identical configuration through the previous steps. TCP port 5701 (Hazelcast default) is open between all nodes. |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if configure-hazelcast.md documents port 5701
rg -n -C3 '5701|port.*hazelcast|hazelcast.*port' en/identity-server/next/docs/deploy/configure-hazelcast.md
# Check if there's port configuration documented elsewhere in deployment.toml or Hazelcast config
rg -n 'hazelcast.*port|5701' en/includes/ en/identity-server/next/docs/deploy/Repository: wso2/docs-is
Length of output: 1168
🏁 Script executed:
# Check the full content of configure-clustering.md around the lines in question
wc -l en/identity-server/next/docs/complete-guides/deploy-ha/configure-clustering.md
head -20 en/identity-server/next/docs/complete-guides/deploy-ha/configure-clustering.mdRepository: wso2/docs-is
Length of output: 833
🏁 Script executed:
# Check the full content of configure-hazelcast.md to see what it documents
wc -l en/identity-server/next/docs/deploy/configure-hazelcast.md
cat -n en/identity-server/next/docs/deploy/configure-hazelcast.mdRepository: wso2/docs-is
Length of output: 4334
Add port documentation to configure-hazelcast.md or clarify the network prerequisite.
Line 9 states "TCP port 5701 (Hazelcast default) is open between all nodes" as a prerequisite, but the included configure-hazelcast.md file does not document this port requirement or explain why it is needed for cluster communication. Readers may not understand which network ports to open or why.
To address this gap, either add a brief explanation of the Hazelcast communication port range (5701-5708) to configure-hazelcast.md when describing the members configuration, or expand the prerequisite in configure-clustering.md to explain that port 5701 is required for inter-node communication.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/identity-server/next/docs/complete-guides/deploy-ha/configure-clustering.md`
at line 9, Update the docs to clarify Hazelcast networking: either add to
configure-hazelcast.md (near the members configuration section) a short note
that Hazelcast uses TCP ports 5701–5708 for member-to-member communication (5701
default) and why those ports must be open between nodes, or expand the
prerequisite sentence in configure-clustering.md that currently says "TCP port
5701 (Hazelcast default) is open between all nodes" to explain the full port
range and purpose; reference the "members" section in configure-hazelcast.md or
the existing "TCP port 5701" line in configure-clustering.md when making the
change.
Comment on lines
+6
to
+14
| Enable HTTPS on the WSO2 Identity Server transport layer using your production TLS certificate. Without this step, all client-to-server traffic passes in plain text and browser security warnings prevent users from accessing the Console. | ||
|
|
||
| !!! note "Before this step" | ||
| Your TLS certificate (PEM or JKS) for the production hostname is available. The hostname configuration step is complete. | ||
|
|
||
| {% include "../../deploy/security/configure-transport-level-security.md" %} | ||
|
|
||
| !!! tip "Verify" | ||
| Start one node temporarily. Run `openssl s_client -connect <hostname>:9443 -brief 2>/dev/null | head -5` to confirm the certificate CN or SAN matches your hostname. Stop the server before continuing. |
Contributor
There was a problem hiding this comment.
Scope this page to TLS hardening or add the missing certificate steps.
Lines 6-11 promise certificate setup, but the included en/identity-server/next/docs/deploy/security/configure-transport-level-security.md content only covers transport protocol settings and a restart. Line 14 then asks the reader to verify a certificate that this page never told them how to install, and the “plain text” wording on Line 6 overstates what happens on the default HTTPS listener. Either move the certificate wording to the keystore step or add the missing certificate procedure here.
Suggested wording if the keystore step remains separate
-Enable HTTPS on the WSO2 Identity Server transport layer using your production TLS certificate. Without this step, all client-to-server traffic passes in plain text and browser security warnings prevent users from accessing the Console.
+Harden the HTTPS transport settings for WSO2 Identity Server. Configure the production certificate and keystore in the next step. Without a trusted production certificate, browsers show security warnings when users access the Console.
!!! note "Before this step"
- Your TLS certificate (PEM or JKS) for the production hostname is available. The hostname configuration step is complete.
+ Your production certificate and hostname are ready. This step configures transport-level TLS settings. Configure the certificate and keystore in the next step.🧰 Tools
🪛 LanguageTool
[style] ~12-~12: Using many exclamation marks might seem excessive (in this case: 6 exclamation marks for a text that’s 695 characters long)
Context: ...figure-transport-level-security.md" %} !!! tip "Verify" Start one node tempora...
(EN_EXCESSIVE_EXCLAMATION)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@en/identity-server/next/docs/complete-guides/deploy-ha/configure-tls.md`
around lines 6 - 14, The page promises TLS certificate setup but only includes
transport-level settings via the include
"../../deploy/security/configure-transport-level-security.md" and then asks
readers to verify a cert with the command `openssl s_client -connect
<hostname>:9443 -brief 2>/dev/null | head -5`; add the missing certificate
installation content or move the certificate wording to the keystore step:
either (A) add a new "Install production TLS certificate" section to
configure-tls.md that lists prerequisites (PEM or JKS, hostname), step-by-step
commands to import the cert into the Java/WSO2 keystore (keystore alias, keytool
import or PEM-to-JKS conversion), updating relevant config entries (HTTPS
listener keystore config), restart steps, and then keep the existing verify
command; or (B) remove the certificate promise here and instead update the
referenced include (configure-transport-level-security.md) to contain those
certificate installation steps and adjust the opening sentence to avoid saying
"all client-to-server traffic passes in plain text" (clarify default listener
state). Ensure the verify tip remains and that the page follows the task
structure (goal, applicability, prerequisites, sequential steps, confirmation,
troubleshooting).
| </tr> | ||
| <tr> | ||
| <td><b>What this path excludes</b></td> | ||
| <td>Single-region HA details — complete <a href="{{base_path}}/complete-guides/deploy-ha/introduction/">Path B</a> first. Container orchestration specifics are covered in <a href="{{base_path}}/complete-guides/deploy-k8s/introduction/">Path D</a>.</td> |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Find all deployment path introduction pages
fd -e md 'introduction.md' en/identity-server/next/docs/complete-guides/
# Check mkdocs.yml navigation for Path D definition
rg -n -A5 'Path D|deploy-k8s|deploy-containers' en/identity-server/next/mkdocs.yml
# Verify the deployment paths overview page references
rg -n 'Path D' en/identity-server/next/docs/deploy/choose-your-deployment-path.mdRepository: wso2/docs-is
Length of output: 2923
Update the link for Path D to use the correct path.
Line 18 incorrectly links to complete-guides/deploy-k8s/introduction/. The canonical path for Path D (Container platforms) is complete-guides/deploy-containers/introduction/, as defined in mkdocs.yml. Update the link to point to the correct destination.
Current link
<a href="{{base_path}}/complete-guides/deploy-k8s/introduction/">Path D</a>
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@en/includes/complete-guides/deploy-dr/introduction.md` at line 18, Update the
incorrect anchor href in the HTML link that points to Path D: change the href
value in the <a
href="{{base_path}}/complete-guides/deploy-k8s/introduction/">Path D</a> element
so it uses the canonical path
"{{base_path}}/complete-guides/deploy-containers/introduction/" instead of
"deploy-k8s"; leave the surrounding text and template variable unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
Documentation
Style