Skip to main content

DNS & Domain Configuration

After installing the module, you need to decide how your tenants will access their CRM. This is one of the most important decisions for your SaaS platform, so let's explain all the options clearly.

Understanding URL Structuresโ€‹

The module supports three different ways for tenants to access their CRM. Here's what each one looks like:

Option 1: Subdirectory Mode (Easiest Setup)โ€‹

https://yoursite.com/ws/tenant-name

Example: If your domain is mycrm.com and a tenant named "Acme Corp" signs up, they'll access their CRM at:

https://mycrm.com/ws/acme-corp

Pros:

  • No additional DNS configuration needed
  • Works on any hosting plan
  • No wildcard SSL required
  • Simplest setup

Cons:

  • Less "professional" looking than a subdomain
  • Tenants can't use custom domains

Best for: Getting started quickly, testing, small deployments.

Option 2: Subdomain Modeโ€‹

https://tenant-name.yoursite.com

Example: Acme Corp would access their CRM at:

https://acme-corp.mycrm.com

Pros:

  • Professional and branded appearance
  • Each tenant feels like they have their own platform
  • Industry standard for SaaS platforms

Cons:

  • Requires wildcard DNS record
  • May require wildcard SSL (but we have workarounds!)

Best for: Professional SaaS deployments, businesses that want to impress clients.

Option 3: Custom Domain Modeโ€‹

https://crm.tenant-own-domain.com

Example: Acme Corp could use their own domain:

https://crm.acmecorp.com

Pros:

  • Maximum branding for your tenants
  • Tenants can use their own company domain
  • Highest perceived value

Cons:

  • Each tenant needs to configure their DNS
  • Requires more setup per tenant

Best for: Enterprise offerings, premium plans, white-label services.

Setting Up Subdirectory Modeโ€‹

This is the default mode and requires almost no DNS setup.

Step 1: Enable Subdirectory Structureโ€‹

  1. Go to SaaS Management โ†’ SuperAdmin Settings
  2. Click the MySQL Server Settings tab
  3. Set "Use Subdir Structure '/ws/{tenant}'" to Yes
  4. Click Save Settings

Step 2: That's It!โ€‹

Seriously โ€” if you're using subdirectory mode, there's no DNS configuration needed. Tenants will automatically be accessible at yoursite.com/ws/tenant-slug.

Setting Up Subdomain Modeโ€‹

Subdomain mode requires a wildcard DNS record. Here's exactly how to set it up:

What Is a Wildcard DNS Record?โ€‹

A wildcard DNS record is a special DNS entry that catches ALL subdomains and points them to your server. Instead of creating a DNS record for each tenant individually (which would be impossible), one wildcard record handles them all.

Think of it like a mail redirect: "Any mail addressed to anything@yourcompany.com should go to the main office."

Step 1: Find Your Server's IP Addressโ€‹

You need your server's IP address. Here's how to find it:

  • cPanel: Look at the top of your cPanel dashboard โ€” it shows your IP
  • VPS/Cloud: Check your hosting provider's dashboard
  • Command line: Run curl ifconfig.me on your server

Step 2: Add the Wildcard DNS Recordโ€‹

  1. Log in to your domain registrar (where you bought your domain โ€” e.g., Namecheap, GoDaddy, Cloudflare)
  2. Go to the DNS settings for your domain
  3. Add a new A Record with these settings:
FieldValue
TypeA
Host/Name* (just an asterisk)
Value/Points toYour server's IP address (e.g., 123.456.789.0)
TTLAutomatic (or 3600)
warning

The asterisk (*) is important! It must be exactly * โ€” not *.yoursite.com or anything else. Just the single asterisk character.

Step 3: Wait for DNS Propagationโ€‹

DNS changes don't take effect instantly. They need to "propagate" across the internet:

  • Cloudflare: Usually instant (within 5 minutes)
  • Most registrars: 15 minutes to 4 hours
  • Some registrars: Up to 24-48 hours (rare)

You can check if your DNS has propagated using dnschecker.org.

Step 4: Disable Subdirectory Modeโ€‹

  1. Go to SaaS Management โ†’ SuperAdmin Settings
  2. Click the MySQL Server Settings tab
  3. Set "Use Subdir Structure '/ws/{tenant}'" to No
  4. Click Save Settings

Now tenants will be accessible at tenant-name.yoursite.com instead of yoursite.com/ws/tenant-name.

Setting Up Custom Domainsโ€‹

Custom domains allow tenants to use their own domain (like crm.theircompany.com) to access their CRM. This is a premium feature that your tenants will love!

How Custom Domains Workโ€‹

  1. You enable the Custom Domain feature in the tenant's plan
  2. The tenant enters their desired domain in their dashboard
  3. The tenant (or you) points their domain's DNS to your server's IP
  4. The module automatically detects the domain and routes traffic to the correct tenant

Enabling Custom Domainsโ€‹

  1. Go to SaaS Management โ†’ Plans
  2. Edit the plan where you want to enable custom domains
  3. In Advanced Features, toggle "Enable Custom Domain" to ON
  4. Save the plan

Toggle "Enable Custom Domain" in the Advanced Feature section of your plan

What Your Tenants Need to Doโ€‹

When a tenant wants to use a custom domain, they need to add DNS records pointing to your server. The module includes a built-in DNS guide that tenants can access with one click:

The built-in DNS guide tells your tenants exactly what DNS records to add โ€” no support tickets needed!

The guide tells them to:

  1. Add an A Record with their domain pointing to your server's IP
  2. Optionally add a www version
  3. Wait for DNS propagation (up to 48 hours)

DNS Configuration Cheat Sheetโ€‹

Here's a quick reference for all the DNS records you might need:

PurposeTypeHost/NameValue
Main domainA@Your server IP
www versionAwwwYour server IP
Wildcard subdomainsA*Your server IP
Tenant custom domainA (on tenant's DNS)@Your server IP

Testing Your DNS Configurationโ€‹

After making DNS changes, test them:

  1. Open a browser and navigate to a test subdomain: http://test123.yourdomain.com
  2. If you see your Perfex CRM (or a landing page) โ€” DNS is working!
  3. If you see an error โ€” DNS hasn't propagated yet. Wait and try again.

You can also use these online tools to check:

success

DNS configured? Great! Now set up SSL for secure connections. Head to the SSL Configuration guide next.