* docs: add self-hosting troubleshooting guide
Add a dedicated troubleshooting page (docs/self-hosting/troubleshooting.mdx)
covering the most common self-hosting issues:
- 500 error during onboarding caused by missing STRIPE_PRIVATE_KEY (#25993)
- Redirect to localhost after deployment (NEXTAUTH_URL / NEXT_PUBLIC_WEBAPP_URL) (#21921)
- API v2 service not starting in Docker (missing REDIS_URL, JWT_SECRET, WEB_APP_URL)
- CLIENT_FETCH_ERROR in Docker logs
- SSL issues behind a reverse proxy
- Prisma user creation failure on first setup
Also adds the new page to the "Getting Started" navigation group in docs/docs.json.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
* fix(docs): provide safer SSL troubleshooting alternatives
Replace the blanket NODE_TLS_REJECT_UNAUTHORIZED=0 recommendation
with three options in order of preference:
1. Use HTTP internally with proper header forwarding
2. Add internal CA to NODE_EXTRA_CA_CERTS
3. Disable TLS verification (last resort with security warning)
The previous guidance could expose users to MITM attacks on all
external API calls (Stripe, Google, etc.).
* fix(docs): correct NEXTAUTH_URL guidance to prevent OAuth breakage
The previous guidance recommended setting NEXTAUTH_URL to localhost
for SSL/DNS issues, which breaks OAuth callbacks since external
providers would redirect to localhost instead of the public domain.
- Replace localhost workaround with extra_hosts in docker-compose
- Add nginx proxy header configuration example
- Add warnings explaining why localhost breaks OAuth
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(docs): correct troubleshooting guide based on codebase verification
- Stripe section: Rewrite to accurately reflect current behavior (app
gracefully handles missing keys by marking Stripe as 'not installed'
rather than crashing). Clarify that NEXT_PUBLIC_STRIPE_PUBLIC_KEY
belongs in .env.appStore.
- API v2 section: Add missing required vars (STRIPE_API_KEY,
STRIPE_WEBHOOK_SECRET, NEXTAUTH_SECRET) that crash the service if
absent. Move WEB_APP_URL to optional (it has a fallback default).
- CLIENT_FETCH_ERROR section: Add caveat about HTTPS URLs failing
with the extra_hosts approach when app listens on port 3000.
- Vercel note: Clarify that NEXTAUTH_URL is auto-inferred via
VERCEL_URL, not just 'left empty'.
- Database section: Replace unverifiable metadata/id advice with
actionable migration and setup guidance matching actual code in
apps/web/app/api/auth/setup/route.ts.
Co-Authored-By: romitgabani1 <romitgabani1.work@gmail.com>
* docs: fix inaccuracies in self-hosting troubleshooting guide
- Add missing CALENDSO_ENCRYPTION_KEY to API v2 required variables
- Fix setup endpoint path from /api/auth/setup to /auth/setup
- Add note about NEXTAUTH_URL auto-derivation from NEXT_PUBLIC_WEBAPP_URL
* fix(docs): correct NEXTAUTH_URL derivation mechanism description
NextAuth infers the base URL from the request's Host header when
NEXTAUTH_URL is not set, not from NEXT_PUBLIC_WEBAPP_URL directly.
Co-Authored-By: romitgabani1 <romitgabani1.work@gmail.com>
---------
Co-authored-by: shockzM1 <shockz@dsn.so>
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
- Replace all references from github.com/calcom/docker to github.com/calcom/cal.com
- Update Contributing section to clarify Docker setup is officially maintained in main repository
- Update Getting Started instructions to clone main cal.com repository
- Update Advanced Users section to reference Dockerfile and docker-compose.yml in root of main repo
- Clarify that Dockerfile and docker-compose.yml are located in root of calcom/cal.com repository
Co-authored-by: Udit Takkar <53316345+Udit-takkar@users.noreply.github.com>
* upgrade turborepo from 1 to 2.5
* Fix tsconfig.json paths path
* chore: fix root path on tsconfig.paths
* chore: add baseUrl to tsconfig.json
* chore: tsconfig.json issue
* try: CI without tsconfig paths
* chore: add only local paths on tsconfig.json
* chore: Fix docs
* Fix missing env var on turbo.json
2025-08-18 11:17:27 -03:00
Hariom BalharaGitHubcubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>Syed Ali Shahbaz
* --init
* progress...
* add more docs
* bunch of changes and added back platform
* development guides added
* more guides in develop with cal
* self hosted WIP
* deployments
* fix deployment steps
* self-hosted guides
* ..
* Removed the development only sections
* Removed 'with Cal.com'
* use steps component for steps
---------
Co-authored-by: Keith Williams <keithwillcode@gmail.com>
