A guided first run for self-hosted Cal.com
Standing up a self-hosted scheduling platform used to mean guessing at env vars and hoping the first login worked. We rebuilt the initial setup flow so a fresh deployment walks you through creating the first admin and configuring the instance from the browser.
Self-hosting is a promise: your data, your infrastructure, your rules. But that promise falls apart in the first ten minutes if bringing up a new instance feels like defusing a bomb. Which env var seeds the admin? What happens if you point a browser at the root URL before the database is ready? Who owns the first account, and how do you prove it's you?
We wanted the answer to be: just open the URL.
Why a setup flow, not a runbook
The traditional self-hosted onboarding is a README with fifteen steps and a warning at the bottom. That works for the person who deployed the container. It fails everyone else — the ops engineer who inherits the instance, the founder evaluating whether to self-host at all, the admin who redeploys six months later and can't remember which secret does what.
So instead of documenting the first-run state, we made it a first-class product surface. Point a browser at the root URL of a fresh deployment and the instance walks you through creating the first admin account and configuring itself Complete Instance Setup. No shell required to get to a working login.
What it unlocks
The obvious win is time-to-first-booking on a new instance. The less obvious win is that setup becomes inspectable. You can see, in the UI, what an unconfigured instance looks like versus a configured one. That makes it easier to hand off ownership, to script deployments in CI, and to reason about what state your instance is actually in.
It also gives us a clean seam for future setup concerns — SSO defaults, org provisioning, license activation — without asking operators to learn a new CLI subcommand each time.
What's next
This is the foundation, not the finish line. We'll be layering more of the day-one configuration into the same flow so that the gap between docker run and a production-ready instance keeps shrinking. If you're spinning up Cal.com for the first time, the paired help-center article walks through the flow step by step.