Benefits of Multi-instance

CabloyJS supports the development of multi-domain/multi-tenant SAAS system through the concept of multi-instance. You only need to start one backend service to support multiple instances running at the same time. Instances share the database schema, but the data generated dynamically is isolated from each other

Application Scenarios of Multi-instance

For example, we have developed a set of enterprise business systems to provide multi-tenant SAAS services for many enterprise users

Instance & Subdomain

CabloyJS distinguishes which instance is currently serving by judging the subdomain of the website

For example, if the domain name of the website visited by the user is tenant1.my-saas.com, the subdomain name is tenant1, and the system will automatically assign an instance to tenant1

  • The system will automatically inject subdomain and instance information into ctx. How do you access them?
  1. 1// subdomain
  2. 2const subdomain = ctx.subdomain;
  3. 3// current instance
  4. 4const instance = ctx.instance;
  5. 5// current instance id
  6. 6const iid = ctx.instance.id;

How to customize the rules of subdomain?

By default, subdomain is obtained based on the secondary domain name. You can modify the rule by modifying the parameter subdomainOffset in the configuration file

/{project}/src/backend/config/config.prod.js

  1. 1  config.subdomainOffset = 1;
  • For Example
domain subdomainOffset subdomain
zhennann.cabloy.com 2 (default) zhennann
zhennann.cabloy.com 1 cabloy.zhennann

Instance Configuration

1. Unit-test & Development Environment

In the unit-test and development environment, the website domain name is generally 127.0.0.1 or localhost. The system assigns a default instance for such a local scenario by default, so no additional configuration is required

2. Production Environment

In the production environment, need to plan the corresponding relationship between the instance and the subdomain by yourself

For example, the official backend of CabloyJS hosts two instances, namely https://portal.cabloy.com and https://admin2.zhennann.com. The configuration of it’s production environment is as follows:

/{project}/src/backend/config/config.prod.js

  1. 1// instances
  2. 2config.instances = [
  3. 3  { subdomain: 'admin', password: '', title: 'CabloyJS', config: {} },
  4. 4  { subdomain: 'admin2', password: '', title: 'My Blog', config: {} },
  5. 5  ];
Name Description
subdomain If the URL is https://cabloy.com, the corresponding subdomain is an empty string
password The initial password of the user root for this instance. The default value is 123456
title Website’s title
config instance level configuration, which will override the module level configuration automatically

How to use Multi-instance?

- current instance Id

Because the data between multiple instances is isolated from each other, the condition of current instance id must be taken when performing CRUD operations

  1. 1// current instance id
  2. 2const iid = this.ctx.instance.id;
  3. 3// insert
  4. 4await this.ctx.db.insert('testParty', {
  5. 5  iid,
  6. 6  deleted: 0,
  7. 7  personCount: 3,
  8. 8});
Name Description
ctx.instance current instance object
ctx.instance.id current instance id

- model

The object of model further encapsulates ctx.db, which facilitates support for multi-instance and soft deletion

  1. 1// insert
  2. 2await this.ctx.model.party.insert({
  3. 3  personCount: 3,
  4. 4});