Skip to content

Beautiful Open-Source Form Builder

5.8 KB
Raw Blame
---
title: Subdomain Redirect
description: Hide OpnForm's public pages by redirecting users to your main website
---

The `NUXT_PUBLIC_ROOT_REDIRECT_URL` environment variable allows you to "hide" OpnForm's public pages (landing page, integrations page, etc.) by redirecting users to your main website or any other destination when they access certain routes.

## Use Case

This feature is particularly useful when you're running OpnForm on a subdomain (e.g., `forms.yourdomain.com`) and want to:

-   Hide the default OpnForm landing page and branding
-   Prevent users from discovering your form creation interface
-   Redirect visitors to your main website instead
-   Keep only the essential form and admin functionality accessible

## How It Works

When `NUXT_PUBLIC_ROOT_REDIRECT_URL` is set, OpnForm redirects users visiting these routes:

-   **Root path** (`/`) - The landing page
-   **Marketing pages** — Integrations, pricing, Enterprise, industry, comparisons, and cloud product pages (HTTP 302)
-   **Any non-existent pages** (404 errors) - Undefined routes

### What Still Works

The following routes remain fully accessible and will **NOT** be redirected:

-   **Form URLs**: `forms.yourdomain.com/forms/my-form` ✅
-   **Admin login**: `forms.yourdomain.com/login` ✅
-   **Admin dashboard**: `forms.yourdomain.com/home` ✅
-   **All admin pages**: Settings, workspaces, templates, etc. ✅

## Configuration

### Environment Variable Setup

Add this to your **client** `.env` file (located in the `client` directory):

```bash
NUXT_PUBLIC_ROOT_REDIRECT_URL=https://yourdomain.com
```

### Example Scenarios

**Scenario 1: Redirect to main website**

```bash
NUXT_PUBLIC_ROOT_REDIRECT_URL=https://mycompany.com
```

-   Visiting `forms.mycompany.com` → redirects to `https://mycompany.com`
-   Visiting `forms.mycompany.com/forms/contact` → works normally ✅

**Scenario 2: Redirect to specific landing page**

```bash
NUXT_PUBLIC_ROOT_REDIRECT_URL=https://mycompany.com/contact
```

-   Visiting `forms.mycompany.com` → redirects to `https://mycompany.com/contact`

**Scenario 3: Redirect to documentation**

```bash
NUXT_PUBLIC_ROOT_REDIRECT_URL=https://docs.mycompany.com
```

## User Experience

### For Form Respondents

-   Can access shared forms normally via direct links
-   If they accidentally visit the root domain, they're redirected to your main site
-   No exposure to OpnForm branding or interface

### For Administrators

-   Can still access the admin panel via `/login`
-   All admin functionality remains fully accessible
-   Forms can be managed and created as usual

## Implementation Notes

-   Root and unknown-page redirects use **HTTP 301**; marketing-page redirects use **HTTP 302**
-   The redirect happens during server rendering and client-side navigation (Nuxt)
-   You must recreate your Docker containers after changing this environment variable
-   The URL should include the protocol (`https://` or `http://`)

## Updating the Configuration

If you're using Docker, remember to recreate your containers after changing this environment variable:

```bash
docker compose down ui
docker compose up -d ui
```

<Warning>
    A simple `docker compose restart` will not reload the new environment
    variable. You must use `down` and `up` to recreate the container.
</Warning>{" "}

## Default self-hosted welcome page

Without `NUXT_PUBLIC_ROOT_REDIRECT_URL`, self-hosted instances show a dedicated
split-screen welcome page with a sign-in button, a local template catalog link,
and a link to discover OpnForm. Signed-in users visiting `/` go to their dashboard.
The welcome page asks search engines not to index it.

Marketing routes (pricing, Enterprise, industry, integrations, comparisons,
AI form builder, MCP overview, and cloud license checkout pages) redirect to the
matching page on `https://opnform.com` with a temporary HTTP 302 redirect.
These links include campaign attribution, but never copy the original query
parameters. If you configure `NUXT_PUBLIC_ROOT_REDIRECT_URL`, these marketing
routes use your configured destination instead. The root and unknown-page
redirects keep their existing HTTP 301 behavior.

Templates, public forms, login, password recovery, invitations, application
pages, OAuth callbacks, and MCP authorization remain on your instance.

### Customize the instance

Set these optional variables in the client environment:

| Variable | Purpose |
| --- | --- |
| `NUXT_PUBLIC_SELF_HOSTED_NAME` | Organization or instance name; defaults to `OpnForm` |
| `NUXT_PUBLIC_SELF_HOSTED_LOGO_URL` | Absolute HTTP(S) URL for the instance logo |
| `NUXT_PUBLIC_SELF_HOSTED_PRIVACY_POLICY_URL` | Your organization's privacy policy URL |
| `NUXT_PUBLIC_SELF_HOSTED_TERMS_URL` | Your organization's terms URL |

Legal links appear in the self-hosted footer only when configured. Direct visits
to `/privacy-policy` or `/terms-conditions` redirect to your configured URL, or
to the instance welcome page when no URL is set. OpnForm Cloud legal pages are
not shown as your instance's policies. Recreate your client container after
changing these environment variables.

### Preview in a Codex worktree

Run `CODEX_SELF_HOSTED=true CODEX_AUTO_LOGIN=false ./scripts/codex-worktree-up.sh`
to launch the isolated seeded app in self-hosted mode and view the public welcome
page. Sign in with the seeded account to test the dashboard. These options default
to cloud mode with automatic login when omitted.

The welcome illustration uses separate, static responsive image layers. On smaller
screens the instance sign-in appears before the illustration.

Marketing redirects are applied during both server rendering and client-side
navigation. Sitemap filtering also reads the installation mode at runtime, so
published Docker images omit redirected marketing pages without requiring a
custom frontend build. An API base path such as `/api` does not determine whether
your deployment is self-hosted.