Perfex SaaS Studio documentation

Perfex SaaS Studio turns one Perfex CRM installation (the platform) into a service: each customer gets a tenant — a separate Perfex workspace with its own database, database user, files and plan modules — provisioned, billed, backed up and upgraded from the platform console.

Licence first

Reselling or hosting Perfex CRM for others requires the Perfex CRM Extended Licence from its author. SaaS Studio is licensed per main installation, not per tenant. Every other module you offer to tenants keeps its own licence terms. SaaS Studio never patches another vendor's licence code.

Installation

Requirements

• Perfex CRM 3.4.x (tested on 3.4.1).
• PHP 8.1 or newer for web and CLI, with mysqli, OpenSSL, mbstring, ZIP, cURL, BCMath, Fileinfo and DOM (SimpleXML for Plesk); at least 256 MB memory per PHP worker.
• proc_open enabled and the mysql and mysqldump binaries. If they are not found automatically, define PSS_PHP_BINARY, PSS_MYSQL_BINARY and PSS_MYSQLDUMP_BINARY in the main configuration.
• MySQL or MariaDB with utf8mb4, and either an account that can create databases and users or a pool of databases you create beforehand.
• Writable tenant, backup and private key folders outside the public web root; POSIX symlinks recommended.
• Cron, HTTPS, and DNS access for subdomains or custom domains.

A VPS or dedicated server is recommended. Shared hosting with cPanel or Plesk works through the Beta adapters below, within your provider's database and process limits.

Server sizing

Measured on an 11-core ARM64 machine with 18 GB RAM and 100 small tenants (99 sharing code, 1 with physical copies):

Starting points: a small pilot on 2 vCPU / 4 GB RAM with 1–2 workers; about 100 light tenants on 4–8 vCPU / 8–16 GB RAM starting with 4 workers. Budget storage for each tenant database, uploads, private module copies, retained backups and room for two copies of the largest tenant. These are empty-tenant numbers: benchmark again with your real modules, data and traffic.

Activate

1. Back up the platform files, database and Perfex encryption key. Install on a staging copy first.
2. Upload perfex_saas_studio-1.0.0.zip under Setup › Modules and activate it on the platform installation only.
3. Activation creates the pss_ tables, a private registry key and adds one guarded line to application/config/app-config.php (a private backup is kept). No Perfex core file is replaced.
4. Store the registry key and the Perfex encryption key in a safe place outside the web server: a database dump without them cannot recover tenant credentials.
5. Open SaaS Studio › Health and Settings; resolve everything before switching on signup. Repair Bootstrap restores the guarded line if needed.

Provisioning

In Settings set absolute tenant and backup roots outside the web root (for example /srv/perfex-tenants and /srv/perfex-backups) and choose how databases are created:

• Database Pool (recommended): create empty databases and users yourself; each user has all privileges on exactly its own database and nothing else. Add them under Add Database Pool; SaaS Studio checks access, emptiness and grants.
• Database Admin: an account that can create databases and users and grant schema privileges. Its credentials are encrypted and never given to tenants.
• cPanel / Plesk — Beta: validated against the panels' API documentation and simulations, not yet against a real panel. A reserved database and user are journalled before any remote call; an uncertain result is never retried as a new identity. Use Panel Allocation Review (administrators only) to retry, adopt or mark cleaned with a reason.

Templates

Register a dedicated, current-version template tenant with only approved sample data — never your live business data. New tenants are cloned from it; logins, sessions, mail queues, keys and secrets are reset. Plans can choose an industry template to start a workspace with sample data for a trade.

Plans and modules

A plan has prices per currency and interval (monthly, yearly, custom days or one-time), a setup fee, taxes, a trial length, sort order, modules, quotas, custom-domain permission, branding, own-SMTP permission and a feature list for the pricing page. Modules lists everything installed with a scanner: reviewed modules are linked into tenants; unknown modules run as private copies until you approve their fingerprint. Perfex Sentinel and Design Studio always run as private copies. Quotas cover staff, customers, contacts, invoices per month, projects, tasks, tickets per month, leads, storage, e-mails per month, API calls per day and AI credits per month.

