OpenWikicalcom/cal.diy

Production Build and Local Setup

Purpose and Scope

This page guides a self-hoster through the source-based setup path for Cal.diy, ending at a production build that can be started locally or adapted for a deployment target. The installation documentation frames Cal.diy as software that can be deployed in several ways inside an existing infrastructure stack, and this page focuses on the non-Docker, repository-clone workflow. It is most useful when you want to inspect the code, configure environment files yourself, prepare app integrations, and build the web application from source rather than starting from a prebuilt container image.

Sources: apps/docs/content/installation.mdx

A source build has two different phases that are easy to confuse. Local setup prepares the repository, installs dependencies, creates environment files, and connects the application to PostgreSQL and app credentials. Production build happens after that preparation, when the project compiles and then starts the web application. The official installation guide emphasizes that the build step is the most intensive part of running Cal.diy, while the running application is comparatively lightweight. That means setup should be treated as an operational task, not only a developer convenience.

Sources: apps/docs/content/installation.mdx

Relevant Source Files

  • apps/docs/content/installation.mdx — Primary installation guide covering requirements, clone commands, environment setup, secret generation, app-store environment setup, and production build commands.
  • apps/docs/content/_meta.ts — Places Installation, Database Migrations, Upgrading, Docker, Apps, and Deployments in the documentation navigation, showing where this page fits in the self-hosting sequence.
  • apps/docs/content/apps/_meta.ts — Lists app credential guides available under the Apps section, including Google, Daily, HubSpot, and other integrations that may need environment values before a useful production run.
  • apps/docs/content/apps/daily.mdx — Documents Daily video credentials, especially the API key and optional scale-plan flag used in the main environment file.
  • apps/docs/content/apps/google.mdx — Documents Google Calendar and Google login credential preparation, redirect URIs, app-store seeding, and shared values for both main and app-store environment files.
  • apps/docs/content/apps/hubspot.mdx — Documents HubSpot OAuth client values, callback URL, and required CRM contacts scope for the HubSpot integration.

Prerequisites and Repository Checkout

Before building, prepare the baseline software stack described by the installation guide: Node.js, yarn, Git, and PostgreSQL. The documentation recommends Node.js version 18 for compatibility and performance, and it names Windows, Mac, Linux, and BSD as supported operating systems because Cal.diy only requires a JavaScript runtime to execute. For production deployments, the same guide suggests Linux as the ideal platform. PostgreSQL is required because Cal.diy uses Prisma for database maintenance, so database access is not an optional add-on for a real source setup.

Sources: apps/docs/content/installation.mdx

Start by cloning the repository and entering the project directory. On ordinary Unix-like systems, the documented clone command is direct. On Windows, the installation guide calls out an alternate clone command using symlink support and admin privileges. That detail matters because a monorepo can contain package and workspace links that behave differently on Windows when symbolic links are disabled. After changing into the repository, run the package installation step so the workspace dependencies are available before configuration, database work, or production compilation.

Sources: apps/docs/content/installation.mdx

git clone https://github.com/calcom/cal.diy.git
cd cal.diy
yarn
git clone -c core.symlinks=true https://github.com/calcom/cal.diy.git

Environment Files and Secrets

The main setup handoff is the environment file. The installation guide instructs you to copy the example environment file into a working file named for local configuration, then fill values using the comments in the template. This is where database connectivity, public URLs, authentication secrets, and integration keys become part of the runtime. Do not treat this as a final polish step after building. The build and start phases assume that important application settings already exist, and deployment platforms may read these values differently from a local shell.

Sources: apps/docs/content/installation.mdx

Generate a strong authentication secret and place it under the documented secret variable. The guide suggests using the OpenSSL base64 command, while also allowing another secret generator if preferred. Preview deployments on Vercel have a special rule in the same installation page: leave selected public URL and authentication URL variables empty for previews. That exception is a useful reminder that URL variables should match the environment where the app actually runs, and that local, preview, and production settings may intentionally differ.

Sources: apps/docs/content/installation.mdx

openssl rand -base64 32

The installation guide also calls out a second environment file for app-store settings. Fill the app-store environment alongside the main environment if you want integrations to appear and work correctly. This matters even for a basic source build because many scheduling features become meaningful only when calendar, video, CRM, payment, or communications apps are configured. The documentation navigation confirms that app setup is a first-class part of the self-hosting guide, not an unrelated customization topic that should be postponed indefinitely.

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

App Credential Preparation

Daily, Google, and HubSpot illustrate the kinds of integration values that belong in the setup phase. Daily requires an API key from the Daily developer dashboard and supports an optional scale-plan flag for features such as video recording. Google setup is broader: enable the Calendar API, configure the OAuth consent screen, select calendar scopes, add test users, create a web OAuth client, and set redirect URIs for both the Google Calendar integration callback and the Google authentication callback. The downloaded OAuth JSON is copied into both the main and app-store environment files.

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

HubSpot follows the same source-build pattern but with CRM-specific OAuth details. The app documentation instructs administrators to create a HubSpot developer app, copy its client ID and client secret into the environment, configure the integration callback URL, and grant read and write access to the contacts object scope. These steps are not required for every installation, but they should be completed before declaring a production build ready if your scheduling workflow depends on CRM meeting creation or contact synchronization after bookings.

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

<Cal.diy URL>/api/integrations/googlecalendar/callback
<Cal.diy URL>/api/auth/callback/google
<Cal.diy URL>/api/integrations/hubspot/callback

Production Build Flow

Only build for production after the repository has dependencies, environment files, secrets, database preparation, and any required integration credentials. The installation documentation explicitly tells operators to set up end-to-end testing and upgrade the database before building for production. It also warns to upgrade the database before the production build. In practice, that means a self-hoster should check migration and upgrade guidance first when moving an existing instance forward, because a successful compile does not prove that the database schema and stored data are compatible with the application that will start afterward.

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

The documented production command sequence is intentionally short once preparation is complete. Run the build command, then start the application. If build failures appear, revisit the earlier setup phases before assuming the source code is broken: missing dependencies, incomplete environment files, absent app-store values, database state problems, or platform-specific clone issues can all surface during or immediately after compilation. Treat the build command as a verification point for the entire setup, and treat the start command as the first runtime validation of URLs, database access, authentication, and enabled integrations.

Sources: apps/docs/content/installation.mdx

yarn build
yarn start

Documentation Map and Next Steps

The documentation metadata places Installation in the Getting Started group and keeps Database Migrations, Upgrading, Docker, Apps, and Deployments nearby in the navigation. That ordering suggests a practical next-step sequence: finish the source setup, confirm the database is current, choose whether Docker or a cloud deployment is more appropriate, and then configure apps needed by your users. If you are preparing a public instance, also read the URL, reverse proxy, and troubleshooting pages in this wiki, because a build that starts locally may still need deployment-specific public URL and callback alignment.

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

For the smallest useful validation, open the running instance, complete the initial setup flow, and test one booking path with the integrations you configured. If Google Calendar is enabled, repopulate the app store as described by the Google app guide so the integration becomes available. If Daily or HubSpot are enabled, verify the corresponding environment values and callback URLs before inviting users. From here, continue to Database Migrations, Upgrading Cal.diy, Apps Overview, and the individual integration pages that match your deployment requirements.

Sources: apps/docs/content/apps/google.mdx, apps/docs/content/apps/daily.mdx, apps/docs/content/apps/hubspot.mdx

Ask a question...