* 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>
