Configuration Instructions

This document provides an explanation of the framework-related fields in cloudbaserc.json.

Before using CloudBase Framework, you need to create a cloudbaserc.json configuration file. The cloudbaserc.json file serves as the configuration file for CloudBase CLI, CloudBase VSCode extension, and CloudBase applications, determining how CloudBase builds and deploys your application.

The framework` field contains configuration information for CloudBase Framework. For other configurations, please refer to https://docs.cloudbase.net/cli-v1/config.html.

Here is an example of a cloudbaserc configuration file:

{
  "envId": "{{env.ENV_ID}}",
  "$schema": "https://framework-1258016615.tcloudbaseapp.com/schema/latest.json",
  "version": "2.0",
  "framework": {}
}

The CloudBase Framework configuration file includes the following categories of configuration information:

Category	Description
Project Information	Describe your application information
Plugin Configuration	Describes which CloudBase Framework plugins your application depends on to build and deploy your application based on the configuration.
Lifecycle	Configures custom actions to be executed before and after the build and deploy lifecycle.
Application Dependencies	Configures extended resources and environment variables that the application depends on for one-click cloud deployment scenarios.
Template Variables	Allows the use of template variables in configurations to achieve dynamic configuration.

Project Information

Project information is used to describe your application information.

`name`

Type: `String

Requirements:

Length: 1-32 characters
Supports only A-Z a-z 0-9 - and _

The unique application identifier requires that duplicate names are not allowed under the same account.

Example:

{
  "framework": {
    "name": "cloudbase-helloworld"
  }
}

Plugin Configuration

Describes which CloudBase Framework plugins your application depends on to build and deploy your application based on the configuration.

`plugins`

Type: Record<string,PluginConfig>

Describes which CloudBase Framework plugins your application depends on, so that your application can be built and deployed based on the configuration. Applications can use multiple plugins. For specific plugin configuration methods, refer to the following section.

Example:

{
  "framework": {
    "plugins": {}
  }
}

`plugins.<deploy_name>`

Type: PluginConfig

Single plugin configuration

Consists of PluginConfig objects:

Field	Description	Type
`use`	The npm package name of the plugin used, for example, `@cloudbase/framework-plugin-website`, supports specifying the plugin version, for example, `@cloudbase/framework-plugin-website@1.3.5`	`String`
`inputs`	Configuration for plugin input parameters. Different plugins support different input parameters. Please refer to the README or documentation of the corresponding plugin.	`Object`

For the list of currently supported plugins, please refer to https://github.com/Tencent/cloudbase-framework#currently-supported-plugins

Example:

{
  "framework": {
    "plugins": {
      "client": {
        "use": "@cloudbase/framework-plugin-website",
        "inputs": {
          "buildCommand": "npm run build",
          "outputPath": "dist",
          "cloudPath": "/vue"
        }
      },
      "server": {
        "use": "@cloudbase/framework-plugin-function",
        "inputs": {
          "functionRootPath": "cloudfunctions",
          "functions": [{
            "name": "vue-echo"
          }]
        }
      }
    }
  }
}

Lifecycle

Configuring custom actions to be executed before and after the build and deploy lifecycle.

`hooks`

Type: HoosConfig

The hook configuration for CloudBase Framework before and after deployment allows customizing execution actions for different application lifecycles here.

Pre-hook, a hook executed before the full build and deployment actions of the Framework, can run command-line commands.

Configuration consists of the following objects:

Field	Description	Type
`prevDeploy`	Pre-hook configuration information	`PreDeployHooksConfig`
`postDeploy`	Post-hook configuration information	`PostDeployHooksConfig`

Example:

{
  "framework": {
    "hooks": {}
  }
}

`hooks.preDeploy`

Type: PreDeployHooksConfig

Pre-hook, a hook executed before the full build and deployment actions of the Framework, can run command-line commands.

Configuration consists of the following PreDeployHooksConfig objects:

Field	Description	Type
`type`	The type of the pre-hook, currently only supports `execCommand`, which means executing command-line commands	`String`
`commands`	List of `command` commands to be executed	`Array`

Example:

{
  "framework": {
    "hooks": {
      "preDeploy": {
        "type": "execCommand",
        "commands": [
          "sudo npm install -g lerna",
          "lerna bootstrap"
        ]
      }
    }
  }
}

`hooks.postDeploy`

Type: PostDeployHooksConfig

Post-hook, a hook invoked in the cloud after the deployment of the Framework, can call some cloud functions.

Configuration consists of the following PostDeployHooksConfig objects:

Field	Description	Type
`type`	The type of the pre-hook, currently only supports `callFunction`, which means executing cloud functions in the cloud	`String`
`functions`	List of cloud functions to be invoked, supports array, for example	`Array<FunctionConfig>`

