SaaS Business Management
The ECOSIRE SaaS Business Management module turns Odoo into a control plane for an Odoo hosting business. Provision and manage customer instances on your own servers, bill them on subscription plans, record usage metrics, and monitor instance health -- all from the Odoo backend. It covers provisioning over SSH and Docker (or Kubernetes), custom domains with SSL, backup and restore, migration between versions and servers, a customer self-service portal, and a REST API.
Compatibility: Odoo 17, 18, 19 and 20 (Community or Enterprise)
Price: $499 (one-time)
Current shipped version: 20.0 → 20.0.0.0.12, 19.0 → 19.0.0.0.12, 18.0 → 18.0.0.0.12, 17.0 → 17.0.0.0.12
Menu map
After installation the app appears as SaaS Business Management in the main menu. Everything in this guide is reached from there:
| Menu | Contains |
|---|---|
| Dashboard | KPI cards and charts for the whole platform |
| Instances | Create Instance, All Instances, Templates/Images |
| Contracts | Subscriptions, Billing |
| Reporting | Analytics, Reports |
| Configuration | Settings, Plans, Servers |
The record you provision for a customer is called an Instance. There is no menu called Tenants.
Key Features
- Multi-instance management with one isolated database per instance
- Automated provisioning over SSH and Docker, with Kubernetes support
- Subscription plans with monthly and yearly pricing
- Usage records for CPU, memory, storage, bandwidth, API calls, active users, transactions and custom metrics
- Instance lifecycle states: Draft, Deploying, Running, Suspended, Cancelled
- Per-server capacity limits with available-slot tracking
- Dashboard with 6 KPI cards and 4 Chart.js charts
- Backup and restore, with configurable retention and scheduling
- Custom domains with SSL certificate status tracking and auto-renewal
- Migration wizard for version and server moves, with rollback on failure
- Customer self-service portal under
/my/saas - REST API under
/saas/api/v1/ - Stripe and PayPal payment integrations
Prerequisites
- Odoo 17, 18, 19 or 20 (Community or Enterprise edition)
- At least one host server you can reach over SSH, prepared as described under Prepare a Server
- Python packages on the Odoo host:
paramiko,docker,requests,cryptography,psycopg2,redis,celery - Sufficient disk space for instance data and backups
Installation
- Download the module ZIP from your ECOSIRE Dashboard
- Extract to your Odoo addons directory:
unzip ecosire-saas-business-management-*.zip -d /opt/odoo/addons/
- Restart the Odoo service:
sudo systemctl restart odoo
- Navigate to Apps, click Update Apps List
- Search for "SaaS Business Management" and click Install
Configuration
Configure in this order. Provisioning will not offer you a server until at least one server record is active, connected and has a free slot.
Step 1: Add a Server
- Navigate to SaaS Business Management then Configuration then Servers
- Click New and fill in:
- Server Name
- Server Type -- Docker, Kubernetes, Virtual Machine, Bare Metal, or Simulated (Demo/Sandbox)
- Host Address and SSH Port (default 22)
- SSH User, and either SSH Password or SSH Private Key Path
- Max Instances -- the capacity cap for this server (default 10)
- Region (optional)
- Click Test Connection. The Connection Status field moves to Connected or Connection Failed, and Last Connection Test is stamped.
- Confirm Available Slots is above zero.
Simulated (Demo/Sandbox) servers skip SSH and Docker entirely -- instances are created as records and marked running immediately. Use them for demos and sandboxes, never for real hosting.
A server is only offered in the instance-creation wizard when it is active, connected and has available slots. A server whose connection test failed, or which is full, will not appear in the dropdown.
Step 2: Define Plans
- Navigate to SaaS Business Management then Configuration then Plans
- Click New and configure:
- Plan Name and Description
- Monthly Price (required) and Yearly Price
- Max Users and Max Instances
- Included Modules -- the Odoo modules installed in each instance on this plan, see What a Plan Installs
- Sequence -- display order on the pricing page
- Active -- clear this to retire a plan without deleting it
- Click Save
Step 3: Global Settings
Navigate to SaaS Business Management then Configuration then Settings. The available settings are:
| Group | Settings |
|---|---|
| Defaults | Default Odoo Version, Default Server, Max Instances per Server (50), Trial Duration in days (14) |
| Backups | Enable Auto Backup, Backup Frequency (daily, weekly, monthly), Backup Retention in days (30) |
| Monitoring | Enable Monitoring, Alert Email, CPU Threshold % (80), Memory Threshold % (85) |
| Lifecycle | Auto Suspend Inactive Instances, Inactive Threshold in days (30) |
| Notifications | Notification Email, Webhook URL, API Key |
| Docker | Docker Registry URL, Docker Network Name (saas_network) |
| Kubernetes | Enable Kubernetes Support, Default Kubernetes Namespace (odoo-saas), Odoo Docker Image (odoo:19) |
| SSL | Enable SSL by Default, SSL Certificate Path, SSL Key Path |
Public endpoints this module exposes
The module serves 7 externally reachable endpoints. Each path is relative to your Odoo base URL (web.base.url), so a full address looks like https://erp.example.com/saas/api/v1/analytics.
| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
/saas/api/v1/analytics | GET | Public (unauthenticated) | Get analytics data via API |
/saas/api/v1/instances | GET | Public (unauthenticated) | Get SaaS instances via API |
/saas/api/v1/instances/<int:instance_id> | GET | Public (unauthenticated) | Get specific SaaS instance via API |
/saas/api/v1/webhooks | POST | Public (unauthenticated) | Handle incoming webhooks |
/saas/payment/paypal/webhook | POST | Public (unauthenticated) | PayPal payment notifications, verified with PayPal for the gateway's Webhook ID |
/saas/payment/stripe/webhook | POST | Public (unauthenticated) | Stripe payment notifications, verified with the gateway's signing secret |
/saas/pricing | POST | Public (unauthenticated) | Externally reachable endpoint exposed by the module. |
These paths answer without an Odoo user session — that is what makes them reachable from outside your database. Register each one where the platform expects it (a webhook callback URL, an OAuth redirect URI, or an endpoint your integration calls) exactly as written above; a path the platform does not have on file is never delivered.
Prepare a Server
The server needs Docker, Nginx, curl, openssl and flock, and SSH from your Odoo as root or as a user with passwordless sudo. Point a wildcard DNS record such as *.clients.example.com at it.
Under Configuration > Servers, enter the host and SSH details and set Platform Domain to clients.example.com. Instances then get addresses like acme.clients.example.com.
On the first deployment the server gets a private Docker network and one PostgreSQL container with no published port. Each instance is published on the server's loopback interface only, and Nginx routes its address to it.
Provisioning a New Instance
- Go to SaaS Business Management then Instances then Create Instance
- Fill in the wizard:
- Template (optional) -- fills plan, server, version and domain
- Customer (required) -- the contact the instance belongs to
- Plan (required)
- Subdomain (required) -- for example
mycompanyformycompany.yourdomain.com - Domain -- defaults to the server's Platform Domain
- Server -- only provisionable servers are listed
- Odoo Version -- 17, 18, 19 or 20
- Custom Domain (optional)
- Trial Instance -- tick to create the instance as a trial
- Notes
- Click one of:
- Create Instance -- creates the instance record in Draft
- Create & Deploy -- creates it and starts deployment immediately
- Deployment runs on the server in the background and usually takes a few minutes. It creates the database, installs the plan's apps, sets the first login, starts the container and routes the address. The instance moves to Running only when its login page answers. Follow it on the Deployment and Login tab, or press Check Deployment. If a step fails, the instance returns to Draft with the step named, and you can deploy again.
- Several deployments can run on one server at the same time, each on its own port.
- Press Send Login Details to email the customer their address and first login. They can add more apps from the Apps menu of their own database.
The instance Name is assigned automatically by a sequence; you do not type it. Existing instances are listed under Instances then All Instances, which opens filtered to running instances by default.
What a Plan Installs
Included Modules on a plan are installed in the instance's database at deployment. If any of them does not install, the deployment fails.
Custom Apps and Odoo Enterprise
Each instance has its own addons folder at /var/lib/saas/instances/<database>/addons, and all instances on a server share /var/lib/saas/shared-addons. Put a custom app in one of them, update the Apps list inside the instance and install it there. Both folders hold a small saas_addons_folder placeholder that cannot be installed: leave it in place, because Odoo 19 and later skip an empty addons folder when they start.
Instances run the public Odoo image, which is Community edition. Enterprise apps need your own licence and source from Odoo.
Custom Domains
Set a custom domain on the instance and press Activate: the site now answers on both addresses. Certbot issues one certificate for all the instance's addresses, so every address must resolve to the server and port 80 must be open. The instance link shows http until a certificate exists.
If a certificate cannot cover the new domain, usually because its DNS is not ready yet, activation is refused and the instance keeps the addresses and the HTTPS it had. Press Deactivate to take a domain off: it stays off through later certificates and redeployments until you activate it again.
The certificate contact is your company's email address. When that is empty or not a real address, the certificate is registered without a contact.
Dashboard
SaaS Business Management then Dashboard shows:
- 6 KPI cards -- Total Instances, Monthly Revenue, Active Subscriptions, Server Utilization, New Today, Suspended
- 4 Chart.js charts -- instance trend, revenue trend, server status and subscription status
- A Quick Actions card and a Refresh button for on-demand reload
Instance Lifecycle
An instance carries one of these states:
| State | Description |
|---|---|
| Draft | Created but not yet deployed |
| Deploying | Provisioning in progress |
| Running | Deployed and operational |
| Suspended | Temporarily disabled (payment overdue or manual suspension) |
| Cancelled | Terminated |
Trial status is a separate Trial flag on the instance rather than a state, so a trial instance is Running like any other. An Expiration Date governs when it lapses, and the default trial length comes from Trial Duration (Days) in Settings.
Subscriptions have their own states: Draft, Active, Suspended, Cancelled and Expired.
Customer Portal
Customers sign in to your Odoo and manage their own instances under /my/saas:
| Path | Purpose |
|---|---|
/my/saas | Portal home |
/my/saas/instances | Their instances, and per-instance actions |
/my/saas/subscriptions | Subscriptions |
/my/saas/billing | Billing records |
/my/saas/usage | Usage metrics |
/my/saas/plans | Available plans, and a request form for an instance |
/my/saas/api-keys | Create and revoke API keys; the create form itself is posted to /my/saas/api-keys/create |
/my/saas/support | Your contact details (not support requests: the page shows how to reach you) |
A customer can suspend and resume their own instance. An instance you suspended, or one whose subscription is on hold, can only be resumed by you, and the portal tells the customer to contact you.
Get Started on the public pricing page at /saas/pricing opens the same request form, after the customer logs in. A request records a draft instance and a subscription and gives a SaaS Manager a task. It does not start a deployment and takes no payment: the SaaS Manager deploys each instance. To let visitors create an account, enable sign-up in the Odoo settings.
Payment Notifications (Stripe and PayPal)
Each payment gateway receives its provider's notifications at its own address:
- Stripe: add an endpoint at
https://<your Odoo>/saas/payment/stripe/webhookin the Stripe dashboard and paste its signing secret (whsec_...) into the gateway's Webhook Secret. A delivery is accepted only when itsStripe-Signaturematches that secret and is less than five minutes old. - PayPal: add a webhook at
https://<your Odoo>/saas/payment/paypal/webhookin the PayPal developer dashboard and copy its id into the gateway's Webhook ID. Each delivery is confirmed with PayPal before it is applied.
A delivery that is unsigned, wrongly signed or too old is refused (HTTP 400) and changes nothing. Applied notifications update the payment transaction or the matching subscription.
Users, Groups and Companies
- SaaS User reads instances, servers, plans, subscriptions, billing, backups, monitoring, alerts, usage, regions and the dashboard, and changes nothing.
- SaaS Manager has full access and is the only role that deploys, suspends, backs up, restores or bills.
- SaaS Administrator includes everything a SaaS Manager can do.
- Multi-company: instances, servers, subscriptions and billing records belong to a company (the one you are working in when you create them; subscriptions and billing follow their instance). Users see only the records of the companies they work in. Leave a server's company empty to share it between companies.
REST API
Instances can be managed programmatically under /saas/api/v1/instances, supporting GET, POST, PUT and DELETE. A key opens the API when you bind it to an internal user with SaaS rights. A key a customer creates in the portal is bound to their portal user, which has no rights on SaaS records, so it does not open the API.
Backups and Migration
- Backup and restore run from the backup wizard on an instance: choose the operation and backup type, and optionally include the instance's log. Backups land in
/opt/backups/<database>on the server, each with a small manifest. - A restore replaces the instance's database and files, so the wizard asks you to tick Overwrite Existing Data. It checks the backup and loads the dump beside the live database before it touches the instance, so a backup that cannot be loaded changes nothing. What it replaced stays on the server until the next restore. An instance that was suspended stays suspended. Only a SaaS Manager can run one.
- Incremental backups hold the files changed since the last full backup, so what you restore is a full backup.
- A non-root SSH user works for backups and restores, given passwordless sudo.
- Migration runs from the migration wizard: pick a migration type, source and target Odoo version, the instances or servers in scope, and a maintenance window. Backup before migration, validation, customer notification and rollback on failure are all switchable, with a maximum downtime setting.
Troubleshooting
| Issue | Solution |
|---|---|
| No server appears in the creation wizard | The server must be Active, its Connection Status must be Connected, and Available Slots must be above zero. Open Configuration then Servers and run Test Connection. |
| "Selected server cannot host new instances" | The server is inactive, unreachable or full. Choose another server or raise its Max Instances. |
| Provisioning failed | Open the Deployment and Login tab. Deployment Error names the step and Deployment Log shows the output. |
| Instance not accessible | Check DNS for the address. On the server, nginx -t and docker ps. |
| Billing not processing | Confirm the instance has a plan assigned and an active subscription. |
| Backup failures | Check backup storage permissions and available disk space. |
| Migration stuck | Review the migration wizard's status message and confirm the target version is valid for the instance. |