Skip to content

Beautiful Open-Source Form Builder

2.8 KB
Raw Blame
---
title: Using your own domain 
description: Setting up a custom domain for OpnForm
---

This page explains how to configure a custom domain for your OpnForm instance.

<Info>
    This guide covers the instance-wide domain for your self-hosted OpnForm
    deployment. Workspace or form-level custom domains are configured
    separately inside OpnForm and are not the same as the instance URL.
</Info>

## Custom Domain Setup

To use a custom domain (or subdomain) with OpnForm:

1. Purchase a domain (if needed)
2. Configure DNS records to point to your OpnForm instance
3. Update an existing Docker installation with your public origin:

   ```bash
   ./scripts/docker-setup.sh --public-url https://forms.example.com
   ```

   The command updates the following configuration while preserving existing
   keys and secrets:
   - Set both `APP_URL` and `FRONT_URL` in `api/.env`
   - Set `NUXT_PUBLIC_APP_URL` and `NUXT_PUBLIC_API_BASE` in `client/.env`
4. Secure with SSL certificate

For example, when the public URL is `https://forms.example.com`:

```bash
# api/.env
APP_URL=https://forms.example.com
FRONT_URL=https://forms.example.com

# client/.env
NUXT_PUBLIC_APP_URL=https://forms.example.com
NUXT_PUBLIC_API_BASE=https://forms.example.com/api
```

`FRONT_URL` is used by the backend when it creates frontend callback URLs,
including OIDC callbacks. Keep it aligned with the public frontend URL.

If you change these files manually, recreate the containers; a restart alone
does not load new environment values. See [Updating Environment Variables](./environment-variables#updating-environment-variables).

<Note>
    If an OIDC connection already exists, edit it afterwards, use **Use current
    app URL** to refresh its redirect URI, save it, and update the URI in your
    identity provider. Existing connections retain their previous redirect URI
    until you save a new one.
</Note>

## Workspace custom domains

Adding a new domain in **Workspace Settings → Domains** requires proof that
you control its DNS. A CNAME pointing to OpnForm alone does not establish
ownership.

1. Enter the domain and click **Add**.
2. Copy the displayed **TXT name / host** and **TXT value** into your DNS
   provider. The name starts with `_opnform-verification.`.
3. Keep the CNAME required by your hosting setup. The TXT record is additional.
4. Wait for DNS propagation, then click **Save Domain(s)**. If verification
   fails, the domain list is not saved; check the record and retry.

The verification value belongs to that domain and workspace. A value from
another workspace or domain cannot be reused. You can remove a domain without
a DNS check. Domains already saved before this requirement remain active;
they are not retroactively certified as verified.

import CloudVersion from "/snippets/cloud-version.mdx";

<CloudVersion/>