feat: add Nextra docs project in apps/docs with self-hosting content#28267
Open
feat: add Nextra docs project in apps/docs with self-hosting content#28267
Conversation
Co-Authored-By: peer@cal.com <peer@cal.com>
Co-Authored-By: peer@cal.com <peer@cal.com>
Contributor
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
7 issues found across 45 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="apps/docs/content/deployments/gcp.mdx">
<violation number="1" location="apps/docs/content/deployments/gcp.mdx:93">
P2: The Docker image name in the run command doesn’t match the image pulled above, so the container won’t start when users follow these steps.</violation>
<violation number="2" location="apps/docs/content/deployments/gcp.mdx:100">
P2: `http://localhost` points to the user’s machine, not the GCP VM. Use the VM’s external IP so the access step works.</violation>
</file>
<file name="apps/docs/app/layout.tsx">
<violation number="1" location="apps/docs/app/layout.tsx:9">
P2: Hardcoded navbar label should use the localization helper (t()) rather than embedding the text directly so it can be translated.</violation>
</file>
<file name="apps/docs/content/guides/white-labeling/color-tokens.mdx">
<violation number="1" location="apps/docs/content/guides/white-labeling/color-tokens.mdx:45">
P3: Typo in documentation: "peaks your interest" should be "piques your interest".</violation>
</file>
<file name="apps/docs/content/docker.mdx">
<violation number="1" location="apps/docs/content/docker.mdx:105">
P1: Avoid recommending `NODE_TLS_REJECT_UNAUTHORIZED=0`; it disables TLS verification globally and can lead to insecure deployments. Suggest configuring proper certificates (or `NODE_EXTRA_CA_CERTS`) instead.</violation>
<violation number="2" location="apps/docs/content/docker.mdx:109">
P2: `NEXTAUTH_URL` should be the canonical site URL (no `/api/auth`) unless you’re using a custom base path. The current value is misleading and can misconfigure NextAuth callbacks.</violation>
</file>
<file name="apps/docs/content/installation.mdx">
<violation number="1" location="apps/docs/content/installation.mdx:63">
P2: The E2E testing link points to `/docs/developing/local-development`, but there is no corresponding page in `apps/docs/content`, so this link will be broken in the new docs site. Update the link to an existing page or add the missing doc.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| ## Troubleshooting | ||
|
|
||
| - **Failed to commit changes: Invalid 'prisma.user.create()'**: Certain versions may have trouble creating a user if the field `metadata` is empty. Using an empty json object `{}` as the field value should resolve this issue. Also, the `id` field will autoincrement, so you may also try leaving the value of `id` as empty. | ||
| - **SSL edge termination**: If running behind a load balancer which handles SSL certificates, you will need to add the environmental variable `NODE_TLS_REJECT_UNAUTHORIZED=0` to prevent requests from being rejected. Only do this if you know what you are doing and trust the services/load-balancers directing traffic to your service. |
Contributor
There was a problem hiding this comment.
P1: Avoid recommending NODE_TLS_REJECT_UNAUTHORIZED=0; it disables TLS verification globally and can lead to insecure deployments. Suggest configuring proper certificates (or NODE_EXTRA_CA_CERTS) instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/content/docker.mdx, line 105:
<comment>Avoid recommending `NODE_TLS_REJECT_UNAUTHORIZED=0`; it disables TLS verification globally and can lead to insecure deployments. Suggest configuring proper certificates (or `NODE_EXTRA_CA_CERTS`) instead.</comment>
<file context>
@@ -0,0 +1,114 @@
+## Troubleshooting
+
+- **Failed to commit changes: Invalid 'prisma.user.create()'**: Certain versions may have trouble creating a user if the field `metadata` is empty. Using an empty json object `{}` as the field value should resolve this issue. Also, the `id` field will autoincrement, so you may also try leaving the value of `id` as empty.
+- **SSL edge termination**: If running behind a load balancer which handles SSL certificates, you will need to add the environmental variable `NODE_TLS_REJECT_UNAUTHORIZED=0` to prevent requests from being rejected. Only do this if you know what you are doing and trust the services/load-balancers directing traffic to your service.
+
+### CLIENT_FETCH_ERROR
</file context>
Suggested change
| - **SSL edge termination**: If running behind a load balancer which handles SSL certificates, you will need to add the environmental variable `NODE_TLS_REJECT_UNAUTHORIZED=0` to prevent requests from being rejected. Only do this if you know what you are doing and trust the services/load-balancers directing traffic to your service. | |
| - **SSL edge termination**: If running behind a load balancer which handles SSL certificates, configure the container to trust the load balancer’s certificate chain (for example via system trust store or `NODE_EXTRA_CA_CERTS`) rather than disabling TLS verification. |
|
|
||
| #### Access Cal.com | ||
|
|
||
| Open a web browser and navigate to `http://localhost`. You should now be able to access the Cal.com homepage. |
Contributor
There was a problem hiding this comment.
P2: http://localhost points to the user’s machine, not the GCP VM. Use the VM’s external IP so the access step works.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/content/deployments/gcp.mdx, line 100:
<comment>`http://localhost` points to the user’s machine, not the GCP VM. Use the VM’s external IP so the access step works.</comment>
<file context>
@@ -0,0 +1,102 @@
+
+#### Access Cal.com
+
+Open a web browser and navigate to `http://localhost`. You should now be able to access the Cal.com homepage.
+
+Congratulations! You have successfully deployed Cal.com on Google Cloud Platform.
</file context>
| Run the Docker container using the following command: | ||
|
|
||
| ```bash | ||
| docker run -d -p 80:80 cal/cal.com |
Contributor
There was a problem hiding this comment.
P2: The Docker image name in the run command doesn’t match the image pulled above, so the container won’t start when users follow these steps.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/content/deployments/gcp.mdx, line 93:
<comment>The Docker image name in the run command doesn’t match the image pulled above, so the container won’t start when users follow these steps.</comment>
<file context>
@@ -0,0 +1,102 @@
+Run the Docker container using the following command:
+
+```bash
+docker run -d -p 80:80 cal/cal.com
+```
+
</file context>
|
|
||
| ### CLIENT_FETCH_ERROR | ||
|
|
||
| If you experience this error, it may be the way the default Auth callback in the server is using the WEBAPP_URL as a base url. The container does not necessarily have access to the same DNS as your local machine, and therefore needs to be configured to resolve to itself. You may be able to correct this by configuring `NEXTAUTH_URL=http://localhost:3000/api/auth`, to help the backend loop back to itself. |
Contributor
There was a problem hiding this comment.
P2: NEXTAUTH_URL should be the canonical site URL (no /api/auth) unless you’re using a custom base path. The current value is misleading and can misconfigure NextAuth callbacks.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/content/docker.mdx, line 109:
<comment>`NEXTAUTH_URL` should be the canonical site URL (no `/api/auth`) unless you’re using a custom base path. The current value is misleading and can misconfigure NextAuth callbacks.</comment>
<file context>
@@ -0,0 +1,114 @@
+
+### CLIENT_FETCH_ERROR
+
+If you experience this error, it may be the way the default Auth callback in the server is using the WEBAPP_URL as a base url. The container does not necessarily have access to the same DNS as your local machine, and therefore needs to be configured to resolve to itself. You may be able to correct this by configuring `NEXTAUTH_URL=http://localhost:3000/api/auth`, to help the backend loop back to itself.
+
+```
</file context>
|
|
||
| #### Production Build | ||
|
|
||
| For a production build, **please make sure** to set up [E2E testing](/docs/developing/local-development#e2e-testing) and [Upgrading](/upgrading) the database from earlier version, and the proceed to build as follows: |
Contributor
There was a problem hiding this comment.
P2: The E2E testing link points to /docs/developing/local-development, but there is no corresponding page in apps/docs/content, so this link will be broken in the new docs site. Update the link to an existing page or add the missing doc.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/content/installation.mdx, line 63:
<comment>The E2E testing link points to `/docs/developing/local-development`, but there is no corresponding page in `apps/docs/content`, so this link will be broken in the new docs site. Update the link to an existing page or add the missing doc.</comment>
<file context>
@@ -0,0 +1,142 @@
+
+#### Production Build
+
+For a production build, **please make sure** to set up [E2E testing](/docs/developing/local-development#e2e-testing) and [Upgrading](/upgrading) the database from earlier version, and the proceed to build as follows:
+
+```bash
</file context>
Contributor
Devin AI is addressing Cubic AI's review feedbackNew feedback has been sent to the existing Devin session. ✅ Pushed commit |
Co-Authored-By: peer@cal.com <peer@cal.com>
- Add app/[[...mdxPath]]/page.tsx catch-all route required by Nextra v4 - Update mdx-components.ts to import from nextra-theme-docs (provides wrapper with sidebar/TOC) - Update tsconfig.json to include .next/types for proper type checking - Add next-env.d.ts generated by Next.js Co-Authored-By: peer@cal.com <peer@cal.com>
Co-Authored-By: peer@cal.com <peer@cal.com>
Co-Authored-By: peer@cal.com <peer@cal.com>
…xt/font/local Co-Authored-By: peer@cal.com <peer@cal.com>
…SemiBold Co-Authored-By: peer@cal.com <peer@cal.com>
Co-Authored-By: peer@cal.com <peer@cal.com>
Co-Authored-By: peer@cal.com <peer@cal.com>
…vin.ai/proxy/github.com/calcom/cal.com into devin/1772632312-nextra-docs
Co-Authored-By: peer@cal.com <peer@cal.com>
…vin.ai/proxy/github.com/calcom/cal.com into devin/1772632312-nextra-docs
…com into devin/1772632312-nextra-docs
Co-Authored-By: peer@cal.com <peer@cal.com>
Co-Authored-By: peer@cal.com <peer@cal.com>
…com into devin/1772632312-nextra-docs
Co-Authored-By: peer@cal.com <peer@cal.com>
…vin.ai/proxy/github.com/calcom/cal.com into devin/1772632312-nextra-docs
Contributor
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="apps/docs/content/index.mdx">
<violation number="1" location="apps/docs/content/index.mdx:49">
P3: Fix the typo in this user-facing docs sentence (`commerical` → `commercial`).</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| Like any diy project, Cal.com, Inc. does not guarantee security and safety of the open source project. Cal.diy is | ||
| community maintained and strictly recommended for personal, non-production use. Please use at your own risk. | ||
|
|
||
| For any commerical usage, please visit Cal.com or request enterprise access to our on-prem hosting: https://cal.com/sales. |
Contributor
There was a problem hiding this comment.
P3: Fix the typo in this user-facing docs sentence (commerical → commercial).
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/content/index.mdx, line 49:
<comment>Fix the typo in this user-facing docs sentence (`commerical` → `commercial`).</comment>
<file context>
@@ -38,3 +38,28 @@ Deploy Cal.com on your preferred platform:
+Like any diy project, Cal.com, Inc. does not guarantee security and safety of the open source project. Cal.diy is
+community maintained and strictly recommended for personal, non-production use. Please use at your own risk.
+
+For any commerical usage, please visit Cal.com or request enterprise access to our on-prem hosting: https://cal.com/sales.
+
+Find all differences in features below:
</file context>
Suggested change
| For any commerical usage, please visit Cal.com or request enterprise access to our on-prem hosting: https://cal.com/sales. | |
| For any commercial usage, please visit Cal.com or request enterprise access to our on-prem hosting: https://cal.com/sales. |
Contributor
Devin AI is addressing Cubic AI's review feedbackNew feedback has been sent to the existing Devin session. ✅ No changes pushed |
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
1 participant
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 does this PR do?
Adds a new Nextra v4 documentation project in
apps/docs/with all self-hosting content extracted from cal.com/docs/self-hosting/installation and its subpages. The documentation structure mirrors the original:Key files:
apps/docs/package.json– Nextra + Next.js 15 + React 19 dependenciesapps/docs/next.config.mjs– Nextra plugin configapps/docs/app/layout.tsx– Root layout with Navbar (SVG logo with dark mode support), Footer, page map, and custom fontsapps/docs/app/logo.css– Dark mode logo toggle CSS (useshtml.darkselector from Nextra's theme)apps/docs/app/fonts.css– Applies Cal Sans to headlines and Cal Sans UI to body text via CSS custom propertiesapps/docs/fonts/– Cal Sans (SemiBold) for headlines + Cal Sans UI (Light/Regular/Medium/SemiBold/Bold) for body text, loaded vianext/font/localapps/docs/app/[[...mdxPath]]/page.tsx– Catch-all route for Nextra v4 App Router MDX renderingapps/docs/mdx-components.ts– ExportsuseMDXComponentsfromnextra-theme-docs(provides sidebar/TOC wrapper)apps/docs/public/cal-docs-logo.svg– Light mode navbar logo (dark text)apps/docs/public/cal-docs-logo-white.svg– Dark mode navbar logo (white text)apps/docs/content/_meta.ts– Root sidebar navigation with separatorsapps/docs/content/**/*.mdx– 30+ MDX content pagesapps/docs/content/**/_meta.ts– Nested navigation definitionsUpdates since initial PR
layout.tsx(explicit type annotations)color-tokens.mdx: "peaks your interest" → "piques your interest"app/[[...mdxPath]]/page.tsxcatch-all route required by Nextra v4 to render MDX content from thecontent/directorymdx-components.tsto import fromnextra-theme-docsinstead ofnextra/mdx-components— the theme's version includes thewrappercomponent that provides the sidebar and table of contentsnext-env.d.tsand updatedtsconfig.jsonto include.next/typescal-docs-logo.svgfor light mode andcal-docs-logo-white.svgfor dark mode, toggled via plain CSS inlogo.css(Tailwinddark:utilities are not available since the docs app doesn't have Tailwind configured)--font-cal, body text uses Cal Sans UI (5 weights: 300–700) via--font-cal-ui. Both loaded withnext/font/localfor optimal performance. Cal Sans UI font files sourced from calcom/sans-ui.Visual Demo
Homepage with Cal Sans headlines and Cal Sans UI body text (light mode):
Navbar logo — light mode:
Navbar logo — dark mode:
Installation page with code blocks and TOC:
Docker page:
GCP deployment page (nested navigation):
Color Tokens guide (confirmed typo fix — "piques"):
next@^15.1.0,react@^19.0.0,nextra@^4.2.0— verify these don't conflict with the existing monorepo workspace versions.yarn installwas not run in the monorepo after adding this workspace, soyarn.lockis not updated. You'll need to runyarnat the root before testing locally./apps/install-apps/google— these should be verified against Nextra's routing behavior. The E2E testing link ininstallation.mdx(/docs/developing/local-development#e2e-testing) points to a page that doesn't exist in this docs project.gcp.mdx, the Docker pull command usescal/calcombut the run command usescal/cal.com— these should match. Also, the "Access Cal.com" step referenceshttp://localhostinstead of the VM's external IP.nextra/mdx-components, but we import fromnextra-theme-docsto get thewrappercomponent that provides sidebar + TOC. This is intentional and correct for the docs theme.logo.css) instead of Tailwind utilities because the docs app doesn't have Tailwind configured. The CSS relies on Nextra adding a.darkclass to thehtmlelement — if Nextra changes this behavior in future versions, the dark mode toggle would break. Using plain<img>tags instead of Next.jsImagecomponent (biome lint warningnoImgElementwas noted but not fixed).fonts.cssfile appliesfont-familydirectly tobodyand all heading tags (h1–h6), which overrides Nextra's default typography. This might conflict with Nextra's built-in styles if they apply fonts with higher specificity. Verify font rendering in different Nextra theme contexts (e.g., code blocks, tables, callouts).Mandatory Tasks (DO NOT REMOVE)
How should this be tested?
yarnat monorepo root to install new workspace dependenciesyarn workspace @calcom/docs devto start the Nextra dev serverChecklist
noImgElementinlayout.tsx)Link to Devin Session: https://app.devin.ai/sessions/66515819d80d417b8e451b38e4d5e3ca
Requested by: @PeerRich