The FunctionConfig` object format is as follows:

Field	Description	Type
`functionName`	Name of the cloud function to be invoked	`String`
`params`	Parameter information for invoking cloud functions	`Record<string,string>`

Example:

{
  "framework": {
    "hooks": {
      "postDeploy": {
        "type": "callFunction",
        "functions":[
          {
            "functionName": "echo",
            "params": {
              "foo": "bar"
            }
          }
        ]
      }
    }
  }
}

Application Dependencies

In one-click cloud deployment scenarios, you need to configure application dependencies to declare extended resources and environment variables that the application depends on.

`requirement`

Type: RequirementConfig

Describes business parameters such as dependent resource information and environment variables when the project is installed and deployed with one click via the console.

The RequirementConfig` object format is as follows:

Field	Description	Type
`addons`	External cloud resources used during application deployment, including cfs, cynosdb, redis, etc.	`AddonsConfig`
`environment`	Declares environment variables for the application at build time and runtime, injected by default into the computing environment (Cloud Functions, Cloud Applications), also used as environment variables during cloud build and deployment, and can be referenced in `cloudbaserc.json` via `{{env.ENV_NAME}}`	`EnvironmentConfig`

`requirement.addons`

Type: AddonsConfig

External cloud resources used during application deployment, including cfs, cynosdb, redis, etc.

The AddonsConfig` object format is as follows:

Field	Description	Type
`type`	Resource type, currently supports `CFS` and `CynosDB`	`'CFS'	'CynosDB'`
`name`	Resource name, supports only a-z, 0-9, and -	`String`
`envMap`	Maps the IP and PORT generated by cloud resources to corresponding environment variable names using the defined keys and injects them into the environment.	`Record<string, string>`

Currently supported resources:

Type	Description	Exported Environment Variables
`CFS`	Shared file storage service. CFS can be used in conjunction with cloud-hosted container services to provide elastic, high-performance shared storage for multiple compute nodes.	None
`CynosDB`	Tencent Cloud database CynosDB (TencentDB for CynosDB) is a self-developed new generation of high-performance, highly available enterprise-grade distributed cloud database. Currently supports the database engine MySQL 5.7	`IP`, `PORT`, `USERNAME`, `PASSWORD`

Example:

  "framework": {
    "requirement": {
      "addons": [
        {
          "type": "CynosDB",
          "name": "wordpress",
          "envMap": {
            "IP": "WORDPRESS-IP",
            "PORT": "WORDPRESS-PORT",
            "USERNAME": "WORDPRESS-USERNAME",
            "PASSWORD": "WORDPRESS-PASSWORD"
          }
        }
      ]
    }
  }
}

`requirement.environment`

Type: Record<string,EnvironmentConfig>

Declares environment variables for the application at build time and runtime, injected by default into the computing environment (Cloud Functions, Cloud Applications), also used as environment variables during cloud build and deployment, and can be referenced in cloudbaserc.json via {{env.ENV_NAME}}

Configuration consists of the environment variable key and an object of related environment variable options, with the environment variable options in the format EnvironmentConfig

The EnvironmentConfig` object format is as follows:

Field	Description	Type
`description`	Environment variable description, which will prompt during input	`String`
`required`	Required	`Boolean`
`default`	Default value	`String`
`validation`	Validation rule configuration	`ValidationConfig`

The ValidationConfig` object format is as follows:

Field	Description	Type
`rule`	Validation rule information	`RuleConfig`
`errorMessage`	Error message when validation fails	`String`

`| Field | Description | Type |

Field	Description	Type
`type`	Validation rule type, currently supports `"RegExp"` for regular expression	`String`
`pattern`	Pattern for regular expression	`String`
`flag`	Flag for regular expression	`String`

Example:

{
  "framework": {
    "requirement": {
      "environment": {
        "SECRET_TOKEN": {
          "description": "A secret key for verifying the integrity of signed cookies.",
          "required": true,
          "default": "default_value",
          "validation": {
            "rule": {
              "type": "RegExp",
              "pattern": "[3-9]",
              "flag": "g"
            },
            "errorMessage": "Value must be 3-9"
          }
        }
      }
    }
  }
}

Template Variables

The configuration file supports the dynamic variables feature. Enable it by declaring "version": "2.0" in cloudbaserc.json.

The dynamic variables feature allows the use of dynamic variables in the cloudbaserc.json configuration file to retrieve dynamic data from environment variables. Values enclosed in {{}} are defined as dynamic variables, which can reference values from data sources. For example, {{env.ENV_ID}}:

Step 1: Create cloudbaserc.json and .env files in the project root directory.

`plain text . ├─cloudbaserc.json ├─.env

Step 2: Add variables in the **.env** file.

`plain text
ENV_ID=pro-123
DB_NAME=pro_user

Step 3: Inject template variables via env in the cloudbaserc.json file.

{
  "version": "2.0",
  "envId": "{{env.ENV_ID}}",
  "framework": {
    "name": "node-capp",
    "plugins": {
      "node": {
        "use": "@cloudbase/framework-plugin-node",
        "inputs": {
          "name": "node-capp",
          "path": "/node-capp",
          "platform": "container",
          "containerOptions": {
            "envVariables": {
              "env": "{{env.ENV_ID}}",
              "db": "{{env.DB_NAME}}"
            }
          }
        }
      }
    }
  }
}