Module features per plan

Modules can add their own plan switches (1.0.1 and newer). Plans › Module Features shows them as a matrix of the public plans (up to eight; on a phone one plan at a time); section 6 of each plan form shows the same switches for that plan. A level switch (for example Locked, Brand or Full) decides which area switches can be turned on; a lock marks a switch the level does not reach. Save Features stores the values and sends them to the workspaces of the changed plans; Push to Workspaces Now sends every plan again.

• Perfex Design Studio (1.2.1 and newer): Locked keeps your main look read-only, Brand adds the workspace's own Brand Kit to it, Full lets the workspace design its own look; switches for Brand Kit, Themes, Layout & Menu, Login Pages, Website and Custom CSS (off unless you turn it on).
• Downgrade grace: when a workspace moves to a plan with a lower value, it keeps the previous value for the number of days in Settings (30 by default, 0 = at once). The platform cron applies the lower value when the grace ends. Nothing the workspace made is deleted.
• Inside a workspace, modules read the values with pss_plan_feature('module.flag'); pss_upgrade_url() links to the platform's customer portal.
• What a tenant sees (1.0.2): under the matrix, plan tabs show the Design Studio page a workspace admin gets on that plan: the upgrade card on your main look (with the next plan and its price), the Brand Kit only, or the Studio with its open areas. It is drawn from the saved values, so save the features to see a change.
• Compare Plans (1.0.2): the button in the Module Features card opens every module feature of your public plans side by side, grouped by module, with prices and intervals (one plan at a time on a phone). Staff with Settings rights can show the same comparison under the plan cards of the public pricing page (off by default). Only features that their module marks as public appear there; for Design Studio these are the level and the area switches.
• Module developers: add 'public' => true to a feature definition to allow it on the public pricing page (default false).

URLs and DNS

