> 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/self-hosting.md).

# Self-hosting

Run your own copy of dForms: the two apps, the Docker images, PostgreSQL in production, the handful of settings that matter and what changes when you leave the hosted app.dforms.ai.

dForms is deployment agnostic: it is plain Node, with no host-only APIs, so it runs on Docker, Kubernetes, a single virtual machine or anything in between. This page is a map. The authoritative instructions live in the repository and are kept up to date with the code.

| Repository file                                                                                             | What it covers                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`README.md`](https://github.com/Dapta-Tech/dapta-forms/blob/develop/README.md)                             | The local development loop: clone, install, run. No database or accounts required.                                                                                      |
| [`SELF-HOSTING.md`](https://github.com/Dapta-Tech/dapta-forms/blob/develop/SELF-HOSTING.md)                 | The production guide: building the images, the full environment reference, the database, reverse proxy and TLS, sign in, email, upgrades, rollback and troubleshooting. |
| [`.env.example`](https://github.com/Dapta-Tech/dapta-forms/blob/develop/.env.example)                       | Every setting with inline notes and its default.                                                                                                                        |
| [`docker-compose.prod.yml`](https://github.com/Dapta-Tech/dapta-forms/blob/develop/docker-compose.prod.yml) | A production shaped reference stack you can bring up in one command.                                                                                                    |

<figure><img src="https://3835013762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCy5rSNtQmtqYCGzJlNEB%2Fuploads%2Fgit-blob-390e5a20d3049425191d2921c95edce4f1e58cd6%2Fforms-self-hosting-01-guide.png?alt=media" alt="The SELF-HOSTING.md production guide rendered on GitHub inside the dapta-forms repository"><figcaption><p><code>SELF-HOSTING.md</code> in the repository is the production guide. Start there.</p></figcaption></figure>

***

## The two apps

A dForms deployment is two containers plus a database.

* **Web** (`apps/web`): the public form pages and the dashboard. Listens on port `3000`.
* **API** (`apps/api`): the public submission endpoints and the dashboard endpoints. Listens on port `4000`, and exposes `/health` and `/health/ready` for your load balancer.

The web app never talks to the database directly, it calls the API over HTTP. That is why the two can be scaled and deployed independently.

Both Dockerfiles take the repository root as the build context:

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

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

***

## The database

PostgreSQL is the production database. The repository also supports a SQLite file so you can clone the project and have it running in a minute, but that path is for evaluation and local development only.

* Point `DATABASE_URL` at your PostgreSQL instance.
* **Run the migrations before the API starts.** The API image does not migrate on boot on purpose, so scaling to several replicas never has several of them migrating at once. The reference stack does it with a one-shot `migrate` service that runs and exits.
* Migrations add things (new tables, new nullable columns), so an upgrade never drops data from a running deployment. A few also update stored data in place: for example, one added the `{{answers}}` variable to custom new submission notices that did not have it.

***

## The settings that matter

Everything has a safe default, so a bare deployment boots. These are the ones you will actually set for a real deployment. The full list is in `SELF-HOSTING.md` and `.env.example`.

| Setting                                                                                | Why you set it                                                                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NODE_ENV`                                                                             | `production` for any real deployment.                                                                                                                                                                                                                                                                                                   |
| `DATABASE_URL`                                                                         | Your PostgreSQL connection string.                                                                                                                                                                                                                                                                                                      |
| `PUBLIC_APP_URL`                                                                       | Your public base URL, for example `https://forms.example.com`. It is the trusted origin used to build sign in redirects and the default list of allowed browser origins. It is also the base of the submissions link in new submission notices (left out when this is not set), and the host spam protection checks each token against. |
| `NEXT_PUBLIC_API_URL`                                                                  | Where the browser reaches your API. Build time value, so it is baked into the web image.                                                                                                                                                                                                                                                |
| `AUTH_PROVIDER`                                                                        | Which sign in adapter the dashboard uses. The default is an unauthenticated development stub, and the API refuses to boot with it in production. See **Auth options** in `SELF-HOSTING.md` for the production value and the secrets it needs.                                                                                           |
| `EMAIL_PROVIDER`                                                                       | `log-only` by default, which prints submission notices to the API log instead of sending them. Switch to SMTP or an HTTP mail API to actually send, and set `MAIL_FROM_EMAIL` and `MAIL_FROM_NAME`.                                                                                                                                     |
| `CORS_ORIGINS`                                                                         | The extra domains allowed to call your API from a browser. Only needed when your own code calls the API from a page on another domain: embedded forms reach the API through the web app, so they do not need it.                                                                                                                        |
| `TRUST_PROXY_HOPS`                                                                     | How many trusted proxies sit in front of the API. It decides which address the rate limiter counts, so get it right or you will throttle everyone as one client.                                                                                                                                                                        |
| `HUBSPOT_PRIVATE_APP_TOKEN`                                                            | Optional. Set it and HubSpot works for the whole deployment. Leave it unset and the HubSpot destination reports a clear disabled state.                                                                                                                                                                                                 |
| `FORMS_ENCRYPTION_KEY`                                                                 | The key stored connections are encrypted with (`openssl rand -base64 32`). Without it no workspace can connect HubSpot, Calendly, Google Sheets, Salesforce or HighLevel.                                                                                                                                                               |
| `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET` and `GOOGLE_OAUTH_REDIRECT_URI` | Optional, all three together: your own Google OAuth client, for the Google Sheets destination. `GOOGLE_PICKER_API_KEY` adds picking an existing spreadsheet. See [Integrations and scheduling](https://docs.dapta.ai/dforms/developers/environment-flags.md#integrations-and-scheduling).                                               |
| `DCAL_API_BASE_URL` and `DCAL_APP_URL`                                                 | Optional, as a pair. Set both to offer dCal as a scheduler.                                                                                                                                                                                                                                                                             |
| `CAPTCHA_SITE_KEY` and `CAPTCHA_SECRET_KEY`                                            | Optional, and always as a pair. Set both to make [spam protection](https://docs.dapta.ai/dforms/connect/spam-protection.md) available to your forms. See [Feature flags & environment](https://docs.dapta.ai/dforms/developers/environment-flags.md#spam-protection).                                                                   |

Server settings are validated when the API starts, and a bad value fails loudly with a message naming the offending variable.

***

## Sign in, TLS and email

* Put a reverse proxy in front of both apps and terminate TLS there. Any proxy works: nginx, Caddy, Traefik, a cloud load balancer. Forward to web on `3000` and API on `4000`.
* Public form pages are always open. Sign in only protects the dashboard, and it is a pluggable adapter: the default local stub is fine for evaluation, and a real deployment points it at your own identity service. `SELF-HOSTING.md` has the exact values and secrets.
* If your proxy adds a Content-Security-Policy, allow the hosts your forms embed in `frame-src`: the host of `DCAL_APP_URL` when you offer dCal, and `https://challenges.cloudflare.com` (also in `script-src`) when you offer spam protection.
* Email delivery is also pluggable. Submission notifications are queued and retried with backoff, so a slow or unreachable mail provider never fails a respondent's submission.

***

## The MCP endpoint

Your API serves the [MCP connector](https://docs.dapta.ai/dforms/developers/mcp-connector.md) at `<your API origin>/mcp`, on by default (`MCP_ENABLED=false` turns it off). Out of the box it takes API keys only. To let people connect Claude, ChatGPT and other apps by signing in, set `MCP_OAUTH_PROVIDER=workos`, `WORKOS_AUTHKIT_DOMAIN` and `MCP_PUBLIC_URL` on the API, and the same `MCP_OAUTH_PROVIDER` and `MCP_PUBLIC_URL` on the web app. Until then, **Connect your agent** says the connector is not available on this deployment. Rate limits, allowed hosts and origins, and the rest are in [`docs/MCP.md`](https://github.com/Dapta-Tech/dapta-forms/blob/develop/docs/MCP.md) in the repository.

***

## What is different from app.dforms.ai

| On app.dforms.ai                                                                                                                              | On your own deployment                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You sign in with your Dapta account.                                                                                                          | You wire your own sign in, or run the open development stub for evaluation.                                                                                                                                                                                                                                       |
| Workspaces, members, roles and invitations come from your Dapta account.                                                                      | There are no Dapta workspaces. Membership comes from whatever identity service you connect.                                                                                                                                                                                                                       |
| HubSpot, Calendly, Google Sheets, Salesforce and HighLevel are connected per account from **Integrations**, and dCal is ready as a scheduler. | Same screen, but you supply the tokens, and you can also set one HubSpot token for the whole deployment. Google Sheets needs your own Google OAuth client and dCal its two URLs; until then their cards say they are not available on this deployment. Salesforce and HighLevel need only `FORMS_ENCRYPTION_KEY`. |
| Submission emails are sent for you.                                                                                                           | Nothing is sent until you configure a mail provider. Until then, notices are written to the API log.                                                                                                                                                                                                              |
| Spam protection is ready to turn on in every form.                                                                                            | It needs your own Cloudflare Turnstile keys. Without them, the switch in the **Connect** tab is disabled.                                                                                                                                                                                                         |
| Dapta runs backups, upgrades and uptime.                                                                                                      | You do: database backups, migrations, image upgrades and rollbacks are yours.                                                                                                                                                                                                                                     |
| Support and bug reports go through Dapta.                                                                                                     | Support is the repository: issues and pull requests on GitHub.                                                                                                                                                                                                                                                    |

Everything else, the editor, logic, scoring, design, webhooks, submissions and analytics, is the same product.

***

## What's next

* [Public API & rate limits](https://docs.dapta.ai/dforms/developers/public-api.md): the endpoints your deployment exposes.
* [Feature flags & environment](https://docs.dapta.ai/dforms/developers/environment-flags.md): the settings that change what your users see.
* [Integrations (account level)](https://docs.dapta.ai/dforms/connect/connections.md): the screen where integrations are connected.
* [MCP tools reference](https://docs.dapta.ai/dforms/developers/mcp-tools.md): what an agent can do on your deployment.


---

# 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/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.
