Troubleshooting Onboarding and Setup

Purpose and Scope

Use this page when a new self-hosted Cal.diy instance starts but the first practical setup tasks do not behave as expected. In this context, onboarding means the early path from cloning the repository, installing dependencies, preparing environment files, running the web app, and confirming that the first user can complete the initial product setup. The documented failures in this area usually come from missing prerequisites, incomplete secret generation, mismatched URL configuration, or optional integration variables being mistaken for required core setup. This page keeps the troubleshooting flow focused on those early checks before moving into deeper Docker, API, or database diagnosis.

Sources: apps/docs/content/troubleshooting.mdx, apps/docs/content/installation.mdx

Cal.diy is intentionally self-hosted, so the local environment is part of the product surface. The installation guide describes a source-based path that begins with cloning the repository, entering the project directory, installing dependencies with Yarn, creating environment files from examples, generating a secret for authentication, and then building and starting the web app. The troubleshooting guide adds symptom-driven fixes for common self-hosting mistakes, including Stripe-related onboarding confusion and redirects that still point to a local development URL after deployment. Read these two documents together: one defines the expected baseline, and the other explains what to correct when that baseline is incomplete.

Sources: apps/docs/content/installation.mdx, apps/docs/content/troubleshooting.mdx

Relevant Source Files

• apps/docs/content/troubleshooting.mdx — Defines the self-hosting troubleshooting guide, including onboarding and setup issues, Stripe payment feature behavior, URL redirect failures, and environment-variable corrections.
• apps/docs/content/installation.mdx — Defines the source installation workflow, supported operating system expectations, required tools, environment-file setup, secret generation, app-store environment setup, production build commands, and database-upgrade warning.

Establish the Setup Baseline

Before investigating a first-user or setup-screen failure, confirm that the installation state matches the documented baseline. The installation guide expects Node.js, Yarn, Git, and PostgreSQL to be available, with Node.js version 18 specifically recommended for compatibility. It also states that Cal.diy is known to work on Windows, Mac, Linux, and BSD, while recommending Linux for production deployments. That matters because an onboarding symptom may be a downstream effect of a missing database, a dependency installation that never completed cleanly, or a runtime that differs from the version the project documentation recommends.

Sources: apps/docs/content/installation.mdx

The source-based setup sequence is simple but order-sensitive. Clone the repository, change into the cloned directory, run the dependency installation, copy the environment example into a real environment file, generate a secret, populate app-store configuration when integrations are needed, and only then build and start the web application. If onboarding fails immediately after a fresh checkout, do not begin by changing application code. Re-check that the environment file exists, that the authentication secret was generated and assigned, and that the application was restarted after configuration changes. These are configuration-state problems, not usually product-flow problems.

Sources: apps/docs/content/installation.mdx

git clone https://github.com/calcom/cal.diy.git
cd cal.diy
yarn
openssl rand -base64 32
yarn build
yarn start

On Windows, the installation guide calls out a special clone form with symlink support and administrator privileges. That detail is easy to overlook during setup troubleshooting because the failure may appear later as a dependency, package, or build problem rather than as a clone problem. If a Windows-based installation reaches onboarding with unexplained missing files or broken package behavior, repeat the earliest setup checks and verify that the repository was cloned with symlinks enabled. For production builds, the guide also warns to upgrade the database before building, so a stale database should be treated as a setup blocker rather than an unrelated runtime issue.

Sources: apps/docs/content/installation.mdx

Environment Files and Secrets

Most onboarding-adjacent failures should be reduced to the environment files first. The installation guide instructs operators to copy the example environment file to a real environment file and use it as the commented template for required and optional settings. It also instructs the operator to generate a secret and place it under the authentication secret setting. Separately, it points to an app-store environment file for integration keys. The practical rule is to separate core boot settings from optional integration settings: the web app needs its baseline configuration to start correctly, while integrations can remain disabled until their credentials are intentionally supplied.

Sources: apps/docs/content/installation.mdx

NEXTAUTH_SECRET=generated_secret_value
.env.appStore contains integration keys when apps are enabled

