> For the complete documentation index, see [llms.txt](https://docs.dapta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dapta.ai/dcal/developers/self-hosting.md).

# Self-hosting

Run your own copy of dCal: the requirements, SQLite for development and PostgreSQL for production, the quickstart commands, the sign-in, email and calendar options, booking pages on a host of their ow

dCal runs anywhere Node or Docker runs: a single virtual machine, Docker Compose, Kubernetes or a platform of your choice. This page is a map. The authoritative instructions live in the repository and change with the code:

| Repository file                                                                                                    | What it covers                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`README.md`](https://github.com/Dapta-Tech/dapta-calendars-slate/blob/main/README.md)                             | The local quickstart, with no database or accounts to set up.                                                                                                            |
| [`SELF-HOSTING.md`](https://github.com/Dapta-Tech/dapta-calendars-slate/blob/main/SELF-HOSTING.md)                 | The production guide: images, database, the full environment reference, reverse proxy and TLS, sign-in, email, calendar backend, upgrades, rollback and troubleshooting. |
| [`.env.example`](https://github.com/Dapta-Tech/dapta-calendars-slate/blob/main/.env.example)                       | Every setting with inline notes and its default.                                                                                                                         |
| [`docker-compose.prod.yml`](https://github.com/Dapta-Tech/dapta-calendars-slate/blob/main/docker-compose.prod.yml) | A production-shaped reference stack you can bring up with one command.                                                                                                   |

***

## Requirements

* **Node 20.9 or newer and pnpm 10 or newer**, only if you build from source. Or **Docker with Docker Compose** to build and run the two images.
* **PostgreSQL 14 or newer** for production, with the `btree_gist` extension. The first migration creates the extension; if your database role cannot, have a database superuser run `CREATE EXTENSION IF NOT EXISTS btree_gist;` once.
* **A reverse proxy that terminates TLS**, such as nginx, Caddy, Traefik or a cloud load balancer, in front of two hostnames: one for the web app (port `3000`) and one for the API (port `4000`).

***

## SQLite or PostgreSQL

`DATABASE_URL` picks the database:

|                           | SQLite                                             | PostgreSQL                                                                                                                   |
| ------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL`            | `file:./.data/dev.db`, the default when unset      | `postgres://<user>:<password>@<host>:5432/<database>`                                                                        |
| Use it for                | Trying dCal and local development, with zero setup | Every real deployment                                                                                                        |
| Double-booking protection | A check inside the app only                        | The same check, plus a database constraint that makes two overlapping bookings (accepted or pending) for one host impossible |

> **⚠️ Note:** Never run production on SQLite. It lacks the database constraint that is dCal's hard guarantee against double bookings.

Migrations are numbered SQL files. Run them before the API starts, never inside the long-running API process, so several API copies never migrate at once:

```bash
DATABASE_URL=postgres://<user>:<password>@<host>:5432/<database> pnpm db:migrate
```

Schema changes are additive (new tables, new nullable columns), so you can migrate a live database during a rolling deploy.

***

## Quickstart

### Run it on your computer

```bash
git clone https://github.com/Dapta-Tech/dapta-calendars-slate.git calendars && cd calendars
pnpm install
pnpm dev
```

`pnpm dev` builds the packages, creates and fills a SQLite database at `.data/dev.db`, and starts both apps:

* **Web**: <http://localhost:3000>, with a demo booking page at `/acme/alex-rivera/intro-call`.
* **API**: <http://localhost:4000/health>.

Email is `log-only`, so confirmations print to the API log. `pnpm db:reset` puts the demo data back. To run against PostgreSQL in Docker instead, the same engine as production, use `pnpm dev:pg`; if port `5432` is taken on your machine, set `PG_PORT`, for example `PG_PORT=5433 pnpm dev:pg`.

### Bring up the production images

`docker-compose.prod.yml` builds the same two images a production deployment uses, runs the migrations once in a one-shot `migrate` service, then starts the API and the web app against a local PostgreSQL:

```bash
POSTGRES_USER=calendars POSTGRES_DB=calendars \
POSTGRES_PASSWORD=<a-strong-password> \
DATABASE_URL=postgres://calendars:<a-strong-password>@db:5432/calendars \
docker compose -f docker-compose.prod.yml up --build
```

Then open `http://localhost:3000` (web) and `http://localhost:4000/health` (API). This stack is a smoke test: it runs with `NODE_ENV=development` and the open development sign-in. For a real deployment, set `NODE_ENV=production` together with a real sign-in provider (see below).

### Build the two images

Both Dockerfiles take the repository root as the build context:

```bash
docker build -f apps/api/Dockerfile -t calendars-api:local .
docker build -f apps/web/Dockerfile \
  --build-arg NEXT_PUBLIC_API_URL=https://calendars-api.example.com \
  -t calendars-web:local .
```

> **⚠️ Note:** Every `NEXT_PUBLIC_*` value is baked into the web image when you build it, not read when the container starts. If you move the API or change any of those values, rebuild the web image.

***

## Sign-in

Public booking pages are always open. Sign-in only protects the dashboard, and `AUTH_PROVIDER` picks how it works. Set the same value on the API and on the web app.

| `AUTH_PROVIDER`   | What it does                                                                                                                                                                                                                         | When to use it                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `local` (default) | An open development stub: anyone who types an email is signed in as that person. The API refuses to start with it when `NODE_ENV=production`.                                                                                        | Trying dCal and local development only. |
| `workos`          | Despite its name, a generic token check: the API accepts any HS256 JWT signed with your `JWT_SECRET` that carries the claims `sub`, `account_id`, `email` and `name`. `JWT_ISSUER` and `JWT_AUDIENCE` are checked when you set them. | Every real deployment.                  |

What to know before you pick `workos`:

* `account_id` names the workspace. The first person to sign in to a workspace becomes its owner; people who arrive later become members, unless an invitation gave them another role.
* The web app needs `WEB_SESSION_SECRET` to sign its session cookie. It refuses to issue a session without it.
* In production (`NODE_ENV=production`) the sign-in cookies are `__Host-` cookies marked `Secure`, so people must reach the web app over `https` (or on `localhost`). A proxy that terminates TLS in front of it is fine.
* The web app's sign-in sends people to an identity service at `IAM_BASE_URL`, which hands back a sign-in address and returns the signed-in person to `/api/auth/callback` with their token. Read the routes under `apps/web/app/api/auth/` in the repository before you connect your own identity service: they are the contract it has to follow.

`SELF-HOSTING.md` also shows how to mint a test token for local work.

***

## Email

Nothing is emailed until you choose a provider with `EMAIL_PROVIDER`. Until then, booking emails are written to the API log, so a fresh deployment still runs end to end.

| `EMAIL_PROVIDER`     | What happens                                                                                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `log-only` (default) | Emails are printed to the API log.                                                                                                                                                                      |
| `noop`               | Emails are dropped silently. Useful in tests.                                                                                                                                                           |
| `smtp`               | Sent through any SMTP server: set `SMTP_HOST`, and `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER` and `SMTP_PASS` as your server needs.                                                                        |
| `http`               | Each email is posted to an HTTP email service at `EMAIL_HTTP_ENDPOINT`, either as a provider-agnostic JSON body with an optional Bearer token (`generic`) or with signed requests (`transactional-v1`). |

Set `MAIL_FROM_EMAIL` and `MAIL_FROM_NAME` before you send anything real, and `MAIL_SUPPORT_EMAIL` to print a support address in the email footer (with the `transactional-v1` profile, the email service's own support footer replaces that line). A provider that is missing its settings falls back to `log-only` rather than stopping the API.

***

## Calendar options for your copy

The public code talks to calendars through a vendor-neutral contract. `CALENDAR_PROVIDER` decides whether it talks to calendars at all:

| Option                                                                             | What you get                                                                                                                                                                                                                                                                |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CALENDAR_PROVIDER=disabled` (default)                                             | No external calendar. Open times subtract only dCal's own bookings, nothing is written to a calendar, and no online meeting links are created. Fine for a deployment that does not need calendar sync.                                                                      |
| `CALENDAR_PROVIDER=external` with `CALENDAR_API_BASE_URL` and `CALENDAR_API_TOKEN` | dCal calls your own calendar service through a small, documented REST contract: free/busy reads, creating, moving and deleting events, listing calendars, checking a connection and starting the connect flow. `SELF-HOSTING.md` lists every route and what it must return. |
| `CALENDAR_PROVIDER=external` with `CALENDAR_BACKEND_MODULE`                        | An absolute path to your own JavaScript module that supplies the base URL, the tokens and the request mapping. For a backend that mints its own short-lived tokens or needs a different request shape.                                                                      |

Three rules matter when you write a backend:

* **Free/busy answers must be complete.** dCal reads busy times in windows of up to 14 days (`CALENDAR_BUSY_WINDOW_DAYS`). If one window fails, dCal shows no times rather than times that might be taken. If a window comes back with only part of the busy times, the missing ones look free, so page through your upstream results before you answer.
* **One meeting link per booking.** When dCal asks for a meeting link it does so on the organizer's event only. If you cannot create one, return the event without it: the booking still stands and the confirmation goes out without a join link. dCal asks for one on online meetings and on bookings with no location, never on the others.
* **Invitations follow `sendInvitations`.** Create, move and delete calls can carry `sendInvitations`, in the body (on a delete, as `?sendInvitations=`). `false` means dCal emails the guest its own invite for that change: write the event without your calendar's own invitation, update or cancellation, or the guest is invited twice. `true` asks for them, and absent leaves it to your backend. dCal sends `true` when its email cannot stand in for yours, for example when `EMAIL_PROVIDER` is `log-only` or `noop`. If a guest's email never goes out, dCal asks for the invitation later on the organizer's event: one update without the guest (`false`), then one with the full guest list (`true`), so replace the guest list with the one you get. A `404` or `410` answer to a delete counts as done.

The hosted app.dcal.ai connects Google Calendar and Outlook through its own private backend, which is not part of the public repository.

***

## HubSpot and webhooks

* Set `CRM_PROVIDER=hubspot` to offer the [HubSpot](https://docs.dapta.ai/dcal/integrations/hubspot.md) integration on **Settings** > **Integrations**.
* Set `INTEGRATION_ENCRYPTION_KEY` to 32 random bytes in base64 (`openssl rand -base64 32`). dCal needs it to store a HubSpot token and to create a webhook, because it refuses to keep either secret unencrypted. With HubSpot switched on but no key, the **Integrations** tab says *Credentials cannot be stored here yet*, and adding a webhook is refused.

> **⚠️ Note:** Back this key up the way you back up the database. If you lose or change it, every workspace has to paste its HubSpot token again and every webhook needs a new signing secret, and webhook deliveries fail until it is fixed.

***

## Booking pages on a host of their own

On app.dcal.ai, booking pages live on `https://book.dcal.ai`, apart from the dashboard, so the tags a host adds to an event never share an address with a signed-in session. Your copy can do the same: the dashboard on one host, such as `app.<your-domain>`, and the booking pages (personal, team, one-off links and the guest's manage page) on another, such as `book.<your-domain>`.

| Variable                 | Set on                      | What it does                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PUBLIC_BOOKING_URL`     | Web and API, the same value | The booking host, as an origin. It serves every booking page, sends the dashboard's pages to `PUBLIC_APP_URL`, and answers the app's own `/api` routes with `404`, except `/api/availability`. Every link dCal writes names it: manage links in emails, MCP booking links, and the dashboard's copy, open and embed snippets. Unset, or blank, booking pages stay on `PUBLIC_APP_URL`. |
| `BOOKING_HOST_REDIRECTS` | Web                         | `off` (the default), `temporary` (307) or `permanent` (308). With `temporary` or `permanent`, every other host answers a booking page's `GET` with a redirect to the same path and query on the booking host.                                                                                                                                                                          |

Move in steps, each undone by reverting its setting:

1. Point the new host at the web app. Set `PUBLIC_BOOKING_URL` on the **web app first**, and once every web instance runs with it, on the **API**. `PUBLIC_APP_URL` must be set on the web app too. Both hosts now serve booking pages, and new links name the new one.
2. Once every kind of page and your real traffic answer on the new host, set `BOOKING_HOST_REDIRECTS=temporary`; after a stable month, `permanent`.

To roll back, go in reverse: take `PUBLIC_BOOKING_URL` off the API first, then off the web app. Once the setting names another host, the web app stops reading the older name of its session cookie, so a session that has not moved to the `__Host-` name signs in once more. After tags have run on the booking host, `SELF-HOSTING.md` recommends taking the setting off the API only and keeping it on the web app, unless the booking host itself has to go.

What keeps working during the move:

* A `POST` is served where it lands, such as a tab left open.
* `/api/availability` and `embed.js` answer on both hosts.
* An embed's frame is never redirected, so a site that allows only the old host as a frame source keeps booking. New embed snippets name the booking host.
* A page that checks `event.origin` on the embed's messages must accept the booking host's origin for new snippets.

***

## Tracking and pixels

Owners and admins can set tracking tags on each event type. A **Meta Pixel** and a **PostHog** project (US or EU cloud) need nothing from you: they load only the vendor's own code. A self-hosted PostHog address is refused.

**Google Tag Manager**, **Google Analytics 4** and **HubSpot** are different: a host's own account can make them run any code. With booking pages on their own host (`PUBLIC_BOOKING_URL` set on the web app and the API), every workspace may use them, and they start only on that host. Without it, they would run on the same address as the dashboard and its session, so they load only for the workspaces you name:

| Variable                  | Default                   | What it does                                                                                                                                                                                                                                    |
| ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EVENT_TRACKING_ACCOUNTS` | unset, which means nobody | API. The workspaces that may load Google Tag Manager, Google Analytics 4 and HubSpot on their booking pages: account short codes or custom links, separated by commas, or `*` for every workspace. Not needed once `PUBLIC_BOOKING_URL` is set. |

Name only workspaces you trust, and use `*` only when every workspace on the deployment is yours. Taking a workspace off the list takes its Google Tag Manager, Google Analytics 4 and HubSpot off its pages at once; its other tags stay. Where none of the three is allowed, the event editor says that this deployment does not offer them on booking pages yet.

***

## Repeating events and attendee checks

To support [repeating events](https://docs.dapta.ai/dcal/developers/mcp-tools.md#repeating-events) on your own installation, the calendar adapter must write one calendar series, move or cancel individual occurrences, and update the series rule. A calendar connection that cannot do this returns `RECURRENCE_UNSUPPORTED`; dCal never silently writes just the first date.

For the generic REST backend, set `CALENDAR_BACKEND_FEATURES=recurrence,attendee-free-busy` only when both contracts are implemented. `recurrence` enables series writes and occurrence updates. `attendee-free-busy` enables read-only checks of the people's calendars the host is allowed to see. Either feature can be declared on its own. A calendar the provider cannot show must be unknown, never an empty busy list that would mean free. The request and response contracts are in [`SELF-HOSTING.md`](https://github.com/Dapta-Tech/dapta-calendars-slate/blob/main/SELF-HOSTING.md#repeating-events-and-other-peoples-busy-times).

Series, video links and attendee availability each depend on the capabilities of the host's connected calendar. dCal checks those capabilities before creating a series or requesting a video link. A connection that does not support attendee checks reports those calendars as unknown. Your adapter determines which capabilities your installation offers.

Series initially block dCal dates up to 180 days after the later of now and their first start. With `OUTBOX_WORKER_ENABLED=true`, the API checks once an hour to add dates entering that horizon, first running about one minute after startup. It skips this work in tests or when the outbox worker is off. Keep the worker running as part of your installation. There are no separate series-extender environment settings.

Without a connected calendar, a repeating focus block must end within that initial 180-day horizon. Later dates are protected by the connected calendar, not by dates that dCal has not materialized yet. Video requests also require a calendar that can create the link; unsupported requests return `VIDEO_UNSUPPORTED`.

***

## Behind a proxy

* `RATE_LIMIT_TRUSTED_PROXY_HOPS` is how many proxies sit in front of the API (default `1`). Get it right, or every visitor is counted as one client by the rate limiter.
* Set `INTERNAL_API_SECRET` to the same value (at least 32 characters) on the API and the web app, and set `API_URL` on the web app to the API's private address. The booking pages then pass each visitor's address to the API, so each visitor gets their own rate-limit allowance instead of sharing the web server's.
* If saving a booking page fails with a "too large" message, raise your proxy's request size limit. A host's photo and cover are saved with the page; nginx's default of 1 MB is too small, so raise it to at least 4 MB on both the web and API upstreams.

***

## AI assistants, analytics and search engines

* **The MCP server is on by default** at `/mcp` on your own API (on app.dcal.ai it is at `https://mcp.dcal.ai/mcp`): the tools for public booking pages answer anyone; the other tools answer API keys, and also sign-ins once you turn sign-in on. Set `MCP_PUBLIC_URL` on the API and the web app to the exact address people should paste, and `API_PUBLIC_URL` on the web app, so **Connect your agent** shows them, the left menu gets an **API docs** item that opens your API's `/docs`, and the agent skill can be downloaded from **API keys**. To turn it off, set `MCP_ENABLED=false`.
* **Sign-in for AI apps (OAuth) is off by default.** It lets people connect Claude, ChatGPT and other apps by signing in instead of pasting a key, in one of two ways:
  * **Through an authorization server you already run**, the way app.dcal.ai works: set `OAUTH_ENABLED=true`, `MCP_PUBLIC_URL` and `OAUTH_AUTHORIZATION_SERVER`. That server must support resource indicators (RFC 8707), with `MCP_PUBLIC_URL` registered as a resource so its tokens carry it as their audience; sign its tokens with RS256 or ES256 and publish its keys; and let MCP apps register, with Client ID Metadata Documents or Dynamic Client Registration. Your web sign-in must also record each person's user ID from that server: `SELF-HOSTING.md` explains how. Only owners and admins who signed in to the web app within `OAUTH_LINK_MAX_AGE_DAYS` can connect. Send `/.well-known/oauth-protected-resource` (and the paths under it) and `/.well-known/oauth-authorization-server` on the host of `MCP_PUBLIC_URL` to the API.
  * **With the built-in authorization server**: set `OAUTH_ENABLED=true` with `MCP_PUBLIC_URL`, `OAUTH_ISSUER` and `OAUTH_SIGNING_JWK`. Send `/oauth/` and `/.well-known/oauth-authorization-server` on the issuer's host, and `/.well-known/oauth-protected-resource` on the host of `MCP_PUBLIC_URL`, to the API. People approve each app on a consent page, which only owners and admins can do, and **API keys** lists the connected apps. A new connection can only read at first: the first time someone asks their agent to book, move or cancel, their app asks them to approve that too, and **Connect your agent** says so.
* **Connect your agent follows your setup.** With the MCP server on, sign-in for AI apps on (either way) and `MCP_PUBLIC_URL` set, it shows one tab per app, as on app.dcal.ai. Otherwise it says **The connector is not available on this installation** and names the settings to turn on. API keys work either way, from **API and webhooks** > **API keys**.
* **The Docs item in the left menu** appears only when you set `DOCS_URL` on the web app, and `DOCS_URL_ES` for people who use the dashboard in Spanish. Point it at your own help pages, or leave it unset.
* **The API reference at `/docs`** links to your own developer guides only when you set `DEVELOPER_DOCS_URL` on the API. Unset, its introduction has no guides link.
* **Product analytics is off** unless you set `PRODUCT_ANALYTICS_PROVIDER` and `PRODUCT_ANALYTICS_KEY`.
* **Search engines** may read your booking pages and never your dashboard. On a staging or preview copy, set `NOINDEX=1` on the web app to keep the whole site out.
* **Several API copies** can share one database: the background queue hands each delivery to one copy at a time, and takes it over from a copy that stops. Rate limits are counted by each copy on its own.

See [Environment variables](https://docs.dapta.ai/dcal/developers/environment-variables.md) for every setting and its default.

***

## What is different from app.dcal.ai

| On app.dcal.ai                                                                                                                              | On your own copy                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| You sign in with your Dapta account.                                                                                                        | You connect your own identity service, or use the open development sign-in to try it.                                                                                                                        |
| Workspaces come from your Dapta account.                                                                                                    | Workspaces come from the `account_id` in your own tokens.                                                                                                                                                    |
| Google Calendar and Outlook connect from **Calendars**.                                                                                     | No calendar sync until you plug in a calendar backend.                                                                                                                                                       |
| Booking pages live on `https://book.dcal.ai`, apart from the dashboard.                                                                     | Booking pages share the web app's address until you set `PUBLIC_BOOKING_URL`.                                                                                                                                |
| Every workspace can add Google Tag Manager, Google Analytics 4 and HubSpot tags to its events.                                              | Those three load only for the workspaces in `EVENT_TRACKING_ACCOUNTS`, until you give booking pages a host of their own. Meta Pixel and PostHog work either way.                                             |
| Booking emails are sent for you.                                                                                                            | Nothing is sent until you configure SMTP or an HTTP email service.                                                                                                                                           |
| Hiding the Dapta branding and the custom link come with a Dapta AI subscription.                                                            | `PREMIUM_FEATURES=open`, the default, unlocks both for everyone.                                                                                                                                             |
| HubSpot is ready to connect.                                                                                                                | Set `CRM_PROVIDER` and `INTEGRATION_ENCRYPTION_KEY` first.                                                                                                                                                   |
| dCal's MCP server for AI assistants is at `https://mcp.dcal.ai/mcp`. You connect by signing in with your Dapta account, or with an API key. | The MCP server answers at `/mcp` on your API by default. Sign-in for AI apps stays off until you set `OAUTH_ENABLED`, with your own authorization server (`OAUTH_AUTHORIZATION_SERVER`) or the built-in one. |
| Dapta runs backups, upgrades and security fixes.                                                                                            | You do. Until a 1.0 release, only the latest `main` gets security fixes.                                                                                                                                     |
| Support comes from Dapta.                                                                                                                   | Support is the repository: issues and pull requests on GitHub.                                                                                                                                               |

Everything else, the booking pages, events, availability, teams, emails, reminders, the design studio, webhooks, the REST API and the Cal.com-compatible API, is the same product.

***

## Upgrades and rollback

* **Upgrade:** pull or rebuild the new images, run the pending migrations, then roll out the API and the web app. Because migrations only add things, an older copy keeps working while a newer one starts.
* **Roll back:** deploy the previous image tags. No down-migration is needed.
* **One exception:** the migration that moved meeting locations into their own column also rewrote stored data. Rolling back across it does not restore the old text, so take a database snapshot before an upgrade if you may need a true point-in-time rollback. `SELF-HOSTING.md` names the migration.

***

## Common startup problems

| What you see                                                                                                           | What to do                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The API stops at startup with an environment error                                                                     | Read the list it prints. Every setting is checked at startup and a bad value names the variable. Check `DATABASE_URL`, and `JWT_SECRET` when `AUTH_PROVIDER=workos`.                                                                                                                                                                            |
| *Refusing to boot: AUTH\_PROVIDER=local*                                                                               | You set `NODE_ENV=production` with the development sign-in. Switch to `workos` with its secret.                                                                                                                                                                                                                                                 |
| A migration fails on `CREATE EXTENSION btree_gist`                                                                     | Have a database superuser create the extension once, then run the migrations again.                                                                                                                                                                                                                                                             |
| The web app calls the wrong API address                                                                                | `NEXT_PUBLIC_API_URL` is baked in at build time. Rebuild the web image with the right value.                                                                                                                                                                                                                                                    |
| Booking emails never arrive                                                                                            | `EMAIL_PROVIDER` is still `log-only`. Configure `smtp` or `http`.                                                                                                                                                                                                                                                                               |
| The API stops at startup with `CALENDAR_PROVIDER=external`                                                             | No calendar backend is configured. Set `CALENDAR_API_BASE_URL` and `CALENDAR_API_TOKEN`, or `CALENDAR_BACKEND_MODULE`, or go back to `disabled`.                                                                                                                                                                                                |
| *Refusing to boot: OAUTH\_ENABLED=true but the authorization server is not configured*                                 | Read the list under it and set what it names. With your own authorization server: `MCP_PUBLIC_URL` and `OAUTH_AUTHORIZATION_SERVER`, written exactly as a bare origin. With the built-in one: `MCP_PUBLIC_URL`, `OAUTH_ISSUER` (an `https://` origin, no path) and `OAUTH_SIGNING_JWK` (an EC P-256 private key). Or set `OAUTH_ENABLED=false`. |
| **Connect your agent** says *The connector is not available on this installation*                                      | The MCP server does not take a sign-in yet. Set `MCP_ENABLED=true` (the default) and `OAUTH_ENABLED=true` with an authorization server on the API, and `MCP_PUBLIC_URL` on the web app, then restart.                                                                                                                                           |
| **API keys** says *The skill is not available on this installation*                                                    | The web app has no public API address. Set `API_PUBLIC_URL`, or `MCP_PUBLIC_URL`, on the web app and restart it.                                                                                                                                                                                                                                |
| The left menu has no **API docs** item                                                                                 | The web app has no public API address. Set `API_PUBLIC_URL`, or `MCP_PUBLIC_URL`, on the web app and restart it.                                                                                                                                                                                                                                |
| A signed-in app's tools answer `NOT_LINKED`, *This sign-in is not an owner or admin of any account on this server yet* | The person must be an active owner or admin and have signed in to the web app within `OAUTH_LINK_MAX_AGE_DAYS`, and your web sign-in must record their user ID from the authorization server. Once that is true, the next call works with no reconnect. See `SELF-HOSTING.md`.                                                                  |
| Nobody can sign in to the dashboard in production                                                                      | The sign-in cookies need `https`. Serve the web app over `https`, for example behind a proxy that terminates TLS.                                                                                                                                                                                                                               |

## Related

* [Environment variables](https://docs.dapta.ai/dcal/developers/environment-variables.md): every setting, its default and what it does.
* [REST API](https://docs.dapta.ai/dcal/developers/rest-api.md): the endpoints your deployment exposes.
* [Security and privacy](https://docs.dapta.ai/dcal/security-and-privacy.md): how secrets and links are protected, and how to report a vulnerability.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dapta.ai/dcal/developers/self-hosting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
