CloudPanel

✅ Requirements

Before you begin, make sure:

• Your Concord CRM is deployed and running on CloudPanel.

• You have sudo/root access to the server or full access to the CloudPanel dashboard.

• Let’s Encrypt is enabled and ports 80 and 443 are open.

• SaaS module is installed and activated in Concord CRM.

---

🧭 Goal

Allow your CRM to serve multiple tenants using:

1. Wildcard Subdomains

2. Custom Domains per Tenant

3. Auto-SSL for All Domains

---

⚙️ Step-by-Step Configuration

1. Install Concord CRM Correctly

When creating your site in CloudPanel:

• Go to Sites > Create Site

• Choose:

  • PHP (or Laravel)

  • Set domain: yoursaas.com

  • Set Document Root to:

    /home/cloudpanel/htdocs/yoursaas.com/public

• Click Create Site

✅ This sets up the base Laravel app with the proper public path.

---

2. Enable Wildcard Subdomain Support

🛠 A. Configure DNS for Wildcard Subdomains

On your DNS provider’s dashboard, add:

Type: A  
Name/Host: *  
Value: <Your Server’s Public IP>

AND

Type: A  
Name/Host: @  
Value: <Your Server’s Public IP>

This ensures *.yoursaas.com resolves to your CloudPanel server.

---

🔐 B. Add Wildcard Domain in CloudPanel

1. Go to Sites > yoursaas.com > Domains

2. Click Add Domain

3. Enter:

   *.yoursaas.com

4. Set Document Root to:

   /home/cloudpanel/htdocs/yoursaas.com/public

✅ This allows all subdomains like tenant1.yoursaas.com to point to your main Laravel app.

---

🔐 C. Install Let’s Encrypt Wildcard SSL

1. Go to Sites > yoursaas.com > SSL/TLS

2. Select:

   • Let’s Encrypt

   • Check *.yoursaas.com ✅

   • Provide a valid email

3. CloudPanel will verify DNS and install SSL

⚠️ Wildcard SSL uses DNS-01 validation. You may need to manually add TXT records at your registrar during verification.

---

3. Enable Custom Domain Support

When a client wants to use their own domain:

🪪 A. Ask Client to Point DNS

Client should add the following A record:

Type: A  
Host: @  
Value: <Your Server IP>

Optionally:

Type: CNAME  
Host: www  
Value: clientdomain.com

---

🧩 B. Add Client Domain in CloudPanel

Instead of manually adding each client domain one by one, you can configure CloudPanel to support a catch-all domain setup, which routes any custom domain pointing to your server to the same Laravel app. This simplifies onboarding and eliminates the need for manual intervention every time a new client adds their domain.

⚙️ Steps:

1. Modify NGINX Configuration to Support Catch-All

   Go to: Sites > yoursaas.com > Manage > Web Server > Custom Configuration

   Add the following inside your server block to capture all unknown hostnames:

   server {
       listen 80 default_server;
       listen [::]:80 default_server;
       server_name _;
       root /home/cloudpanel/htdocs/yoursaas.com/public;
   
       include /etc/nginx/cloudpanel/vhost/default/*.conf;
   }

   This sets a default fallback server that serves any domain not explicitly configured—great for multi-tenant SaaS apps where clients add their own domains.

2. Ensure Laravel Handles Domain Mapping

   Your Laravel app should extract the domain from the request and map it to the correct tenant (e.g., using middleware like TenantIdentificationMiddleware).

3. Automate SSL Installation

   Since custom domains are now dynamic, you’ll need a tool like acme.sh or Certbot to automatically issue SSL certificates for new domains via a CLI or cron job.

   Example using acme.sh:

   acme.sh --issue -d clientdomain.com -w /home/cloudpanel/htdocs/yoursaas.com/public
   acme.sh --install-cert -d clientdomain.com \
     --key-file       /etc/ssl/private/clientdomain.key \
     --fullchain-file /etc/ssl/certs/clientdomain.crt

   Then reload NGINX:

   systemctl reload nginx

💡 All domains and subdomains share the same Laravel app.

---

🔐 C. Enable SSL for Custom Domain

1. Go to Sites > yoursaas.com > SSL/TLS

2. Click Install Let’s Encrypt

3. Choose:

   • clientdomain.com

   • www.clientdomain.com (optional)

   • Enter a valid email

CloudPanel will automatically generate the certificates.

---

🔁 SSL Renewal & Maintenance

• CloudPanel handles auto-renewals for Let’s Encrypt

• Just ensure:

  • DNS remains pointed correctly

  • No firewall blocks port 80 or 443

You can manually verify:

• From SSL/TLS page in CloudPanel

• Or with tools like SSL Labs

---

🧪 Testing the Setup

Test	Description
https://tenant1.yoursaas.com	Should route to the correct tenant
https://clientdomain.com	Should show the correct client tenant’s CRM
https://yoursaas.com	Should show default/root tenant
dig +short tenant1.yoursaas.com	Should return your server IP
curl -I https://clientdomain.com	Should return 200 OK and valid SSL

---

📌 Troubleshooting

Problem	Solution
Subdomain not resolving	Check wildcard A record at DNS provider
SSL error on custom domain	Ensure domain is added to CloudPanel & points to server
Wildcard SSL fails to install	Ensure TXT records are added properly during DNS-01 verification

---

💡 Pro Tip

If you support many tenants with custom domains, consider automating the following using Laravel commands or cronjobs:

• Auto-adding domains (via CloudPanel API or SSH)

• Requesting/renewing SSL via CLI (acme.sh, certbot, etc.)

• Updating NGINX config (if needed)

🔌 MySQL Root Integration for Automatic Tenant Provisioning

The MySQL Root Integration allows the SaaS system to perform database-level operations using root or privileged MySQL credentials. This is essential when using a multi-database or isolated-database tenancy model.

📥 Configuration Fields

• Go to Settings > MySQL Root tab in your Concord CRM admin panel.

• Provide the MySQL root credentials or privileged user credentials.

⚙️ How It Works

When creating a new tenant with the "Create a new database" or "I will provide my own credentials" option:

• A new database is automatically created.

• A new MySQL user is created (if enabled).

• Required privileges are assigned to the user.

• Credentials are securely used on the server side only.

🧠 Fallback Behavior

If disabled or credentials aren't provided:

• The system uses the current database connection from .env.

• Ideal for shared hosting or single-database (table-prefix-based) tenancy.

🛡️ Security Recommendations

• You may use a dedicated MySQL user with scoped privileges instead of a root user.

• Avoid reusing root credentials for other services.

• Ensure secure access policies are enforced on your MySQL server.