Learn how to configure DNS and domains for your SaaS platform. This determines how your tenants will access their CRM instances.
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
Example: Acme Corp would access their CRM at:
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
Example: Acme Corp could use their own domain:
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
Go to SaaS Management → SuperAdmin Settings
Click the MySQL Server Settings tab
Set "Use Subdir Structure '/ws/{tenant}'" to Yes
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
Log in to your domain registrar (where you bought your domain — e.g., Namecheap, GoDaddy, Cloudflare)
Go to the DNS settings for your domain
Add a new A Record with these settings:
Field
Value
Type
A
Host/Name
* (just an asterisk)
Value/Points to
Your server's IP address (e.g., 123.456.789.0)
TTL
Automatic (or 3600)
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
Go to SaaS Management → SuperAdmin Settings
Click the MySQL Server Settings tab
Set "Use Subdir Structure '/ws/{tenant}'" to No
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
You enable the Custom Domain feature in the tenant's plan
The tenant enters their desired domain in their dashboard
The tenant (or you) points their domain's DNS to your server's IP
The module automatically detects the domain and routes traffic to the correct tenant
Enabling Custom Domains
Go to SaaS Management → Plans
Edit the plan where you want to enable custom domains
In Advanced Features, toggle "Enable Custom Domain" to ON
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:
Add an A Record with their domain pointing to your server's IP
Optionally add a www version
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:
Purpose
Type
Host/Name
Value
Main domain
A
@
Your server IP
www version
A
www
Your server IP
Wildcard subdomains
A
*
Your server IP
Tenant custom domain
A (on tenant's DNS)
@
Your server IP
Testing Your DNS Configuration
After making DNS changes, test them:
Open a browser and navigate to a test subdomain: http://test123.yourdomain.com
If you see your Perfex CRM (or a landing page) — DNS is working!
If you see an error — DNS hasn't propagated yet. Wait and try again.