Step 4: One-click application deployment

cloudbase framework deploy

Mode Switching

Assuming you have completed the configuration of the above template variables

Step 1: Additionally create the .env.dev file in the project root directory.

`plain text . ├─cloudbaserc.json ├─.env ├─.env.dev

Step 2: Add variables in the **.env.dev** file.

`plain text
ENV_ID=dev-123
DB_NAME=dev_user

Step 3: Specify the mode using --mode when deploying applications.

cloudbase framework deploy --mode dev

Complete Sample

{
  "version": "2.0",
  "envId": "{{env.ENV_ID}}",
  "$schema": "https://framework-1258016615.tcloudbaseapp.com/schema/latest.json",
  "framework": {
    "plugins": {
      "admin": {
        "use": "@cloudbase/framework-plugin-website",
        "inputs": {
          "outputPath": "./packages/admin/dist",
          "installCommand": "echo \"Skip Install\"",
          "buildCommand": "npm run build",
          "cloudPath": "{{env.deployPath}}"
        }
      },
      "init": {
        "use": "@cloudbase/framework-plugin-function",
        "inputs": {
          "functionRootPath": "./packages",
          "functions": [
            {
              "name": "cms-init",
              "timeout": 60,
              "envVariables": {
                "CMS_ADMIN_USER_NAME": "{{env.administratorName}}",
                "CMS_ADMIN_PASS_WORD": "{{env.administratorPassword}}",
                "CMS_OPERATOR_USER_NAME": "{{env.operatorName}}",
                "CMS_OPERATOR_PASS_WORD": "{{env.operatorPassword}}",
                "CMS_DEPLOY_PATH": "{{env.deployPath}}",
                "ACCESS_DOMAIN": "{{env.accessDomain}}"
              },
              "installDependency": true,
              "handler": "index.main"
            }
          ]
        }
      },
      "service": {
        "use": "@cloudbase/framework-plugin-node",
        "inputs": {
          "name": "tcb-ext-cms-service",
          "entry": "app.js",
          "projectPath": "./packages/service",
          "path": "/tcb-ext-cms-service",
          "functionOptions": {
            "timeout": 15,
            "envVariables": {
              "NODE_ENV": "production"
            }
          }
        }
      },
      "db": {
        "use": "@cloudbase/framework-plugin-database",
        "inputs": {
          "collections": [
            {
              "collectionName": "tcb-ext-cms-projects",
              "description": "CMS system project data (Please do not modify manually)",
              "aclTag": "ADMINONLY"
            },
            {
              "collectionName": "tcb-ext-cms-schemas",
              "description": "CMS system content model data (Please do not modify manually)",
              "aclTag": "ADMINONLY"
            },
            {
              "collectionName": "tcb-ext-cms-users",
              "description": "CMS system user data, storing CMS user information including administrator account details, role information, etc. (Please do not modify manually)",
              "aclTag": "ADMINONLY"
            },
            {
              "collectionName": "tcb-ext-cms-webhooks",
              "description": "CMS system webhook collection, storing the callback interface configuration for the CMS system. Changes to CMS system data can be synchronized via callbacks (Please do not modify manually)",
              "aclTag": "ADMINONLY"
            },
            {
              "collectionName": "tcb-ext-cms-settings",
              "description": "CMS system configuration collection, storing the settings of the CMS system (Please do not modify manually)",
              "aclTag": "ADMINONLY"
            },
            {
              "collectionName": "tcb-ext-cms-user-roles",
              "description": "CMS system user role configuration collection, storing custom user role information for the CMS system (Please do not modify manually)",
              "aclTag": "ADMINONLY"
            }
          ]
        }
      }
    },
    "requirement": {
      "addons": [],
      "environment": {
        "administratorName": {
          "description": "Administrator account name, which must be longer than 4 characters and can only contain letters and numbers",
          "required": true,
          "default": "admin",
          "validation": {
            "rule": {
              "type": "RegExp",
              "pattern": "[^[a-zA-Z0-9]+[a-zA-Z0-9_-]?[a-zA-Z0-9]+$]",
              "flag": "g"
            },
            "errorMessage": "Combination of letters and numbers, cannot be all numbers, length must be 1-32"
          }
        }
      }
    }
  }
}

Configuration Instructions

Project Information​

name​

Plugin Configuration​

plugins​

plugins.<deploy_name>​

Lifecycle​

hooks​

hooks.preDeploy​

hooks.postDeploy​

Application Dependencies​

requirement​

requirement.addons​

requirement.environment​

Template Variables​

Mode Switching​

Complete Sample​

Project Information

`name`

Plugin Configuration

`plugins`

`plugins.<deploy_name>`

Lifecycle

`hooks`

`hooks.preDeploy`

`hooks.postDeploy`

Application Dependencies

`requirement`

`requirement.addons`

`requirement.environment`

Template Variables

Mode Switching

Complete Sample