OpenWikicalcom/cal.diy

Installation Requirements

Purpose and Scope

This page explains what must be ready before installing Cal.diy from source. The installation documentation frames Cal.diy as a self-hostable scheduling platform that can be deployed in multiple ways, but the source-based path starts with a small set of local tools, a database, and environment files. Treat these requirements as a readiness checklist rather than a complete installation guide: the goal is to confirm that the host machine, developer workstation, or server can clone the project, install dependencies, connect to PostgreSQL, and later run the production build workflow without avoidable setup failures.

Sources: apps/docs/content/installation.mdx

Cal.diy has modest runtime expectations, but the installation guide calls out an important distinction: building the software is the most intensive phase, while the running application is comparatively lightweight. That means a small self-hosted instance can be practical, but the machine still needs enough memory, CPU, disk, and network stability to complete dependency installation and application build steps. If a deployment target is constrained, prepare a stronger build environment first, then run the built service on the intended host when your deployment model allows that split.

Sources: apps/docs/content/installation.mdx

Relevant Source Files

  • apps/docs/content/installation.mdx - Primary installation guide with the requirements list, supported operating systems, Node.js recommendation, clone command, dependency installation step, environment-file setup, secret generation, app-store environment note, and production build warning.
  • apps/docs/content/_meta.ts - Documentation navigation metadata that places Installation in the Getting Started section alongside database migrations, upgrading, Docker, apps, and deployments.
  • apps/docs/content/apps/_meta.ts - App documentation navigation metadata listing supported integration setup pages such as Google, Daily, HubSpot, Microsoft, Zoom, Sendgrid, Stripe, Twilio, and Zoho.
  • apps/docs/content/apps/daily.mdx - Optional Daily video integration prerequisite page, including the Daily API key and optional scale-plan variable used when enabling Daily features.
  • apps/docs/content/apps/google.mdx - Optional Google Calendar integration prerequisite page, including OAuth consent, calendar scopes, redirect URIs, credentials, environment keys, and app-store repopulation.
  • apps/docs/content/apps/hubspot.mdx - Optional HubSpot integration prerequisite page, including client credentials, OAuth redirect URL, contacts scope, and the environment variables needed for HubSpot.

Baseline Runtime Requirements

The core software requirements are Node.js, yarn, Git, and PostgreSQL. The installation documentation also states that Prisma is used for database maintenance, so PostgreSQL should be available before treating the application as installable. The docs do not attempt to replace each tool’s upstream installation guide; instead, they direct readers to normal operating-system package managers or vendor documentation. For Linux and BSD administrators, the expected path is to install the required packages from the distribution’s package sources and then configure PostgreSQL according to that platform’s conventions.

Sources: apps/docs/content/installation.mdx

Node.js version selection matters. The installation guide explicitly recommends Node.js 18 for the development environment because it offers the desired balance of stability, features, and security for this project. The same requirements section says Cal.diy can run anywhere JavaScript execution is available and names Windows, Mac, Linux, and BSD as known-good operating systems. For production deployments, however, the docs recommend Linux as the ideal platform, so teams planning a durable instance should prefer a Linux server even if local preparation happens elsewhere.

Sources: apps/docs/content/installation.mdx

Git is not just a convenience in the source-based path; it is the first installation action. The production-build instructions begin by cloning the repository, then changing into the newly cloned directory and installing dependencies with yarn. Windows users get a special cloning note: the guide instructs them to use an option that enables symlink support and to do so with administrator privileges. That requirement is easy to overlook, but it should be handled before dependency installation because broken or missing symlinks can create confusing failures later in a monorepo.

Sources: apps/docs/content/installation.mdx

Operating System and Database Readiness

A practical readiness check starts with the operating system, then the database. Because Cal.diy is known to work on several desktop and server platforms, local evaluation does not require a specific distribution. Production planning is different: the docs steer operators toward Linux, and the database should be installed, reachable, and administratively understood before Cal.diy is configured. PostgreSQL is a required service, not an optional add-on, because the application depends on database state and the installation guide ties database maintenance to Prisma.

Sources: apps/docs/content/installation.mdx

Before moving into application-specific setup, confirm that PostgreSQL can accept connections from the environment where Cal.diy will run. The installation source does not prescribe a particular PostgreSQL tutorial, but it gives the intended research pattern: use the operating system and database version together when finding setup instructions, such as a distribution-specific PostgreSQL guide. This matters because package names, service management, authentication defaults, and firewall behavior differ across operating systems. Cal.diy’s own setup becomes much easier when the database is already verified independently.

Sources: apps/docs/content/installation.mdx

Environment Files and Secrets

After cloning and installing dependencies, the source-based setup moves into environment configuration. The installation guide instructs readers to copy the example environment file and rename the copy so the application has a working configuration template. The same section explains that this file includes comments for settings that must or may be set. It also requires a generated secret for authentication: the documented method is to use a base64 random value and place it under the authentication secret field in the environment file.

Sources: apps/docs/content/installation.mdx

The setup has two environment surfaces to keep in mind. The main environment file covers the web application and core runtime settings, while a separate app-store environment file is used for keys that enable integrations. The installation guide says to fill out the app-store environment file similarly to the main one. It also includes a Vercel-specific preview deployment caution: certain URL environment variables should be left empty for preview deployments. Even if you are not using Vercel, this warning is a useful reminder that URL variables are deployment-context-sensitive.

Sources: apps/docs/content/installation.mdx

Optional Integration Prerequisites

Cal.diy can be installed without every third-party integration enabled, but app features require provider credentials. The app documentation metadata lists the supported setup pages under the Apps section, while individual pages describe the prerequisites for each provider. Daily needs an API key copied from the Daily dashboard into the environment file, and an optional scale-plan variable can enable features such as video recording. These are not generic application requirements, but they become prerequisites if the installation is expected to support Daily video meetings from the start.

Sources: apps/docs/content/apps/_meta.ts, apps/docs/content/apps/daily.mdx

Google Calendar setup is more involved because it uses OAuth. The Google app page walks through enabling the Calendar API, configuring the OAuth consent screen, selecting calendar scopes, adding test users, creating a web OAuth client, and registering redirect URIs for both the Google Calendar integration callback and Google authentication callback. It then instructs readers to put the downloaded OAuth JSON into both the main environment file and the app-store environment file. After credentials are present, the docs say to repopulate the app store so Google Calendar appears as an available app.

Sources: apps/docs/content/apps/google.mdx

HubSpot is another optional integration with its own pre-installation work. The HubSpot page requires a developer account, a created app, client ID and client secret values, an OAuth redirect URL pointing back to the Cal.diy instance, and read/write access for the contacts object scope. The resulting credentials belong in the environment file under HubSpot-specific fields. If bookings should create HubSpot meetings immediately after launch, complete this provider setup before treating the installation as finished; otherwise, defer it until after the core instance is running.

Sources: apps/docs/content/apps/hubspot.mdx

Pre-Install Checklist and Next Steps

Use the following checklist before continuing to the production build or local setup guide: choose a supported operating system, prefer Linux for production, install Node.js 18, install yarn and Git, prepare PostgreSQL, confirm you understand Prisma-backed database maintenance, clone with symlink support on Windows, install dependencies, create the main environment file, generate the authentication secret, and prepare the app-store environment file if integrations are needed. Once these requirements are satisfied, continue with the source-based build flow, API setup, cron-job setup, database migration guidance, or the relevant app integration page.

Sources: apps/docs/content/installation.mdx, apps/docs/content/_meta.ts, apps/docs/content/apps/_meta.ts

Ask a question...