docs(self-hosting): add FIPS-enabled deployment guide - #306
Open
pratapalakshmi wants to merge 5 commits into
Open
docs(self-hosting): add FIPS-enabled deployment guide#306pratapalakshmi wants to merge 5 commits into
pratapalakshmi wants to merge 5 commits into
Conversation
Adds the FIPS deployment guide for the makeplane/*-commercial-fips image set under the Commercial Edition install methods, matching the sibling pages' hidden/noindex convention (search:false, sidebar:false, robots noindex, added to the LLM ignoreFiles list). Covers the host fips=1 prerequisite (the single most-missed step), the full -commercial-fips image list (and why there is no FIPS AIO image), the docker-compose-fips.yml deploy + verify-fips.sh flow, the FIPS-only config defaults (LDAP_TLS_REQUIRE_CERT, SAML_REJECT_DEPRECATED_ALGORITHM, SECRET_ENCRYPTION_V2, USAGE_ID_DIGEST) with overrides, non-root/OpenShift arbitrary-UID guidance, and an honest scope-of-coverage section (bundled data plane is not FIPS; modules are certified, not Plane as a product). Supersedes makeplane/docs#484 — self-hosting content lives on developers.plane.so. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds a FIPS deployment guide with image selection, host setup, Compose and Kubernetes guidance, verification, configuration, LDAP validation, and coverage limitations. Adds the guide to self-hosting navigation and the LLM generation ignore list. ChangesFIPS deployment documentation
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
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}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/self-hosting/methods/install-methods-commercial/fips-deployment.md`:
- Line 98: Update the log-output fenced code block in the FIPS deployment
documentation to specify the text language identifier, changing the opening
fence to use text while preserving the block contents.
- Around line 107-110: Update the FIPS deployment documentation around the
verify-fips.sh reference to remove claims about invoking or describing checks
from a nonexistent committed script, unless the script is added to the
repository first. Keep the documented FIPS validation guidance accurate and
avoid listing exact assertions or exit behavior without an available script
implementing them.
- Around line 118-129: Update the settings table’s USAGE_ID_DIGEST row to state
that sha256 is required with FIPS-mode Postgres and explicitly mark md5 as
incompatible, rather than implying it is a supported FIPS override. Keep the
existing digest purpose and migration context intact.
- Around line 146-153: Update the OpenShift security-context guidance in the
FIPS deployment documentation to avoid unconditionally setting runAsGroup: 0 or
fsGroup: 0, since restricted-v2 rejects fsGroup 0 unless the namespace
supplemental-group range permits it. State that these group settings are
conditional on supported namespace configuration, otherwise omit them, and
document that bundled proxy deployments may use an SCC explicitly allowing
NET_BIND_SERVICE instead of requiring a custom SCC.
- Around line 61-71: Split the FIPS host setup section by distribution and RHEL
version instead of grouping all hosts under “RHEL-family.” Keep fips-mode-setup
and the separate /boot requirement only for supported RHEL versions, document
RHEL 10 as requiring installation with fips=1 without post-install switching,
and provide Amazon Linux 2023 instructions without requiring a separate /boot or
boot=UUID=... configuration.
🪄 Autofix
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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 1c43bdb4-e450-4d3d-9b49-bef375f472c0
📒 Files selected for processing (2)
docs/.vitepress/config.mtsdocs/self-hosting/methods/install-methods-commercial/fips-deployment.md
Add a "FIPS deployment" entry to the "Self-host Plane" sidebar group in both the root and /self-hosting/ sidebars, and drop `search: false` / `sidebar: false` from the page frontmatter so it renders with the nav and is found by in-site (⌘K) search. Keep the robots noindex tag — discoverable within the docs site, not indexed by public search engines (matching its commercial-feature nature). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Host setup: split by distro/version. AL2023 + RHEL 8/9 use fips-mode-setup (AL2023 keeps /boot on root; RHEL needs a mounted separate /boot if present). RHEL 10 removed fips-mode-setup — FIPS must be enabled at install with fips=1; post-install switching is unsupported. - OpenShift: don't set runAsUser/runAsGroup/fsGroup under restricted-v2 — the SCC assigns the UID and allocates fsGroup from the namespace supplemental-group range, so an explicit fsGroup: 0 is rejected unless that range includes 0. The runAsGroup/fsGroup: 0 guidance now applies only to plain Kubernetes. Proxy note reworded to "an SCC that permits NET_BIND_SERVICE". - USAGE_ID_DIGEST: clarify md5 is incompatible under FIPS (sha256 required), not an either-direction override. - verify-fips.sh: attribute to the plane-ee repo and soften wording (it is not committed to this docs repo). - Add the `text` language tag to the startup-log fenced block. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/.vitepress/config.mts`:
- Line 302: Restore the trailing comma after the Kubernetes sidebar item in the
sidebar configuration, preserving the repository’s Prettier formatting
conventions for multiline entries.
In `@docs/self-hosting/methods/fips-deployment.md`:
- Around line 19-20: Update the FIPS deployment documentation warning and the
sections covering PLANE_REQUIRE_FIPS=0 and LDAP_TLS_REQUIRE_CERT=never to
distinguish an unguarded FIPS image from the shipped Compose startup guard, and
explicitly label both overrides as non-accredited, limited to evaluation or
troubleshooting rather than accredited deployments.
🪄 Autofix
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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 53a452e1-441d-4fcf-88ec-41f437635540
📒 Files selected for processing (2)
docs/.vitepress/config.mtsdocs/self-hosting/methods/fips-deployment.md
| { text: "Self-hosting 101", link: "/self-hosting/self-hosting-101" }, | ||
| { text: "Docker Compose", link: "/self-hosting/methods/docker-compose" }, | ||
| { text: "Kubernetes", link: "/self-hosting/methods/kubernetes" }, | ||
| { text: "Kubernetes", link: "/self-hosting/methods/kubernetes" } |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Restore the trailing comma.
Line 302 removes the trailing comma from a multiline sidebar item. Restore it to match the repository’s Prettier configuration.
As per coding guidelines, files matching **/*.{md,ts,tsx,js,jsx,vue,mts} must use Prettier with 120-character width, 2-space indentation, semicolons, double quotes, and ES5 trailing commas.
Suggested fix
- { text: "Kubernetes", link: "/self-hosting/methods/kubernetes" }
+ { text: "Kubernetes", link: "/self-hosting/methods/kubernetes" },📝 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
| { text: "Kubernetes", link: "/self-hosting/methods/kubernetes" } | |
| { text: "Kubernetes", link: "/self-hosting/methods/kubernetes" }, |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/.vitepress/config.mts` at line 302, Restore the trailing comma after the
Kubernetes sidebar item in the sidebar configuration, preserving the
repository’s Prettier formatting conventions for multiline entries.
Source: Coding guidelines
Comment on lines
+19
to
+20
| ::: warning **The single most important prerequisite** | ||
| FIPS mode is a property of the **host**, not of the image. A FIPS image on a non-FIPS host starts cleanly and looks identical from the inside while providing none of the guarantees. Read [Host prerequisite](#host-prerequisite) first. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Label the downgrade paths as non-accredited.
The warning says a FIPS image on a non-FIPS host starts cleanly, but the shipped Compose file sets PLANE_REQUIRE_FIPS=1 and refuses startup. The page also documents PLANE_REQUIRE_FIPS=0 and LDAP_TLS_REQUIRE_CERT=never without limiting either override to evaluation or troubleshooting.
State that both overrides are not suitable for an accredited deployment. Qualify the warning so it distinguishes an unguarded image from the shipped Compose behavior.
Suggested wording
-FIPS image on a non-FIPS host starts cleanly and looks identical from the inside while providing none of the guarantees.
+Without startup enforcement, a FIPS image can start on a non-FIPS host while providing none of the guarantees.
-Set it to `0` to downgrade that to a startup warning.
+Set it to `0` only for evaluation or troubleshooting. Do not use it for an accredited deployment.
-Setting `LDAP_TLS_REQUIRE_CERT=never` restores the previous behaviour and logs a warning on every
-connection.
+Use `LDAP_TLS_REQUIRE_CERT=never` only for temporary compatibility testing. It bypasses LDAP
+certificate validation and is not suitable for an accredited deployment.Also applies to: 76-77, 144-145
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/self-hosting/methods/fips-deployment.md` around lines 19 - 20, Update
the FIPS deployment documentation warning and the sections covering
PLANE_REQUIRE_FIPS=0 and LDAP_TLS_REQUIRE_CERT=never to distinguish an unguarded
FIPS image from the shipped Compose startup guard, and explicitly label both
overrides as non-accredited, limited to evaluation or troubleshooting rather
than accredited deployments.
plane-ee is a private repository, so the deployment files the Deploy section referenced (deployments/cli/commercial/...) are not browsable by the customers and prospects this page is for. Describe them as the FIPS deployment bundle shipped with each release instead, with a pointer to the account team / support for obtaining it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.
What
Adds the FIPS-enabled deployment guide for the
makeplane/*-commercial-fipsimage set, under the Commercial Edition install methods (self-hosting/methods/install-methods-commercial/fips-deployment.md).This supersedes makeplane/docs#484 — self-hosting content lives on
developers.plane.so, so the guide belongs in this repo rather than the general docs site. That PR is being closed in favour of this one.Placement & conventions
Placed beside the other Commercial Edition install pages (
docker-compose.md,kubernetes.md) and follows their exact convention:search: false,sidebar: false,robots: noindex, nofollow, and added to thevitepress-plugin-llmsignoreFileslist inconfig.mts. Reached by direct link like its siblings.Contents
fips=1boot requirement (the single most-missed step: a FIPS image on a non-FIPS host looks fine but provides nothing).-commercial-fipsimages; note there is deliberately no FIPS AIO image (Alpine base has no validated crypto).docker-compose-fips.ymlflow and theverify-fips.shposture check.LDAP_TLS_REQUIRE_CERT,SAML_REJECT_DEPRECATED_ALGORITHM,SECRET_ENCRYPTION_V2,USAGE_ID_DIGEST, each with its override and standard-image default, plus the LDAP hostname-matching gotcha.restricted-v2, plus the bundled-proxy low-port caveat. (New vs #484 — reflects the validated OpenShift arbitrary-UID work.)Points at
deployments/cli/commercial/README-FIPS.mdin plane-ee as the authoritative operations reference.Validation
prettierclean on both files.@voidzero-dev/vitepress-theme); CI's clean install + build is authoritative.🤖 Generated with Claude Code
Summary by CodeRabbit