> 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/dforms/developers/environment-flags.md).

# Feature flags & environment

The environment settings a self-hosted dForms deployment can change that your users actually notice: demo form seeding, premium features, the Made with dForms badge, deployment wide tracking IDs, emai

A self-hosted deployment is configured entirely through environment variables. Most of them are plumbing, meaning database, ports and secrets, and are covered in [Self-hosting](https://docs.dapta.ai/dforms/developers/self-hosting.md). This page lists the ones that change **what people see**, so you can tell why your instance behaves differently from app.dforms.ai.

None of these apply to the hosted product: on app.dforms.ai these choices are already made for you.

> **⚠️ Note:** Anything starting with `NEXT_PUBLIC_` is a **build time** value, baked into the web image when you build it. Changing it means rebuilding and redeploying the web image, not restarting a container.

***

## New workspaces

| Setting          | Default | What your users see                                                                                                                                                                                                                                         |
| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SEED_DEMO_FORM` | `true`  | Whether a brand new workspace starts with a ready made demo form to poke at, or an empty **Forms** list. Set it to `false` to ship empty workspaces. Other first run settings can take precedence over it: `.env.example` spells out the exact interaction. |

***

## Premium features

dForms itself is free and has no plans to unlock. The gate exists only so a deployment can put its own entitlements in front of the optional extras.

| Setting                | Default | What your users see                                                                                                                                           |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PREMIUM_FEATURES`     | `open`  | `open` unlocks everything, which is what a fork gets and what you almost certainly want. `locked` checks each feature against an entitlement service instead. |
| `ENTITLEMENTS_API_URL` | unset   | Required only when `PREMIUM_FEATURES=locked`: the service that answers the entitlement check.                                                                 |
| `ENTITLEMENTS_API_KEY` | unset   | The credential for that service. Required only when `PREMIUM_FEATURES=locked`.                                                                                |

***

## Naming and cross links

| Setting                     | Default | What your users see                                                                                   |
| --------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_PRODUCT_NAME`  | `Forms` | The product name shown around the UI.                                                                 |
| `NEXT_PUBLIC_PLATFORM_URL`  | empty   | Adds the platform row to the app switcher. Unset renders neither it nor the platform navigation item. |
| `NEXT_PUBLIC_CALENDARS_URL` | empty   | Adds a calendars link to the app switcher.                                                            |

***

## Deployment wide tracking IDs

These are the marketing tags rendered on **public form pages only**, never in the dashboard. Each tag loads only when its ID is set, so a deployment with all of them unset loads no tracking scripts. The only other third-party script a public form can load is the [spam protection](#spam-protection) check, and only on a form that turns it on. They are defaults for the whole deployment, and a form's own settings under **Connect** override them per form. See [Tracking & pixels](https://docs.dapta.ai/dforms/connect/tracking-and-pixels.md).

| Setting                           | What your users see                                                                                  |
| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_GTM_ID`              | Loads a Google Tag Manager container on every public form page.                                      |
| `NEXT_PUBLIC_META_PIXEL_ID`       | Fires one Meta Pixel PageView per visit.                                                             |
| `NEXT_PUBLIC_POSTHOG_KEY`         | Captures one PostHog pageview per visit.                                                             |
| `NEXT_PUBLIC_POSTHOG_HOST`        | The PostHog ingestion URL. Defaults to PostHog US cloud, so set it for an EU or self-hosted project. |
| `NEXT_PUBLIC_HUBSPOT_TRACKING_ID` | Loads the HubSpot tracking code for your portal on public form pages.                                |

> **⚠️ Note:** These tags belong to the **form owner** and measure their respondents. They are not your deployment's own product analytics, which is a separate set of variables with deliberately different names so the two can never be pointed at the same key.

***

## Email

Nothing is emailed until you choose a provider. Until then, submission notices are written to the API log, so a fresh deployment still runs end to end.

| Setting           | Default             | What your users see                                                                                                                                                                                                                     |
| ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EMAIL_PROVIDER`  | `log-only`          | `log-only` prints notices to the log, `noop` drops them silently, `smtp` sends over SMTP, `http` posts each message to a mail API. Until this is set, [submission emails](https://docs.dapta.ai/dforms/connect/emails.md) never arrive. |
| `MAIL_FROM_EMAIL` | `forms@example.com` | The sender address on every email. Change it before you send anything real.                                                                                                                                                             |
| `MAIL_FROM_NAME`  | `Forms`             | The sender name shown in the inbox.                                                                                                                                                                                                     |

***

## Rate limits and destinations

| Setting                     | Default                                | What your users see                                                                                                                                                                                              |
| --------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RATE_LIMIT_ENABLED`        | `true`                                 | Whether the public form and submission endpoints are throttled at all.                                                                                                                                           |
| `RATE_LIMIT_CAPACITY`       | `60`                                   | The burst allowance per client IP address.                                                                                                                                                                       |
| `RATE_LIMIT_REFILL_PER_SEC` | `1`                                    | How fast that allowance builds back up. See [Public API & rate limits](https://docs.dapta.ai/dforms/developers/public-api.md).                                                                                   |
| `TRUST_PROXY_HOPS`          | `1` when a public URL is set, else `0` | How many trusted proxies sit in front of the API. Set it wrong and every visitor shares one bucket, so real respondents start seeing throttle errors.                                                            |
| `HUBSPOT_PRIVATE_APP_TOKEN` | unset                                  | Set it and HubSpot works for the whole deployment: the **Integrations** page shows **Provided by the server** instead of asking each account to connect. Unset, the HubSpot card reports a clear disabled state. |

***

## Integrations and scheduling

Each integration below is optional. Leave its settings out and the app keeps working: the **Integrations** page says the app is not available on this deployment instead of offering a button that could only fail, and forms that already use it still render. All of these are read by the API when it starts, so changing one means restarting the API, not rebuilding an image.

| Setting                                                                             | Default                                          | What your users see                                                                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FORMS_ENCRYPTION_KEY`                                                              | unset                                            | The key every stored connection is encrypted with: a base64 encoded 32 byte key (`openssl rand -base64 32`). Unset, the **Integrations** page says *Connecting is unavailable* on every app a person would connect themselves, and no HubSpot, Calendly, Google Sheets, Salesforce or HighLevel connection can be made. |
| `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`, `GOOGLE_OAUTH_REDIRECT_URI` | unset                                            | Turn on the Google Sheets destination. All three or none: with any one missing, Google Sheets shows *Not available on this deployment*, `GET /v1/integrations` lists it under `unavailable`, and an agent that adds a Google Sheets destination is refused. Also needs `FORMS_ENCRYPTION_KEY`.                          |
| `GOOGLE_PICKER_API_KEY`                                                             | unset                                            | Lets a person pick a spreadsheet they already have. Unset, the Google Sheets card offers only **Create a new spreadsheet**.                                                                                                                                                                                             |
| `GOOGLE_PICKER_APP_ID`                                                              | the project number at the start of the client id | The Google Cloud project number. Set it only when your client id does not start with it.                                                                                                                                                                                                                                |
| `DCAL_API_BASE_URL`, `DCAL_APP_URL`                                                 | unset                                            | Offer [dCal](https://docs.dapta.ai/dcal/dcal.md) as a scheduler. Both or neither. Unset, the scheduler step offers Calendly only, `list_integrations` reports `dcal: null`, and a form that already names dCal still renders.                                                                                           |

### Google Sheets

1. In Google Cloud, create an OAuth client of type **Web application** and turn on the **Google Sheets API** in the same project.
2. Add your API's own callback as an authorized redirect URI, `https://<your API origin>/v1/integrations/google-sheets/callback`, and set the same string, character for character, in `GOOGLE_OAUTH_REDIRECT_URI`. Google compares the text, not the host.
3. Optional: turn on the **Google Picker API** in the same project and create a browser API key restricted by HTTP referrer to your web app's origin. That key reaches the browser by design, so the referrer restriction is what protects it.

dForms asks only for the `drive.file` permission, so it reaches only the spreadsheets it created or the ones a person picked, and the consent screen needs no Google verification. Each workspace then connects its own Google account on the **Integrations** page.

### Salesforce

Nothing to set beyond `FORMS_ENCRYPTION_KEY`. Each workspace connects its own org on the **Integrations** page with three values from an External Client App: the org's My Domain, the consumer key and the consumer secret. If your API's outbound traffic goes through an allowlist, let it reach `*.my.salesforce.com`, `*.salesforce.com` and `*.force.com`.

### HighLevel

Nothing to set beyond `FORMS_ENCRYPTION_KEY`. Each workspace connects one sub-account on the **Integrations** page with a Private Integration token and the sub-account's Location ID. If your API's outbound traffic goes through an allowlist, let it reach `services.leadconnectorhq.com`.

### dCal

`DCAL_API_BASE_URL` is the dCal API the Forms API calls. `DCAL_APP_URL` is the dCal app a visitor's browser loads, and the base of both the booking pages embedded in forms and the link to create an event type (`<DCAL_APP_URL>/admin/event-types`). With only the first set, every booking link would be relative, so dCal reports itself unavailable instead: the dCal card on the **Integrations** page reads **Not available here**, and a Scheduler question says *dCal is not available on this deployment.*

There is no dCal token. The scheduler picker forwards the signed-in author's own session to dCal, so each author sees exactly the event types they can see in dCal. A deployment whose sign-in is the local development stub has no session to forward and cannot offer dCal. For the same reason, neither an API key nor the MCP connector can list dCal event types.

> **⚠️ Note:** If a proxy in front of the web app adds a Content-Security-Policy, allow the host of `DCAL_APP_URL` in `frame-src`. The booking page is embedded in an iframe, both in the public form and in the editor's canvas.

***

## File uploads

The **File upload** question only exists on a deployment that has somewhere to put the files. `STORAGE_BUCKET` is the switch: unset, which is what a bare fork gets, the question type cannot be published and the upload endpoint answers `404`, so a clone with no bucket still runs end to end.

| Setting                                               | Default     | What your users see                                                                                                                                 |
| ----------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STORAGE_BUCKET`                                      | unset       | The bucket uploads are written to. Setting it turns the **File upload** question on for the whole deployment.                                       |
| `STORAGE_REGION`                                      | `us-east-2` | The bucket's region. A mismatch fails the request rather than writing somewhere else.                                                               |
| `STORAGE_PROVIDER`                                    | unset       | Set it to `none` to keep a bucket configured but turn the feature off. It is not how you turn storage on: the bucket is.                            |
| `STORAGE_ENDPOINT`                                    | unset       | Point it at an S3-compatible service such as Cloudflare R2 or MinIO. Most self-hosted servers also need `STORAGE_FORCE_PATH_STYLE=true`.            |
| `STORAGE_ACCESS_KEY_ID` / `STORAGE_SECRET_ACCESS_KEY` | unset       | Only for a deployment with no instance or workload role to attach. On a pod with a role, leave both unset and the SDK finds the credentials itself. |
| `UPLOAD_MAX_FILE_MB`                                  | `10`        | The hard ceiling per file. A form owner can ask for less on their own question, never more.                                                         |
| `UPLOAD_PRESIGN_TTL_SEC`                              | `600`       | How long an upload address stays valid.                                                                                                             |
| `UPLOAD_DOWNLOAD_TTL_SEC`                             | `300`       | How long a link to read a file back stays valid.                                                                                                    |

The browser uploads straight to the bucket, so the bucket's CORS rules have to allow the origin your forms are served from. Allow `PUT` for the upload itself, and `GET` as well if you want Word documents to preview in the dashboard, since that is the one kind the dashboard fetches rather than pointing the browser at.

***

## Spam protection

The **Spam protection (captcha)** switch in a form's **Connect** tab only works on a deployment with Cloudflare Turnstile keys. Both keys unset, which is what a bare fork gets, means the feature does not exist: the switch shows *Spam protection is not set up on this deployment.* and no form loads anything from Cloudflare. See [Spam protection (captcha)](https://docs.dapta.ai/dforms/connect/spam-protection.md) for what the check does.

| Setting                     | Default | What your users see                                                                                                                                                           |
| --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CAPTCHA_SITE_KEY`          | unset   | With `CAPTCHA_SECRET_KEY`, turns the feature on. It is public by design: it reaches the browser inside the published form's data, never through a `NEXT_PUBLIC_` build value. |
| `CAPTCHA_SECRET_KEY`        | unset   | The secret the API verifies every check with. It never leaves the API.                                                                                                        |
| `CAPTCHA_PROVIDER`          | unset   | Set it to `none` to keep the keys loaded but turn the check off everywhere. It is not how you turn it on: the keys are.                                                       |
| `CAPTCHA_VERIFY_TIMEOUT_MS` | `2500`  | How long the API waits for Cloudflare on each attempt, at most `4000`. One retry follows an outage, inside a total of 4 seconds.                                              |

A few rules to get right:

* **Set both keys or neither.** One key without the other stops the API from booting, and so does `CAPTCHA_PROVIDER=turnstile` without them. Only the API needs them; the web app needs nothing.
* **Register the right host.** Create a **Managed** widget in Cloudflare for the host your forms are served from, the host of `PUBLIC_APP_URL`. The API checks that each token was issued there. Forms embedded on other sites need nothing more, because the check runs inside the form's own frame.
* **Let the traffic through.** The API must be able to reach `https://challenges.cloudflare.com`. If a proxy in front of the web app sets a Content-Security-Policy, allow `https://challenges.cloudflare.com` in `script-src` and `frame-src`.
* **Keep test keys out of production.** Cloudflare's test keys are for local and CI runs. The API logs a warning when it starts with a test secret, because that secret accepts any token.

***

## Where the full list lives

These are the user visible ones. The complete reference, including every secret, port and database setting, lives in the repository:

* [`.env.example`](https://github.com/Dapta-Tech/dapta-forms/blob/develop/.env.example): every variable with its default and an inline explanation of what it does.
* [`SELF-HOSTING.md`](https://github.com/Dapta-Tech/dapta-forms/blob/develop/SELF-HOSTING.md): the same variables grouped by concern, with the ones that are required for a real deployment called out.

Server settings are validated when the API starts. A bad value, such as one spam protection key without the other, stops the boot with a message naming the variable and the reason, rather than starting up in a broken state.

***

## What's next

* [Self-hosting](https://docs.dapta.ai/dforms/developers/self-hosting.md): the deployment itself.
* [Public API & rate limits](https://docs.dapta.ai/dforms/developers/public-api.md): what the throttle settings above actually do.
* [Tracking & pixels](https://docs.dapta.ai/dforms/connect/tracking-and-pixels.md): the per form version of the tracking IDs.


---

# 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/dforms/developers/environment-flags.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.
