Cal.com Guide for Developers

Cal.com is an open‑source scheduling platform that lets developers embed booking experiences directly into apps. This guide walks you through the core concepts, initial setup, typical workflows, advanced patterns, and the pitfalls most teams encounter. By the end you will have a working Cal.com instance and a clear roadmap for extending it.

Table of contents

• 1. Conceptual Overview
• 2. Quick Setup (Docker)
• 3. Core Workflows
• 4. Advanced Patterns
• 5. Common Mistakes
• 6. FAQ

1. Conceptual Overview

Cal.com consists of three main layers: the API server, the React front‑end, and the data store. The API follows a REST‑plus‑GraphQL hybrid, exposing endpoints for events, users, and integrations. The front‑end renders booking pages using React components that call the same API. All data lives in PostgreSQL, which stores users, event types, availability rules, and webhook logs.

Key concepts you’ll use daily:

• Event Types – reusable templates (e.g., 30‑minute demo, 15‑minute intake).
• Availability Slots – rules that translate into free/busy windows.
• Integrations – connectors for Google Calendar, Office 365, Zoom, etc.
• Webhooks – push notifications for created or cancelled bookings.

2. Quick Setup (Docker)

The fastest way to start is the official Docker compose file. It runs the API, web UI, and PostgreSQL in three containers.

2.1 Prerequisites

• Docker Engine ≥ 20.10
• Docker Compose ≥ 2.2
• Port 80 (or 443) free on the host

2.2 Steps

1. Clone the repo:

   git clone https://github.com/calcom/cal.com.git && cd cal.com

2. Copy the example env file:

   cp .env.example .env

3. Edit .env:
   • DATABASE_URL=postgresql://cal:cal@postgres:5432/cal
   • NEXT_PUBLIC_WEBAPP_URL=http://localhost
   • Set NEXTAUTH_SECRET to a 32‑byte random string (e.g., openssl rand -hex 16).
4. Start containers:

   docker compose up -d

5. Run migrations:

   docker compose exec web npm run prisma:migrate

6. Visit http://localhost and create the first admin user.

2.3 Self‑Hosted vs SaaS Comparison

3. Core Workflows

3.1 Creating an Event Type

In the admin UI go to Event Types → New. Fill the form:

• Name: “30‑minute product demo”.
• Duration: 30 min.
• Location: Zoom (requires Zoom integration).
• Availability: “Weekdays 9 am‑12 pm”.

Save. The system generates a public URL like https://cal.com/yourteam/demo.

3.2 Integrating Google Calendar

1. Open Google Cloud Console → APIs & Services → Credentials.
2. Create OAuth client ID (Web application).
3. Authorized redirect URI: https://yourdomain.com/api/auth/callback/google.
4. Copy client ID and secret to Cal.com Settings → Integrations → Google Calendar.
5. Enable “Read/write” scope to let Cal.com create events.

3.3 Handling Webhooks

Cal.com can POST JSON to any endpoint when a booking occurs. Set the webhook URL in Settings → Webhooks. Example payload:

{
  "event_type":"booking.created",
  "payload":{
    "id":"bk_01F8Z3",
    "start":"2026-07-01T14:00:00Z",
    "end":"2026-07-01T14:30:00Z",
    "user":{"id":"usr_123","email":"dev@company.com"},
    "metadata":{"custom_field":"value"}
  }
}

Validate the signature header using the secret you configured.

3.4 Embedding the Booking Widget

Use the script tag provided by Cal.com or render the React component directly.

<script src="https://cal.com/embed.js"></script>
<div data-cal-link="yourteam/demo"></div>

For React projects:

import { BookingPage } from '@calcom/ui';
function Demo() { return <BookingPage eventType="demo" />; }

4. Advanced Patterns

4.1 Custom Availability Logic

Default rules are static. For dynamic availability (e.g., block holidays from an external API) use the availability webhook. Return a JSON array of { start, end } intervals. Cal.com will merge these with the static rules.

4.2 Multi‑Tenant SaaS Mode

Cal.com supports a “team” model out of the box. To turn it into a full SaaS product:

• Enable TEAM_MODE=true in .env.
• Implement a custom tenantResolver that maps subdomains (acme.cal.com) to team IDs.
• Store branding (logo, colors) per team in a separate table and load it in getServerSideProps.

4.3 Server‑Side Rendering (SSR) of Booking Pages

Next.js supports SSR out of the box. Create pages/[team]/[slug].tsx and fetch the event type with getServerSideProps. This improves SEO for public calendars.

4.4 Scaling with Kubernetes

When traffic exceeds a few hundred bookings per minute, move to K8s:

1. Build a custom Docker image with docker build -t yourrepo/cal.com:latest .
2. Create a Deployment with replicas: 3 and a HorizontalPodAutoscaler targeting CPU > 70%.
3. Expose via an Ingress that terminates TLS (let’s encrypt).
4. Use a managed PostgreSQL service (e.g., Amazon RDS) with read replicas for analytics.

5. Common Mistakes

• Missing environment variables. The app will start but API calls fail with 500 errors. Always run npm run env:check before deployment.
• Running without a reverse proxy. Directly exposing port 3000 leaks server headers and disables HTTP/2. Use Nginx or Traefik.
• Using default JWT secrets. The starter NEXTAUTH_SECRET is “secret”. Replace it with a cryptographically strong value.
• Storing passwords in .env on a public repo. Use secret managers (AWS Secrets Manager, Vault) for production.
• Neglecting timezone handling. Cal.com stores UTC internally. Always convert user‑provided times to UTC before saving.

6. FAQ

What is the difference between Cal.com SaaS and self‑hosted?

SaaS runs on Cal.com’s servers, includes automatic updates and support, and costs $12‑$30 per month per active user. Self‑hosted runs on your own infrastructure, you manage updates and scaling, but you avoid recurring fees. The self‑hosted Docker image starts at $0, plus hosting costs.

Which database does Cal.com require?

Cal.com officially supports PostgreSQL 13‑15. SQLite works for local testing but is not recommended for production because it lacks clustering and robust backup features.

How do I enable OAuth with Google on Cal.com?

Create a Google Cloud project, enable the Google+ API, generate OAuth client ID and secret, then add them in the Cal.com admin UI under Settings → Integrations → Google Calendar. Set redirect URL to https://your‑domain.com/api/auth/callback/google.

Can I customize the booking page UI?

Yes. Cal.com exposes a React component library. You can replace the default <BookingPage/> with your own component, or override CSS variables via the theme-config.json file. The UI is built with Tailwind, so you can add any Tailwind class.

What are the most common deployment mistakes?

Skipping environment variable validation, running the app without a reverse proxy, and using default secrets in production are frequent errors. Always set NODE_ENV=production, configure HTTPS termination, and rotate all JWT secrets before launch.

---

With this guide you should be able to install Cal.com, create booking flows, and extend the platform for your own product. Start small, test each integration, and iterate. The open‑source community updates the code weekly, so keep an eye on the GitHub releases for security patches and new features.