From 6756bbf10f64423e87ff3bd0c290dc6d8550b5b0 Mon Sep 17 00:00:00 2001 From: JhumanJ Date: Fri, 23 May 2025 16:02:26 +0200 Subject: [PATCH] Update Documentation and Configuration for Subdomain Redirect - Added a link to the new "Subdomain Redirect Configuration" page in `environment-variables.mdx` to enhance user guidance on setting up subdomain redirects. - Updated the `mint.json` file to include "configuration/subdomain-redirect" in the configuration paths, ensuring it is recognized in the documentation structure. These changes aim to improve the documentation's comprehensiveness and provide users with clear instructions for configuring subdomain redirects, thereby enhancing the overall setup experience. --- docs/configuration/environment-variables.mdx | 45 ++++---- docs/configuration/subdomain-redirect.mdx | 102 +++++++++++++++++++ docs/mint.json | 3 +- 3 files changed, 127 insertions(+), 23 deletions(-) create mode 100644 docs/configuration/subdomain-redirect.mdx diff --git a/docs/configuration/environment-variables.mdx b/docs/configuration/environment-variables.mdx index 4e3c43ca..13526ad7 100644 --- a/docs/configuration/environment-variables.mdx +++ b/docs/configuration/environment-variables.mdx @@ -16,6 +16,7 @@ There are dedicated configuration pages available for more detailed setup instru - [File Storage (S3)](../configuration/aws-s3) - [Email Configuration (SMTP)](../configuration/email-setup) - [Custom Domain](../configuration/custom-domain) +- [Subdomain Redirect Configuration](../configuration/subdomain-redirect) ### Configuration Environment Variables @@ -53,12 +54,12 @@ There are dedicated configuration pages available for more detailed setup instru ### PHP Configuration Environment Variables -| Variable Name | Description | -| --------------------------- | -------------------------------------------------------------------------------------------------------- | -| `PHP_MEMORY_LIMIT` | Maximum amount of memory a script may consume. | -| `PHP_MAX_EXECUTION_TIME` | Maximum time in seconds a script is allowed to run. | -| `PHP_UPLOAD_MAX_FILESIZE` | Maximum size of an uploaded file. | -| `PHP_POST_MAX_SIZE` | Maximum size of POST data that PHP will accept. | +| Variable Name | Description | +| ------------------------- | --------------------------------------------------- | +| `PHP_MEMORY_LIMIT` | Maximum amount of memory a script may consume. | +| `PHP_MAX_EXECUTION_TIME` | Maximum time in seconds a script is allowed to run. | +| `PHP_UPLOAD_MAX_FILESIZE` | Maximum size of an uploaded file. | +| `PHP_POST_MAX_SIZE` | Maximum size of POST data that PHP will accept. | These PHP configuration variables are particularly important when handling file uploads and processing large amounts of data. If any of these variables are not set, PHP will use its default values from the php.ini configuration. When using Docker, these values are set in the docker-compose.yml file. For non-Docker installations, you'll need to configure these values in your PHP configuration (php.ini) file. @@ -66,25 +67,25 @@ These PHP configuration variables are particularly important when handling file These variables are essential for connecting the Laravel backend to your database. -| Variable Name | Description | -| ----------------- | ------------------------------------------------ | -| `DB_CONNECTION` | The database driver (e.g., `mysql`, `pgsql`). | -| `DB_HOST` | The database server host (e.g., `127.0.0.1`). | -| `DB_PORT` | The database server port (e.g., `3306`). | -| `DB_DATABASE` | The name of the database. | -| `DB_USERNAME` | The username for connecting to the database. | -| `DB_PASSWORD` | The password for the database user. | +| Variable Name | Description | +| --------------- | --------------------------------------------- | +| `DB_CONNECTION` | The database driver (e.g., `mysql`, `pgsql`). | +| `DB_HOST` | The database server host (e.g., `127.0.0.1`). | +| `DB_PORT` | The database server port (e.g., `3306`). | +| `DB_DATABASE` | The name of the database. | +| `DB_USERNAME` | The username for connecting to the database. | +| `DB_PASSWORD` | The password for the database user. | ## Front-end Environment Variables -| Variable Name | Description | -| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `NUXT_PUBLIC_APP_URL` | Public facing URL of the Nuxt application. | -| `NUXT_PUBLIC_API_BASE` | Base URL for the Laravel API. | -| `NUXT_PUBLIC_H_CAPTCHA_SITE_KEY` | Site key for hCaptcha integration on the front-end. | -| `NUXT_PUBLIC_RE_CAPTCHA_SITE_KEY` | Site key for reCAPTCHA integration on the front-end. | -| `NUXT_API_SECRET` | Shared secret key between Nuxt and Laravel backend. | -| `NUXT_PUBLIC_ROOT_REDIRECT_URL` | If set, permanently redirects users visiting the root path (/), /integrations, or any non-existent (404) page to the specified URL. Useful for self-hosted subdomains to avoid exposing the default landing page. | +| Variable Name | Description | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `NUXT_PUBLIC_APP_URL` | Public facing URL of the Nuxt application. | +| `NUXT_PUBLIC_API_BASE` | Base URL for the Laravel API. | +| `NUXT_PUBLIC_H_CAPTCHA_SITE_KEY` | Site key for hCaptcha integration on the front-end. | +| `NUXT_PUBLIC_RE_CAPTCHA_SITE_KEY` | Site key for reCAPTCHA integration on the front-end. | +| `NUXT_API_SECRET` | Shared secret key between Nuxt and Laravel backend. | +| `NUXT_PUBLIC_ROOT_REDIRECT_URL` | Permanently redirects users visiting the root path (/), /integrations, or any non-existent (404) page to the specified URL. This effectively "hides" OpnForm's public pages while keeping forms and admin functionality accessible. See [Subdomain Redirect Configuration](../configuration/subdomain-redirect) for detailed setup and examples. | import CloudVersion from "/snippets/cloud-version.mdx"; diff --git a/docs/configuration/subdomain-redirect.mdx b/docs/configuration/subdomain-redirect.mdx new file mode 100644 index 00000000..c15b8213 --- /dev/null +++ b/docs/configuration/subdomain-redirect.mdx @@ -0,0 +1,102 @@ +--- +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 will permanently redirect (301) users visiting these routes: + +- **Root path** (`/`) - The landing page +- **Integrations page** (`/integrations`) - The integrations showcase +- **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 + +- The redirect is a **permanent redirect** (HTTP 301) +- The redirect happens on the client-side (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 +``` + + + A simple `docker compose restart` will not reload the new environment + variable. You must use `down` and `up` to recreate the container. +{" "} diff --git a/docs/mint.json b/docs/mint.json index 028996f5..d34614ca 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -84,7 +84,8 @@ "configuration/environment-variables", "configuration/aws-s3", "configuration/email-setup", - "configuration/custom-domain" + "configuration/custom-domain", + "configuration/subdomain-redirect" ] }, {