docs: align self-hosting docs for Formbricks v5#7906
Conversation
BhagyaAmarasinghe
force-pushed
the
doc/self-hosting-migration-guide
branch
from
335dfae to
276ab06
Compare
WalkthroughThe documentation has been updated to reflect Formbricks v5 self-hosting requirements and capabilities. Changes include a new migration guide detailing runtime-contract requirements (Hub bundling, edge rate limiting, environment variable configurations), updates to rate-limiting documentation with migration links, and refined environment variable documentation for v5 behavior. Deployment-specific guides (Docker, Kubernetes, cluster, one-click) have been revised to document Hub as mandatory, Cube as optional, edge rate-limiting requirements, and include v4→v5 upgrade workflows. Configuration sections have been updated to reflect new default values and consolidated dependencies across distributed deployments. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/self-hosting/configuration/environment-variables.mdx`:
- Around line 111-112: Update the table row for HUB_API_URL so the default
column reflects the bundled Docker stack value (http://hub:8080) to match the
description and the Docker setup guidance; keep the description text about using
http://hub:8080 for the bundled stack and, if helpful, add a short parenthetical
or secondary example in the default or notes to show the local dev alternative
(http://localhost:8080) while ensuring the primary default shown is
http://hub:8080.
In `@docs/self-hosting/setup/kubernetes.mdx`:
- Around line 120-136: The phrase "confirm all of the following before running
the upgrade:" is wordy; update the text under "## 4. Upgrade The Deployment" to
instead read "confirm the following before running the upgrade:" and keep the
bulleted list as-is so the heading and checklist remain clear and concise.
🪄 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: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 21af729b-f6e4-4ea6-a933-adf4a12ff460
📒 Files selected for processing (7)
docs/self-hosting/advanced/migration.mdxdocs/self-hosting/advanced/rate-limiting.mdxdocs/self-hosting/configuration/environment-variables.mdxdocs/self-hosting/setup/cluster-setup.mdxdocs/self-hosting/setup/docker.mdxdocs/self-hosting/setup/kubernetes.mdxdocs/self-hosting/setup/one-click.mdx
| | HUB_API_KEY | API key used by the Formbricks Hub API. Generate a strong secret and use the same value wherever your deployment supplies Hub auth configuration. | required | (e.g. `openssl rand -hex 32`) | | ||
| | HUB_API_URL | Base URL the Formbricks app uses to call Hub. With the bundled Docker stack, keep this at `http://hub:8080` unless Hub runs elsewhere. | required | `http://localhost:8080` in local dev | |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Clarify HUB_API_URL default value for consistency.
The default column shows http://localhost:8080 for local dev, but the description says to keep it at http://hub:8080 for the bundled Docker stack. Consider updating the default column to explicitly show http://hub:8080 for Docker/production deployments to match the guidance in docs/self-hosting/setup/docker.mdx (lines 108-109) which states the bundled stack sets HUB_API_URL to http://hub:8080.
📝 Suggested clarification
-| HUB_API_URL | Base URL the Formbricks app uses to call Hub. With the bundled Docker stack, keep this at `http://hub:8080` unless Hub runs elsewhere. | required | `http://localhost:8080` in local dev |
+| HUB_API_URL | Base URL the Formbricks app uses to call Hub. With the bundled Docker stack, keep this at `http://hub:8080` unless Hub runs elsewhere. | required | `http://hub:8080` (bundled Docker), `http://localhost:8080` (local dev) |📝 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.
| | HUB_API_KEY | API key used by the Formbricks Hub API. Generate a strong secret and use the same value wherever your deployment supplies Hub auth configuration. | required | (e.g. `openssl rand -hex 32`) | | |
| | HUB_API_URL | Base URL the Formbricks app uses to call Hub. With the bundled Docker stack, keep this at `http://hub:8080` unless Hub runs elsewhere. | required | `http://localhost:8080` in local dev | | |
| | HUB_API_KEY | API key used by the Formbricks Hub API. Generate a strong secret and use the same value wherever your deployment supplies Hub auth configuration. | required | (e.g. `openssl rand -hex 32`) | | |
| | HUB_API_URL | Base URL the Formbricks app uses to call Hub. With the bundled Docker stack, keep this at `http://hub:8080` unless Hub runs elsewhere. | required | `http://hub:8080` (bundled Docker), `http://localhost:8080` (local dev) | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/self-hosting/configuration/environment-variables.mdx` around lines 111 -
112, Update the table row for HUB_API_URL so the default column reflects the
bundled Docker stack value (http://hub:8080) to match the description and the
Docker setup guidance; keep the description text about using http://hub:8080 for
the bundled stack and, if helpful, add a short parenthetical or secondary
example in the default or notes to show the local dev alternative
(http://localhost:8080) while ensuring the primary default shown is
http://hub:8080.
| ## 4. Upgrade The Deployment | ||
|
|
||
| For normal chart upgrades: | ||
|
|
||
| ### Enabling Autoscaling | ||
| ```sh | ||
| helm upgrade formbricks oci://ghcr.io/formbricks/helm-charts/formbricks -n formbricks --set autoscaling.enabled=true --set autoscaling.minReplicas=3 --set autoscaling.maxReplicas=10 | ||
| helm upgrade formbricks oci://ghcr.io/formbricks/helm-charts/formbricks \ | ||
| -n formbricks \ | ||
| -f values.yaml | ||
| ``` | ||
|
|
||
| --- | ||
| For a Formbricks 4.x to 5.0 migration, confirm all of the following before running the upgrade: | ||
|
|
||
| ## 5. Key Configuration Values | ||
| - Hub remains enabled | ||
| - `HUB_API_KEY` is present | ||
| - your edge rate-limiting plan is in place | ||
| - any required `AI_*` variables are added | ||
| - Cube is configured only if this instance needs analytics dashboards or analysis queries |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider minor wording improvement.
The static analysis suggests simplifying "all of the following" to "the following" for conciseness.
📝 Optional style improvement
-For a Formbricks 4.x to 5.0 migration, confirm all of the following before running the upgrade:
+For a Formbricks 4.x to 5.0 migration, confirm the following before running the upgrade:🧰 Tools
🪛 LanguageTool
[style] ~130-~130: Consider removing “of” to be more concise
Context: ...ormbricks 4.x to 5.0 migration, confirm all of the following before running the upgrade: ...
(ALL_OF_THE)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/self-hosting/setup/kubernetes.mdx` around lines 120 - 136, The phrase
"confirm all of the following before running the upgrade:" is wordy; update the
text under "## 4. Upgrade The Deployment" to instead read "confirm the following
before running the upgrade:" and keep the bulleted list as-is so the heading and
checklist remain clear and concise.
|
I think this should also include a pointer to the MinIO -> RustFS change, right? |
BhagyaAmarasinghe
force-pushed
the
doc/self-hosting-migration-guide
branch
from
e351912 to
a7c8e1a
Compare
🚨 PR Size WarningThis PR has approximately 960 lines of changes (585 additions, 375 deletions across 7 files). Large PRs (>800 lines) are significantly harder to review and increase the chance of merge conflicts. Consider splitting this into smaller, self-contained PRs. 💡 Suggestions:
📊 What was counted:
📚 Guidelines:
If this large PR is unavoidable (e.g., migration, dependency update, major refactor), please explain in the PR description why it couldn't be split. |
|
3 participants
Summary
This updates the self-hosting docs set for the Formbricks v5 upgrade path.
Fixes ENG-757
Why
The existing self-hosting docs only covered the v5 rate-limiting change and did not explain the full upgrade contract around Hub, AI configuration, Cube scope, or the current Kubernetes deployment path.
Impact
Self-hosters upgrading from Formbricks 4.x should now have one canonical migration guide plus consistent support pages instead of conflicting setup instructions.
Validation
docker/docker-compose.yml,.env.example, andcharts/formbricksgit diff --checkNotes
mintlify devwas not run because the Mintlify CLI is not installed in this environment