From 925be2dfab1aac20a158a27d13af1a62395f06b2 Mon Sep 17 00:00:00 2001 From: shockzM1 Date: Mon, 30 Mar 2026 11:44:46 +0900 Subject: [PATCH 1/2] docs: add env variable checklist and Windows symlink guidance to README setup Expand Step 4 of the installation guide to help users avoid the most common self-hosting misconfiguration issues: - Add a quick-reference table of key environment variables that must be reviewed before starting the app, with notes on when each needs to change (NEXTAUTH_SECRET, CALENDSO_ENCRYPTION_KEY, DATABASE_URL, NEXT_PUBLIC_WEBAPP_URL, NEXTAUTH_URL, EMAIL_FROM) - Add a callout note linking NEXT_PUBLIC_WEBAPP_URL / NEXTAUTH_URL misconfiguration to the common localhost redirect issue - Expand Windows symlink guidance to cover the case where admin privileges were missing at clone time, with the correct git clone command and a link to the Git for Windows symlinks docs Co-Authored-By: Paperclip --- README.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ae8179f5a1ef96..ce39aa2475cfe1 100644 --- a/README.md +++ b/README.md @@ -149,13 +149,35 @@ Here is what you need to be able to run Cal.com. - Duplicate `.env.example` to `.env` - Use `openssl rand -base64 32` to generate a key and add it under `NEXTAUTH_SECRET` in the `.env` file. - Use `openssl rand -base64 24` to generate a key and add it under `CALENDSO_ENCRYPTION_KEY` in the `.env` file. - + + The following variables must be reviewed before starting the app. Most have defaults that work for local development, but **must be changed for production deployments**: + + | Variable | When to change | Example | + |---|---|---| + | `NEXTAUTH_SECRET` | Always — generate with `openssl rand -base64 32` | `abc123...` | + | `CALENDSO_ENCRYPTION_KEY` | Always — generate with `openssl rand -base64 24` | `xyz789...` | + | `DATABASE_URL` | When using a custom/remote database instead of the default local one | `postgresql://user:pass@host:5432/calcom` | + | `NEXT_PUBLIC_WEBAPP_URL` | **Required for any non-localhost deployment** — set to your public domain | `https://cal.yourdomain.com` | + | `NEXTAUTH_URL` | For production deployments; leave empty on Vercel (auto-detected) | `https://cal.yourdomain.com` | + | `EMAIL_FROM` | When you want outgoing emails to show a custom sender address | `Cal.com ` | + + > **Note:** Failing to update `NEXT_PUBLIC_WEBAPP_URL` and `NEXTAUTH_URL` is the most common cause of redirect-to-localhost issues after deployment. + > **Windows users:** Replace the `packages/prisma/.env` symlink with a real copy to avoid a Prisma error (`unexpected character / in variable name`): > > ```sh > # Git Bash / WSL > rm packages/prisma/.env && cp .env packages/prisma/.env > ``` + > + > If you cloned without admin privileges and the symlink was not created, run: + > + > ```sh + > # PowerShell (run as Administrator) + > git clone -c core.symlinks=true https://github.com/calcom/cal.com.git + > ``` + > + > See [Git for Windows symlinks](https://github.com/git-for-windows/git/wiki/Symbolic-Links) for more details. 5. Setup Node If your Node version does not meet the project's requirements as instructed by the docs, "nvm" (Node Version Manager) allows using Node at the version required by the project: From 4a9cd6249b5011a140a28d62a9b8319f9e18a359 Mon Sep 17 00:00:00 2001 From: Sahitya Chandra Date: Tue, 31 Mar 2026 15:49:43 +0530 Subject: [PATCH 2/2] Remove symlink details from README Removed reference to Git for Windows symlinks from README. --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 459231690f1668..86d338a54e87c1 100644 --- a/README.md +++ b/README.md @@ -177,8 +177,6 @@ Here is what you need to be able to run Cal.com. > # PowerShell (run as Administrator) > git clone -c core.symlinks=true https://github.com/calcom/cal.com.git > ``` - > - > See [Git for Windows symlinks](https://github.com/git-for-windows/git/wiki/Symbolic-Links) for more details. 5. Setup Node If your Node version does not meet the project's requirements as instructed by the docs, "nvm" (Node Version Manager) allows using Node at the version required by the project: