← Back to home

Setting Up Cloudflare for Multi-Tenant Subdomain Support

This guide will help you configure Cloudflare to enable wildcard subdomain support for your Referral OS deployment, which is essential for proper multi-tenant functionality.

Why Cloudflare for Multi-Tenancy?

Referral OS uses subdomain-based multi-tenancy (e.g., tenant1.yourdomain.com, tenant2.yourdomain.com). Cloudflare provides:

  1. Wildcard DNS support for *.yourdomain.com
  2. SSL/TLS for all subdomains automatically
  3. Performance benefits through Cloudflare's CDN
  4. Additional security features

Step 1: Sign Up for Cloudflare

If you don't have a Cloudflare account:

  1. Go to cloudflare.com and sign up
  2. Add your domain to Cloudflare
  3. Follow Cloudflare's instructions to change your domain nameservers

Step 2: Configure DNS Settings

  1. In your Cloudflare dashboard, go to the DNS section for your domain

  2. Add the following DNS records:

    A Record for Root Domain:

    Type: A
Name: @
Content: YOUR_SERVER_IP_ADDRESS
Proxy status: Proxied

    CNAME for Wildcard Subdomains:

    Type: CNAME
Name: *
Content: yourdomain.com
Proxy status: Proxied

  3. Wait for DNS changes to propagate (can take up to 24 hours, but often much faster)

Step 3: Configure SSL/TLS

  1. Go to the SSL/TLS section in your Cloudflare dashboard
  2. Set the encryption mode to "Full" or "Full (strict)" if you have SSL on your origin server
  3. Enable "Always Use HTTPS" under the Edge Certificates tab

Step 4: Configure Cloudflare Headers

Referral OS can detect the original subdomain even when behind Cloudflare's proxy by using special headers. No additional configuration is needed as our middleware automatically handles these headers.

Step 5: Test Your Setup

  1. Create a test tenant (e.g., "test") in your Referral OS super admin dashboard
  2. Try accessing it via the subdomain: test.yourdomain.com
  3. You should be directed to that specific tenant's environment

Custom Domain Setup for Tenant Administrators

Instructions to Provide to Your Tenants

When tenants want to use their own custom domain (e.g., partners.theircompany.com) instead of your subdomain, provide them with these instructions:

  1. Add their domain to Cloudflare (recommended but optional):

    • This provides added security and performance benefits
    • They should follow Step 1 above for their own domain

  2. Create a CNAME record in their DNS settings:

    Type: CNAME
Name: partners (or whatever subdomain they prefer)
Content: tenant-subdomain.yourdomain.com (their specific tenant subdomain)
TTL: Auto

  3. Configure their DNS settings with their domain registrar or DNS provider:

    • If using Cloudflare, ensure the record is "Proxied"
    • If not using Cloudflare, just set up the CNAME as above

  4. Enter their custom domain in the Settings → Branding & Domain section in their admin dashboard

  5. Wait for DNS propagation (up to 24-48 hours)

Example for Tenant Administrators

Here's a concrete example you can provide to tenants:

If your tenant's subdomain on Referral OS is acme.referral-os.ai and they want to use partners.acmecorp.com:

  1. Create this CNAME record in their DNS settings:

    CNAME partners.acmecorp.com → acme.referral-os.ai

  2. In their Referral OS admin dashboard, go to Settings → Branding & Domain

  3. Enter partners.acmecorp.com in the Custom Domain field

  4. Click Save Domain Settings

  5. Wait for DNS changes to propagate

The system will automatically detect and route visitors to their tenant environment whether they use the original subdomain (acme.referral-os.ai) or their custom domain (partners.acmecorp.com).

Additional Configuration Options

Page Rules (Optional)

You can set up page rules to customize behavior for specific URL patterns:

  1. Go to the Page Rules section in your Cloudflare dashboard
  2. Create rules as needed for caching, redirects, etc.

Example rule to always cache the marketing pages:

URL pattern: yourdomain.com/blog*
Setting: Cache Level: Standard

Workers (Advanced)

For more advanced routing logic, you can use Cloudflare Workers:

  1. Go to the Workers section in your Cloudflare dashboard
  2. Create a new worker with custom logic for specific routing needs

Troubleshooting

Subdomain Not Working

If a subdomain isn't properly redirecting to the correct tenant:

  1. Verify the DNS record for wildcard subdomains is set up correctly
  2. Check that the tenant exists in your Referral OS database
  3. Look for errors in your application logs

Custom Domain Not Working

If a tenant's custom domain isn't working properly:

  1. Verify the CNAME record is set correctly in their DNS settings
  2. Check that the custom domain matches exactly what's entered in their settings
  3. Confirm SSL/TLS is properly configured if using HTTPS
  4. Try clearing browser cache or using an incognito window

SSL Issues

If you're having SSL certificate errors:

  1. Ensure SSL/TLS is set to "Full" or "Full (strict)" in Cloudflare
  2. Wait for SSL certificate provisioning (can take up to 24 hours)
  3. Verify your origin server is properly configured for SSL if using "Full (strict)"

Security Recommendations

  1. Enable Cloudflare security features like WAF (Web Application Firewall)
  2. Set appropriate security level under "Security" in the Cloudflare dashboard
  3. Consider enabling "Bot Fight Mode" to prevent automated attacks

Getting Help

If you encounter issues with your Cloudflare configuration: