calcom/cal.diy installation guide

Install Cal.diy on macOS Tahoe (Apple silicon)

What you are installing

Cal.diy is the MIT-licensed, community edition of Cal.com: a self-hosted scheduling web application built with Next.js, React, tRPC, Prisma, and PostgreSQL. It has no hosted or managed edition, so the application and its data run on infrastructure you control.

The repository gives an important warning: Cal.diy is intended for **personal, non-production use**. Self-hosting requires responsibility for the database, secrets, updates, backups, network exposure, and sensitive scheduling data. This walkthrough therefore installs it locally on your Mac through Docker Compose. Do not expose this local installation to the internet merely because it opens successfully.

Relationship to Claude Code

**Classification:** repository-local context injection; runs alongside Claude Code; medium confidence.

Cal.diy is primarily a standalone scheduling application, not a Claude Code plugin, Agent Skill, MCP server, or hook. Its `specs` area does, however, describe `CLAUDE.md` files and feature specifications that Claude reads while helping contributors implement features and preserve session continuity. The `agents` area also contains machine-readable engineering rules. That supports classifying its Claude relationship as **context injection through repository files**. The supplied files do not explicitly prove a Claude Code installation mechanism, so installing Cal.diy does not install anything into Claude Code.

Before you begin

For the Docker route documented by the project, you need:

• A Mac with Apple silicon running macOS Tahoe.
• Docker and Docker Compose. The project says both are supplied by common Docker utilities, including Docker Desktop and Rancher Desktop.
• Git, because the documented installation starts by cloning the repository.
• A text editor for changing the `.env` configuration file.
• Enough free storage for the large repository, container images, and PostgreSQL data.

Install and open your chosen Docker desktop application using its normal graphical installer. Wait until it reports that Docker is running. No command-line installation command is included here because the supplied repository files do not document one.

Apple silicon is an ARM platform. The project specifically says that direct Docker image pulls on ARM must use a version tag ending in `-arm`, such as its example `v5.6.19-arm`. A current release version was not supplied, so this guide does not invent a direct `docker pull` command or tell you to use that old example. The documented Docker Compose workflow below is the safest source-supported starting point.

1. Open Terminal and download the repository

Open **Terminal** from Applications → Utilities. Clone the repository, including its submodules, with the command documented for Docker Compose installation:

git clone --recursive https://github.com/calcom/cal.diy.git

When that finishes, enter the new project directory:

cd cal.diy

Keep this Terminal window open. The remaining Docker commands must be run from this directory.

2. Create the local configuration file

The repository supplies an example environment file. Copy it to the `.env` filename used by the application:

cp .env.example .env

Open `.env` in a text editor. Finder can be used to navigate to the cloned `cal.diy` folder if you prefer not to open files from Terminal.

The Docker Compose configuration has a documented default local PostgreSQL URL:

`postgresql://unicorn_user:magical_password@database:5432/calendso`

For the complete local stack, most settings can remain as supplied. Do not publish the sample database password or use this convenience configuration as an internet-facing production system.

3. Generate the two required secrets

Cal.diy requires `NEXTAUTH_SECRET` for cookie encryption and `CALENDSO_ENCRYPTION_KEY` for authentication encryption. The README warns that leaving the default value `secret` is a security risk.

Generate `NEXTAUTH_SECRET`:

openssl rand -base64 32

Terminal prints a random value. Copy that output, find `NEXTAUTH_SECRET` in `.env`, and replace its placeholder with the generated value.

Next, generate the 32-byte AES256 encryption key in the encoding documented by the project:

openssl rand -base64 24

Copy this second output and use it as the value of `CALENDSO_ENCRYPTION_KEY` in `.env`. The resulting entries should have this form, using your actual generated values rather than the angle-bracket placeholders:

NEXTAUTH_SECRET=<your_generated_secret>
CALENDSO_ENCRYPTION_KEY=<your_generated_key>

Save `.env`. Treat it as sensitive: it contains database credentials and cryptographic secrets. The repository also says not to commit real keys to `.env.example`.

For a local installation, the documented default web address is `http://localhost:3000`. `NEXTAUTH_URL` normally defaults to the web application URL followed by `/api/auth`. Avoid changing these values during the initial setup unless you understand the networking implications.

4. Optionally pre-download the container images

The project calls this step optional. With Docker running, you can ask Compose to download the configured images before startup:

docker compose pull

On Apple silicon, pay attention to any architecture or image-tag error. The repository requires an `-arm` suffix for direct ARM image pulls, but the supplied evidence does not document a current version-specific replacement to paste into the Compose configuration. Do not guess a tag. Check the repository’s current release and Docker configuration if Compose reports that no compatible ARM image exists.

5. Start the complete local stack

Start the documented complete stack, which includes the Cal.diy web application, a local PostgreSQL database, and Prisma Studio:

docker compose up -d

The `-d` option starts the services in detached mode, leaving them running after Terminal returns to the prompt. Initial startup can take longer because Docker may need to download images and initialize PostgreSQL.

If startup fails and you need to see live diagnostic output, the README says to remove `-d` from the desired command. Run:

docker compose up

Leave that Terminal window open while using attached mode. Read the output for the first reported error rather than repeatedly starting additional copies.

6. Complete setup in your browser

Visit [http://localhost:3000](http://localhost:3000). On the first run, Cal.diy presents a setup wizard. Define your first user when prompted.

The wizard may show a seemingly required **Connect your Calendar** step. The project says you can postpone calendar integration by navigating directly to [http://localhost:3000/event-types](http://localhost:3000/event-types). Calendar providers can be added later under **Settings → Integrations**. Google, Microsoft, Zoom, Daily, and other integrations require separate provider credentials; they are not needed merely to start the local application.

If the application reports `Error: No key set vapidDetails.publicKey`, Web Push keys are missing. The project documents this generator:

npx web-push generate-vapid-keys

Use it only if `npx` is already available on your Mac. Copy its public and private outputs into `NEXT_PUBLIC_VAPID_PUBLIC_KEY` and `VAPID_PRIVATE_KEY` in `.env`, then restart the stack. The supplied files do not document installing `npx` solely for this optional feature.

Everyday operation and updates

To stop the stack cleanly from the `cal.diy` directory, run:

docker compose down

Your local database is part of the Docker setup, so treat its data as important even though this guide is for personal development use.

The repository’s documented update sequence is to stop the stack, pull updated images, review environment-variable changes, and start it again:

docker compose down

docker compose pull

docker compose up -d

The instruction to “update env vars as necessary” is a manual review step. Before updating, compare the current `.env.example` with your private `.env`, preserve your generated secrets, and do not blindly replace your configuration.

Important limitations

This walkthrough uses the repository’s prebuilt Docker Compose path rather than building the TypeScript monorepo directly. Native development has additional documented prerequisites—Node.js 18 or newer, PostgreSQL 13 or newer, and Yarn—and building a Docker image from source currently requires an available database during the build. Those paths are intended more for contributors than for a first local installation.

Cal.diy’s own warning should govern your use: it is community-maintained and recommended only for personal, non-production deployment. A successful page at localhost confirms that the local app started; it does not establish secure internet hosting, reliable backups, production readiness, or correctly configured third-party integrations.