For preview deployments on Vercel, the installation guide says to leave several URL-related variables empty. That is a special deployment mode, not a general self-hosting recommendation. If a self-hosted deployment sends users to the wrong host during login or onboarding, compare the deployment style against the environment-file guidance before changing application routes. A preview environment that lets the platform infer URLs is different from a fixed-domain deployment where the application must know the external web address. Mixing these assumptions can make the first login or setup redirect look broken even when authentication itself is functioning.

Sources: apps/docs/content/installation.mdx, apps/docs/content/troubleshooting.mdx

Common Setup Failure Patterns

A frequent early confusion is that payment-related features appear unavailable during setup or app-store configuration. The troubleshooting guide explains that Stripe requires variables split across the root environment file and the app-store environment file. If those variables are missing or empty, the Stripe app is marked as not installed and payment-related features are unavailable. This is not necessarily a failed onboarding state for the whole application. If paid events and payment integration are not part of the initial deployment goal, the guide explicitly allows those values to remain empty, with the understood consequence that Stripe features stay disabled.

Sources: apps/docs/content/troubleshooting.mdx

STRIPE_PRIVATE_KEY=sk_test_...
STRIPE_CLIENT_ID=ca_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLIC_KEY=pk_test_...

Another common symptom is a deployment that still redirects to a local development address. The troubleshooting guide identifies the cause as missing or incorrect public web app and authentication URL settings. For a fixed production domain, set the public web app URL and authentication URL to the deployed domain, and do not include a trailing slash. This affects onboarding because login and internal navigation are often the first flows a new administrator exercises. If the browser leaves the deployed domain during sign-in, the first-user setup may appear unavailable even though the underlying server is reachable.

Sources: apps/docs/content/troubleshooting.mdx

NEXT_PUBLIC_WEBAPP_URL=https://cal.yourdomain.com
NEXTAUTH_URL=https://cal.yourdomain.com

The redirect fix has deployment-specific timing rules. The troubleshooting guide notes that Docker deployments must set the public web app URL before building the image because the value is inlined by the Next.js build. Changing it after the image is already built requires rebuilding the image, not merely restarting a container with a new variable. The same section also notes that Vercel deployments do not need the authentication URL because Vercel can infer the deployment URL. When troubleshooting setup, always ask whether the failing value is read at build time, runtime, or inferred by the hosting platform.

Sources: apps/docs/content/troubleshooting.mdx

Triage Flow

Start with the smallest reproducible symptom. If the application does not build, return to prerequisites, dependency installation, the database-upgrade warning, and the environment-file copy step. If the application builds but onboarding or login loops to the wrong place, focus on URL variables and whether the deployment needs a rebuild. If the application works but an integration-specific setup panel is missing functionality, check whether that app has credentials in the root or app-store environment file. This ordering prevents optional app configuration from being confused with core application readiness, and it keeps first-user troubleshooting grounded in documented setup contracts.

Sources: apps/docs/content/installation.mdx, apps/docs/content/troubleshooting.mdx

After every environment correction, restart or rebuild at the level implied by the variable. A generated authentication secret in the normal environment file requires the running application to reload configuration. A public web app URL in a Docker image requires rebuilding because it is treated as a build-time value. Stripe variables require both the web-facing secret values and the public app-store value to be present before payment features should be expected to appear. Keeping a short change log while troubleshooting helps separate the fix that changed behavior from unrelated edits, especially during the first installation when many settings are new.

Sources: apps/docs/content/troubleshooting.mdx, apps/docs/content/installation.mdx

Next Steps

If these checks do not resolve setup, move outward by symptom rather than by guesswork. Redirects and hostnames belong with environment and URL troubleshooting. HTTPS and proxy behavior belongs with reverse proxy and SSL guidance. API v2 startup failures belong with the API and database troubleshooting page, because the troubleshooting source describes separate API service environment requirements outside this onboarding scope. Payment-specific issues belong with the Stripe payments integration page. For a clean first install, the most useful next step is to re-run the documented setup checklist, confirm the environment files, rebuild when required, and only then inspect service logs.

Sources: apps/docs/content/troubleshooting.mdx, apps/docs/content/installation.mdx