Why self-host Cal.com on a VPS
Cal.com is a Next.js application backed by PostgreSQL that handles appointment scheduling, event types, availability and synchronization with calendars (Google, CalDAV, Office 365). Self-hosting answers a specific need: controlling the availability and appointment-booking data of your clients, which normally passes through a third-party US service. On a VPS, you eliminate the free plan's limits (a single event type, imposed branding), you connect your own Google/video API keys and you embed the booking widget directly into your site under your domain. Since Cal.com is a persistent Node application with a database and a production build, it requires a VPS — shared hosting can neither run the process nor host PostgreSQL.
Concrete benefits of a self-hosted Cal.com
- Unlimited event types: 15-min interviews, 30-min demos, group workshops, without a paywall.
- Booking data on your side: no leak of clients' contact details and time slots to a third-party SaaS.
- Full white-label: the booking link carries your domain, not a vendor's.
- Webhooks and API: trigger automations (CRM, billing) on every appointment booked.
- Google Calendar, CalDAV and video integrations (Jitsi, Google Meet) configured with your own keys.
- Team bookings and round-robin to distribute appointments among several collaborators.
Technical requirements
Cal.com is more demanding than the self-hosting average because of its Next.js foundation and the build step. Plan for 2 vCPUs, 4 GB of RAM and 20 GB of disk for a comfortable team instance; 2 GB of RAM can suffice for individual use but the initial build is tighter. You need Docker and Docker Compose, a PostgreSQL database (included in the official compose), a domain rdv.yourdomain.com pointed at the VPS, and several mandatory environment variables: NEXTAUTH_SECRET, CALENDSO_ENCRYPTION_KEY (randomly generated keys) and NEXT_PUBLIC_WEBAPP_URL set to your final HTTPS URL. For calendar sync and video, prepare the Google OAuth credentials.
Deploy Cal.com step by step
Clone the Docker deployment repository
On the VPS: git clone https://github.com/calcom/docker.git cal-docker && cd cal-docker. This repository provides a docker-compose.yml and an .env.example file to adapt.
Generate the secrets and configure the environment
Copy .env.example to .env, then generate the keys: openssl rand -base64 32 for NEXTAUTH_SECRET and for CALENDSO_ENCRYPTION_KEY. Set NEXT_PUBLIC_WEBAPP_URL=https://rdv.yourdomain.com and the PostgreSQL credentials. Save these three values in a secrets manager immediately — you will not be able to change them after the first boot without losing all your integrations.
Build and launch the stack
Start with docker compose up -d. The first startup builds the Next.js image and applies the Prisma migrations on PostgreSQL — this is the longest step, follow it with docker compose logs -f.
Place the reverse proxy and SSL
Put Cal.com (internal port 3000) behind an HTTPS reverse proxy. With Caddy: rdv.yourdomain.com { reverse_proxy calcom:3000 }. The certificate is obtained automatically. The URL must match NEXT_PUBLIC_WEBAPP_URL exactly, otherwise authentication fails.
Create the account and configure availability
Open https://rdv.yourdomain.com, create the owner account, set your time slots and a first event type. Test an end-to-end booking to validate the chain.
Connect calendar and video
In the integrations, add your Google OAuth credentials for bidirectional calendar sync, and enable Jitsi or Google Meet to automatically generate a video link on each booking.
Logging in for the first time
Open the URL: Cal.com redirects you to its first-run setup wizard (/auth/setup), where you create YOUR administrator account. Do this as soon as the installation finishes: nothing protects this wizard for as long as the first account does not exist.
Cal.com's memory build can fail on a 2 GB VPS during Next.js compilation. If you see a "JavaScript heap out of memory" error, temporarily add a 2 GB swap file (fallocate -l 2G /swapfile && mkswap /swapfile && swapon /swapfile) for the duration of the build, then remove it. For updates, always back up the PostgreSQL database before docker compose pull because the Prisma migrations are not reversible.
Critical first-boot invariants
Three environment variables are permanently locked at Cal.com's first boot. Changing them afterwards silently corrupts all stored integrations: the application restarts normally, shows zero errors, but Google Calendar, Zoom and all OAuth connections stop working — their tokens were encrypted with the original key, which is now incompatible. This behaviour is documented in calcom/docker issue #333 and calcom/cal.diy issue #13290: users have lost all their integrations after an update that regenerated the .env file.
CALENDSO_ENCRYPTION_KEY — encrypts the OAuth tokens stored in the database. Any change silently invalidates all existing integrations.
NEXTAUTH_URL — anchors session cookies. A change breaks authentication for all active users.
NEXT_PUBLIC_WEBAPP_URL — baked into the Next.js build at compile time. Changing this value requires a full rebuild and reconnecting all integrations.
Best practice: copy these three values into a secrets manager (Bitwarden, HashiCorp Vault, Ansible Vault) as soon as they are generated. If you manage your VPS as infrastructure-as-code, store them in an encrypted vault — never let the .env file be their only location.
Updating Cal.com safely
Back up the PostgreSQL database
Before any update: docker exec cal-docker-db-1 pg_dump -U calcom calcom | gzip > /opt/backup/calcom-$(date +%Y%m%d).sql.gz. Prisma migrations are not reversible — this backup is your only safety net.
Verify that CALENDSO_ENCRYPTION_KEY is unchanged
Compare the value in your .env with the one stored in your secrets manager. If they differ, stop here: restore the original value before proceeding. A different key will silently destroy all your OAuth integrations on restart.
Pull the new image and restart
Update with docker compose pull && docker compose up -d. Follow the startup with docker compose logs -f calcom — wait for the message indicating the server is ready before testing.
Verify integrations after the update
Open Settings → Integrations and confirm that every existing connection (Google Calendar, Zoom, etc.) is still active. A "not connected" status means the key changed between restarts — restore the backup and the original .env.
Troubleshooting
Integrations lost after an update — The cause is almost always a CALENDSO_ENCRYPTION_KEY that differs between two startups. Check that your .env was not overwritten by an .env.example during the pull. Compare the current value with the one in your secrets manager. If the values differ: restore the PostgreSQL backup, put the original key back in .env and restart with docker compose up -d.
Build "JavaScript heap out of memory" — The Next.js compiler is running out of RAM. Fix: fallocate -l 2G /swapfile && mkswap /swapfile && swapon /swapfile, then run docker compose build again. On a 2 GB VPS, swap is often essential for the first build and major updates. Remove the swap file once the build is done.
Redirect loop or "Unable to find valid origin" — NEXT_PUBLIC_WEBAPP_URL does not match the actual URL. Check that this variable is exactly https://rdv.yourdomain.com (no trailing slash, correct domain, HTTPS protocol), that the reverse proxy does not alter the Host header, then restart with docker compose up -d --build to force a rebuild with the correct URL.
Automate your PostgreSQL backup with a daily cron job. Example command to schedule: docker exec cal-docker-db-1 pg_dump -U calcom calcom | gzip > /opt/backup/calcom-$(date +%Y%m%d-%H%M).sql.gz. Keep at least 7 days of rotating backups and ship them to object storage (S3-compatible, Backblaze B2): in case of VPS loss, the PostgreSQL database is the only non-reproducible part of your Cal.com instance.