• Path (https://platform.example.com/t/acme/): works without wildcard DNS; route /t/<slug>/ to that tenant's folder.
• Subdomain (https://acme.example.com): add a wildcard DNS record and a wildcard certificate, then set the base domain in Settings.
• Custom domain: the customer adds the shown CNAME (or A record) and a _pss-verification TXT record; you may require approval. A removed domain falls back to the subdomain or path URL.

Web server

Each tenant host or path maps to exactly that tenant's folder; private folders (application, system, temp, backups, private, storage), dot files and every PHP file except index.php must be denied. The download contains tested nginx, Apache and Caddy examples; for Caddy on-demand certificates, point ask at https://platform.example.com/saas/api/domain-check, which only approves verified, active domains. Always run nginx -t, apachectl -t or caddy validate before reloading.

Pricing page and signup

The public pricing page is at /saas/pricing and signup at /saas/signup. Signup asks for plan, interval, currency, workspace address, company, contact and password, checks the address, applies bot timing and optional reCAPTCHA, and sends an e-mail verification. After verification the tenant is provisioned in the background and the customer sees the progress and then a one-time login link. A Perfex customer and contact are created for every signup. Set your legal page URLs, e-mail delivery and payment setup before switching signup on.

Billing

• Perfex invoices (every plan): recurring Perfex invoices paid through your normal Perfex gateways. Add-ons and coupons always use this route.
• Stripe or PayPal subscriptions: native subscriptions for the plan price and tax, with signed webhooks at /saas/webhooks/stripe and /saas/webhooks/paypal, replay protection and an encrypted event queue.
• Unpaid workspaces become past due and then suspended; a billing suspension lifts when payment is recorded.
• Billing Reviews lists cases where the provider and Perfex disagree, with expected and provider amounts. Nothing is guessed: you acknowledge with a note.

Use Stripe test mode and the PayPal sandbox with your own test accounts before going live.

Customer portal

In the Perfex customer area, My SaaS shows the contact's own workspaces with usage, compatible plan changes, invoices, payment method, domains, data exports, cancellation and resume. Contacts can allow support access; support links then expire within 60 seconds.

Tenant workspace

Inside a tenant, the owner sees usage against the plan, company details and logo, staff invitations, a customer CSV import, module choices within the plan, shared or own SMTP and an onboarding checklist. Announcements from the platform appear as a dismissable banner.

Cron and upgrades

Add one platform cron (every five minutes):

*/5 * * * * /usr/bin/php /srv/perfex/index.php pss cli cron >> /var/log/pss-cron.log 2>&1

It runs due tenants through CLI workers (pool of 1–8 in Settings). To upgrade, back up the platform, deploy the new shared code, then run php index.php pss cli upgrade: each tenant is locked, backed up, migrated, and left in maintenance if something fails. Copied modules sync code only and keep their reviewed mutable files. Never use rsync --delete or hard links on tenant folders.

Backups and S3

Backups contain the tenant database, uploads, private module copies and registered private storage. Schedule daily or weekly backups with retention; recovery backups (pre-upgrade, pre-restore, final) are never removed by retention. For S3-compatible storage give an HTTPS endpoint, bucket, region and an identity with PutObject, GetObject and DeleteObject on its prefix. Restore and clone fetch a missing archive from the exact same target and verify its size and SHA-256. Restore always makes a pre-restore backup first.

E-mail

Tenant e-mail goes through a signed private outbox and background SMTP delivery. Bind the platform's TLS SMTP settings for shared delivery, or allow encrypted own SMTP per plan; platform SMTP credentials are never handed to tenants. Operations shows delivery jobs and retries.

REST API

Under /saas/api/: plans, tenants, usage, subscription, suspend, resume and csrf. Issue scoped keys under API Keys; a key is shown once. For JSON POST requests, get the CSRF cookie and token from GET /saas/api/csrf with the bearer key and send X-CSRF-Token. The OpenAPI description is included in the download.

Importer

The importer moves tenants from an earlier SaaS setup: preview the source, map lifecycles and dates, confirm that the old billing has stopped, then commit. Every batch can be undone while its tenants are untouched.

Permissions

SaaS Studio permissions separate viewing, creating and editing tenants, backups, imports and settings. Panel Allocation Review and bootstrap repair are for administrators only. Customer and invoice data still follow Perfex's own permissions.

Isolation

Tenants are separated by database, database user, files, cookies and CSRF tokens. They run under the same operating-system user as the platform, so this is application-level tenancy: offer only modules you trust, and use containers or separate OS users if tenants can upload their own code.

Troubleshooting

• "Workspace unavailable" page: check the tenant status, URL mode and folder mapping, and any queued upgrade.
• A module is missing in a tenant: open its diagnostic from Modules; check the plan, activation and reviewed fingerprint.
• Tenant in maintenance after an upgrade: see Operations for the failing job and the worker log; the pre-upgrade backup is kept.
• Panel provisioning uncertain: use Panel Allocation Review — a timeout is not proof that creation failed.
• Two tenants log each other out: check the cookie path per tenant and your reverse-proxy HTTPS settings.

Changelog

Current version 1.0.2 (24 Oct 2026). Release notes of every version, newest first: perfexcrm.app/saas-studio/changelog/.

1.0.1

• Module features per plan: modules add their own switches (for example the Design Studio level Locked, Brand or Full and its areas); a matrix on Plans and a section in each plan form; values reach workspaces right away.
• Downgrade grace period: a workspace that moves to a lower plan keeps its previous value for 30 days (setting).
• Design Studio 1.2.0 and later run linked in workspaces; older private copies are swapped on the next upgrade run with a backup.

1.0.0

• First release: tenants with separate databases, templates, plans, public pricing and signup, Perfex invoice billing and Stripe/PayPal subscriptions, add-ons, coupons, billing reviews, customer portal, tenant workspace, path/subdomain/custom-domain URLs, one-cron worker pools, queued upgrades, local and S3 backups, restore and clone, database pool/admin provisioning with cPanel and Plesk adapters in Beta, REST API, announcements, importer, audit and CSV exports.
• Same look as our other modules, light and dark, phone layouts; nine languages.

The full list is in changelog.txt in the download.