Subdomain & Root Redirect

OpnForm supports redirecting users from root domains to specific URLs, useful for directing traffic from your main domain to your forms or application.

Client Configuration

NUXT_PUBLIC_ROOT_REDIRECT_URL

string

URL to redirect to when accessing the root domain (e.g., redirecting yourdomain.com to app.yourdomain.com or an external site).

Use Cases

Redirect to Subdomain

Redirect your root domain to a subdomain:

# client/.env
NUXT_PUBLIC_ROOT_REDIRECT_URL=https://app.yourdomain.com

When users visit https://yourdomain.com, they’ll be redirected to https://app.yourdomain.com.

Redirect to Marketing Site

Redirect your OpnForm instance root to your marketing website:

NUXT_PUBLIC_ROOT_REDIRECT_URL=https://www.yourcompany.com

Redirect to Specific Form

Redirect to a default form:

NUXT_PUBLIC_ROOT_REDIRECT_URL=https://yourdomain.com/forms/contact-us

Implementation Details

The redirect is implemented in the Nuxt client application and occurs client-side. The redirection happens when:

User visits the root path (/)
NUXT_PUBLIC_ROOT_REDIRECT_URL is set
User is not already on a specific route

This ensures users can still access other routes like /forms/:id, /login, etc.

Nginx Configuration Example

For server-side redirects (more efficient), configure your Nginx reverse proxy:

Redirect Root to Subdomain

server {
    listen 443 ssl http2;
    server_name yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    # Redirect root to subdomain
    location = / {
        return 301 https://app.yourdomain.com;
    }
    
    # Proxy all other requests
    location / {
        proxy_pass http://opnform-client:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Redirect Entire Domain

server {
    listen 443 ssl http2;
    server_name yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    # Redirect all traffic
    return 301 https://app.yourdomain.com$request_uri;
}

Preserve Query Parameters

server {
    listen 443 ssl http2;
    server_name yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location = / {
        return 301 https://app.yourdomain.com$is_args$args;
    }
}

Caddy Configuration Example

If using Caddy for custom domains:

Redirect Root Domain

yourdomain.com {
    redir https://app.yourdomain.com{uri} permanent
}

Redirect Only Root Path

yourdomain.com {
    # Redirect root only
    redir / https://app.yourdomain.com permanent
    
    # Proxy everything else
    reverse_proxy opnform-client:3000
}

Subdomain Strategy

Common subdomain patterns for OpnForm deployments:

app.

Main application interfaceapp.yourdomain.com

forms.

Public form accessforms.yourdomain.com

api.

Backend API endpointapi.yourdomain.com

www.

Marketing websitewww.yourdomain.com

Multi-Tenant Configuration

For white-label deployments with multiple workspaces:

# Root domain redirects to main marketing site
server {
    server_name yourdomain.com;
    return 301 https://www.yourcompany.com;
}

# App subdomain hosts OpnForm
server {
    server_name app.yourdomain.com;
    location / {
        proxy_pass http://opnform-client:3000;
    }
}

# Custom workspace domains
server {
    server_name ~^(?<workspace>.+)\.forms\.yourdomain\.com$;
    location / {
        proxy_pass http://opnform-client:3000;
        proxy_set_header X-Workspace $workspace;
    }
}

DNS Configuration

Set up DNS records for your subdomain strategy:

Example DNS Records

Type    Name    Value                   TTL
A       @       192.168.1.100          300
CNAME   app     yourdomain.com.        300
CNAME   forms   yourdomain.com.        300
CNAME   api     yourdomain.com.        300
CNAME   www     external-site.com.     300

Using External Services

Type    Name    Value                           TTL
CNAME   app     opnform-app.herokuapp.com.     300
CNAME   api     opnform-api.herokuapp.com.     300

HTTPS Considerations

When redirecting between domains, ensure both domains have valid SSL certificates to avoid security warnings.

Wildcard Certificates

For multiple subdomains, use a wildcard SSL certificate:

*.yourdomain.com

This covers:

app.yourdomain.com
forms.yourdomain.com
api.yourdomain.com
Any other subdomain

Let’s Encrypt Wildcard

certbot certonly --manual --preferred-challenges=dns \
  -d yourdomain.com -d "*.yourdomain.com"

SEO Considerations

Use 301 (permanent) redirects for SEO purposes. This signals to search engines that the content has permanently moved.

Canonical URLs

If your forms are accessible via multiple domains, use canonical URLs:

<link rel="canonical" href="https://forms.yourdomain.com/contact" />

Testing Redirects

Command Line Testing

# Test redirect
curl -I https://yourdomain.com

# Follow redirects
curl -L https://yourdomain.com

# View redirect chain
curl -sI https://yourdomain.com | grep -i location

Expected Output

HTTP/2 301
location: https://app.yourdomain.com

Troubleshooting

Redirect Loop

Check that:

Source and destination URLs are different
You’re not redirecting app.domain.com back to domain.com
Nginx/Caddy configuration doesn’t have circular redirects
Browser cache is cleared

Redirect Not Working

Verify NUXT_PUBLIC_ROOT_REDIRECT_URL is set correctly
Check Nginx/Caddy configuration is loaded (nginx -t, caddy validate)
Reload web server after config changes
Clear browser cache and DNS cache
Test in incognito mode

SSL Certificate Errors

Ensure both source and destination domains have valid certificates
For subdomains, use wildcard certificate or individual certs
Verify certificate covers all SANs (Subject Alternative Names)
Check certificate expiration date

Query Parameters Lost

Use $is_args$args in Nginx or {uri} in Caddy to preserve:

return 301 https://app.yourdomain.com$request_uri;

Best Practices

Use 301 redirects for permanent moves
Use 302 for temporary redirects
Preserve query parameters and paths when relevant
Use HTTPS for all redirects
Test redirect chains don’t exceed 3 hops
Configure redirects at the web server level for better performance
Monitor redirect response times

Custom Domains

Configure workspace custom domains

Environment Variables

All configuration options

Get Started

Core Features

Deployment

Configuration

Integrations

​Client Configuration

​Use Cases

​Redirect to Subdomain

​Redirect to Marketing Site

​Redirect to Specific Form

​Implementation Details

​Nginx Configuration Example

​Redirect Root to Subdomain

​Redirect Entire Domain

​Preserve Query Parameters

​Caddy Configuration Example

​Redirect Root Domain

​Redirect Only Root Path

​Subdomain Strategy

app.

forms.

api.

www.

​Multi-Tenant Configuration

​DNS Configuration

​Example DNS Records

​Using External Services

​HTTPS Considerations

​Wildcard Certificates

​Let’s Encrypt Wildcard

​SEO Considerations

​Canonical URLs

​Testing Redirects

​Command Line Testing

​Expected Output

​Troubleshooting

​Best Practices

​Related Documentation

Custom Domains

Environment Variables

Build docs developers (and LLMs) love

Client Configuration

Use Cases

Redirect to Subdomain

Redirect to Marketing Site

Redirect to Specific Form

Implementation Details

Nginx Configuration Example

Redirect Root to Subdomain

Redirect Entire Domain

Preserve Query Parameters

Caddy Configuration Example

Redirect Root Domain

Redirect Only Root Path

Subdomain Strategy

Multi-Tenant Configuration

DNS Configuration

Example DNS Records

Using External Services

HTTPS Considerations

Wildcard Certificates

Let’s Encrypt Wildcard

SEO Considerations

Canonical URLs

Testing Redirects

Command Line Testing

Expected Output

Troubleshooting

Best Practices

Related Documentation