Host Cal.com on Your VPS: Complete Docker Guide

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.

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.

Cal.com listens on port 3000 inside the container. A HTTPS reverse proxy is required for two reasons: exposing port 443 and forwarding the correct Host header — otherwise NEXT_PUBLIC_WEBAPP_URL no longer matches the real origin and authentication redirects break.

With Caddy (recommended, automatic certificate):

rdv.yourdomain.com {
    reverse_proxy calcom:3000
}

Caddy obtains and renews the Let's Encrypt certificate without additional configuration.

With nginx, add this block to your configuration:

server {
    listen 443 ssl;
    server_name rdv.yourdomain.com;
    ssl_certificate     /etc/letsencrypt/live/rdv.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/rdv.yourdomain.com/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

In both cases, the URL must match NEXT_PUBLIC_WEBAPP_URL exactly: no trailing slash, HTTPS, correct subdomain. A single character difference produces infinite redirects or a blank screen.

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.

CLIENT_FETCH_ERROR on page load — Since early 2026, all new Docker installations encounter this error on first load. Cause: the Next.js container tries to resolve NEXTAUTH_URL (your public domain) from inside the Docker network, where external DNS is not reachable. Fix: add NEXTAUTH_URL_INTERNAL=http://calcom:3000 to your .env and restart with docker compose up -d. This variable forces NextAuth to call its own API internally, without going through the public domain. Documented in calcom/cal.diy issue #27668 (February 2026, 8 comments confirming the error on all recent Docker distributions).

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 forwards the Host header correctly, then restart with docker compose up -d --build to force a rebuild with the correct URL.

Prisma migrations stuck on startup — If the container restarts in a loop with migration errors, the database may not yet be ready. Wait a few seconds and run docker compose restart calcom. If the problem persists, check the PostgreSQL logs with docker compose logs db.

Once Cal.com is running, several steps to harden the installation: enable alerts on SSL certificates to anticipate expirations, set up HTTP monitoring (Uptime Kuma, Better Uptime) on https://rdv.yourdomain.com/api/health, and restrict the container's port 3000 to 127.0.0.1 so it is no longer directly reachable. For team installations, the reverse proxy can serve multiple Cal.com instances behind distinct subdomains from a single VPS — see deploying with Coolify for simplified multi-service management. The official Cal.com documentation also covers SMTP configuration for confirmation emails and Stripe integration for paid bookings.