diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ef07f7..aeb569c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +## 0.6.4 (July 29, 2022) + +- docs: update doc for Blocklet Meta Spec + ## 0.6.3 (June 27, 2022) - docs: update doc for Blocklet SDK diff --git a/blocklet.yml b/blocklet.yml index 7d2a4e8..e2e4026 100644 --- a/blocklet.yml +++ b/blocklet.yml @@ -1,5 +1,5 @@ name: '@arcblock/abtnode-docs' -version: 0.6.3 +version: 0.6.4 description: >- Blocklet Server Documentation, a help documentation for quickly get started with Blocklet Server. diff --git a/package.json b/package.json index 842cbab..c29aaa6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@arcblock/abtnode-docs", - "version": "0.6.3", + "version": "0.6.4", "description": "Blocklet Server Documentation, a help documentation for quickly get started with Blocklet Server.", "main": "index.js", "publishConfig": { diff --git a/src/developer/blocklet-spec/index.md b/src/developer/blocklet-spec/index.md index faf172c..bd47daa 100644 --- a/src/developer/blocklet-spec/index.md +++ b/src/developer/blocklet-spec/index.md @@ -1,6 +1,6 @@ --- -title: Blocklet Specification -description: 'Blocklet Specification' +title: Blocklet Meta Spec +description: 'Blocklet Meta Specification' keywords: 'blocklet server,blocklet,specification' author: 'zhenqiang, wangshijun' category: '' @@ -11,179 +11,209 @@ tags: - specification --- ->
This page is outdated and must be updated
+> The following only lists the configurations that developers need to care about. For the complete documentation, see [github.com/blocklet/blocklet-specification](https://github.com/blocklet/blocklet-specification/blob/main/docs/meta. md) + +```yml +did: z8iZrkWYbi3JU3AP9NHJQbBUdrgiRbeorauqf # Blocklet DID +name: example # Human readable Blocklet ID, did derived from name. To define the application name please use title +version: 1.0.0 # Blocklet version number +title: Example APP # application name +description: App Description # App description +logo: logo.png # application logo file +files: # Which files need to be packaged into the bundle + - logo.png + - screenshots + - hooks +screenshots: # Picture introduction, which will be displayed on the store's introduction page + - 0.png + - 1.png + - 2.png +scripts: # Blocklet hook directive + dev: npm run start # The command actually executed when `blocklet dev` is executed + preInstall: node hooks/pre-install.js # hooks before installation + preDeploy: node hooks/pre-deploy.js # pre-deployment hooks (install `blocklet deploy` in deployment mode) + postInstall: node hooks/post-install.js # hook after installation + preStart: node hooks/pre-start.js # hook before startup + preStop: node hooks/pre-stop.js # hook before stop + preUninstall: node hooks/pre-uninstall.js # Hook before deletion +timeout: + start: start timeout +payment: # Blocklet Price + price: # can specify multiple currencies + - address: z35n6UoHSi9MED4uaQy6ozFgKPaZj2UKrurBG # token address + value: 8 # price + share: # share + - name: Bob # account alias + address: z1QUDFzp6wKhLFjV4sG1ACY3J3ePcknrviy # Account DID + value: 0.7 # split ratio + - name: Store # Account alias + address: zNKr4EeqcMk4W4TpBYD7MzGj6UEua53vJFx1 # Account DID + value: 0.3 # split ratio +interfaces: # Blocklet access interface (most of the following configurations do not need to be concerned, just focus on the auth configuration) + - type: web # access interface type + services: + - name: auth # Auth service for this access interface + config: + whoCanAccess: all # Who can access + blockUnauthenticated: false # Whether to automatically intercept unauthenticated requests and jump to the login page + blockUnauthorized: false # Whether to automatically intercept unauthorized requests + allowSwitchProfile: true # Whether to support switching profiles + profileFields: # Information to provide when logging in + - fullName + - email + - avatar + ignoreUrls: [] # Which interfaces allow any request to access + protocol: http # access interface type + name: publicUrl # usually does not need to be modified + port: BLOCKLET_PORT # Environment variable for receiving port (port number is generated by Blocklet Server) + path: / # Default prefix when Bloclet receives requests + prefix: '*' # Blocklet is mounted prefix +environments: # runtime environment variables + - name: key # variable name + description: xxxx # variable description + default: '' # default value + required: false # Is it required + secure: false # Whether it is sensitive information + shared: true # Is it public. Defaults to true, shared must be false when secure is true +requirements: + server: '>=1.8.0' # server version constraints + os: '*' + cpu: '*' + fuels: # Fuel needed before starting (token) + endpoint: xxx # The address of the chain + address: xxx # token address + value: xxx # price + reason: xxx # The reason for the need (for example, because the NFT Factory needs to be created before the first boot) +capabilities: + clusterMode: false # Can blocklet be started in cluster mode + component: true # Can blocklet become a component and be composed by other blocklets +children: # Usually no manual maintenance is required, it can be maintained through `blocklet add/remove` + - name: xxx # Human readable ID (required) + source: # installation source + # install via url + url: xxx + # install via store + store: xxx # store address + name: xxx # Blocklet ID + version: xxx # Blocklet version + mountPoint: /path/to # mount point + title: xxx # name + description: xxx # description +navigation: # navigation information (app map) + - title: xxx name + # link to a url + link: xxx + # link to child component + child: xxx # child name or child did + section: # where I want to show + - header + - footer + icon: mdi:home # icon +theme: # theme + background: "#f5f5f5" # background color +copyright: # Copyright information + owner: Arcblock # owner + year: 2022 # If not written, take the current year -## What is Blocklet? - -Blocklet is an application protocol and software architecture. As a protocol, it describes the way to build the Blocklet Server platform; as software architecture, an independent blocklet is a reusable software module, which may be an HTTP service or a function library, etc.; when multiple When blocklets run together, they need a platform to combine them to form an independent service, such as Blocklet Server. +``` -## How to define a Blocklet? +## Configure Navigation -We use JSON data format to describe the protocol of blocklet. +A more complete example: [Component Demo](https://github.com/blocklet/component-demo/blob/main/blocklet.yml) -## Define basic information +#### i18n support -```json -{ - "name": "blocklet name, can be same as npm package name", - "description": "blocklet description, can be same as npm package description", - "version": "blocklet version, can be same as npm package version", - "group": "only `dapp|static` are allowed and supported" -} +```yml +title: xxx ``` -`name, description, version, group` describes the basic information of the blocklet. Among them, `group` is divided into two types of `dapp` and `static`. `dapp` is a regular dapp. `static` is a web application that only contains front-end static resources. Blocklet Server will use an HTTP Server to serve `static` Blocklet. - -## Define runtime configuration +or -```json -{ - "main": "the entrypoint to bundle the blocklet or the static folder", - "requiredEnvironments": { - "name": "string, name of the environment", - "description": "string, description of the environment", - "required": "bool, is required", - "default": "Any type, default value" - } -} +```yml +title: +en: xxx +en: xxx ``` -In addition to the description of the basic information of the blocklet, the blocklet also defines the `main` field to describe how the blocklet starts to run, which is the description of the so-called entry file. This field is closely related to the operation of the blocklet. `main` defines the entry file or static resource directory of dapp or static type blocklet. So for Blocklet Server, the `main` field is necessary; otherwise, Blocklet Server has no way to start Blocklet. - -In addition to the `main` field, we also need to define the `requiredEnvironments` field to declare the environment variables that the blocklet needs to run. There are four attributes that describe an environment variable: name, description, required, default. If the variable is set to required, and no default value is provided, the user must set the variable before starting. - -`requiredEnvironments` is not necessary, but a blocklet can use this field to request blocklet users to provide corresponding information through this field. For example, a blocklet that depends on the MongoDB database can use requiredEnvironments to ask users to fill in the MongoDB connection string. - -`capabilities` is used to tell Blocklet Server what the blocklet is capable of, if your blocklet can not serve on dynamic path prefix, please set it as following: - -```json - "capabilities": { - "dynamicPathPrefix": false - } +#### header and footer show different information + +```yml +navigation: +- title: a # appears in the header (default) +- title: c +section: footer # only in footer +- title: d +section: # both in header and footer + - header + - footer +- title: e +section: social # in footer's social media +- title: f +section: bottom # at the bottom of the footer ``` -## Other configuration +#### show icon -```json -{ - "provider": "arcblock|community", - "public_url": "public page url, should at least specify one", - "admin_url": "administrator page url, default to empty", - "config_url": "configuration page url, default to empty", - "doc_url": "public document url, if not specified, will use store detail page" -} +```yml +navigation: +- title: a +icon: mdi:home # iconify style +- title: a +icon: 'https://xxx' # url +- title: b +icon: '/path/to/xxx' # icon serve in app ``` -Here are other configuration items. For a blocklet, these fields are optional. Let’s briefly introduce these fields. - -- provider: The `provider` is the source of the declared blocklet. There are two optional values: arcblock|community. `arcblock` represents the official development of ArcBlock, and the community develops `community`. -- public_url: The `public_url` is the public address of the blocklet. -- admin_url: The `admin_url` is the address of the management end of the Blocklet. -- config_url: The `config_url` is the address of the blocklet configuration page. -- doc_url: The `doc_url` is the document address of the blocklet. If this address does not exist, Blocklet Server will use the README of the blocklet as the document page. - -## Blocklet life cycle - -## Life cycle - -![blocklet lifecycle](./images/blocklet-lifecycle.png) - -In Blocklet Server, the complete life cycle of a blocklet includes four stages: installation (or deployment), start, stop, and uninstall. Blocklets can be installed in two ways: one is to download and install it from the Store, and the other is to deploy and install it directly with Blocklet Server CLI. The CLI is mainly for development and testing. Therefore, in the first phase of the life cycle, there are two installation and deployment situations. - -## Hooks - -![blocklet lifecycle](./images/blocklet-lifecycle-hooks.png) - -In these stages, Blocklet Server provides the hook function, which is used to do something during the execution of the life cycle. Currently includes pre-deploy, post-install, pre-start, pre-stop, pre-install, pre-uninstall hook. - -For example, a blocklet has hardware requirements for the running machine: the memory cannot be lower than 1G, and the available disk capacity cannot be lower than 500 MB. You can use the pre-install hook to check whether the target machine has met the demand. If it meets, install normally, otherwise throw an error message and terminate the installation. - -Hooks are Shell scripts, and these scripts may refer to the files in the blocklet. In the process of packaging the blocklet, the Blocklet Server packaging tool (Blocklet Server CLI) will package the files used by the hook separately, so developers need to declare which files are referenced by hooks in `hookFiles`. - -## Creating a Blocklet +#### show copyright -After understanding some basic Blocklet concepts and protocols, it's time to learn how to create a blocklet. +```yml +copyright: +owner: xxx +year: xxx # If not written, take the current year +``` -## Initialize the blocklet +#### Different backgrounds -Blocklet Server CLI provides `blocklet init` command to help developers quickly create a blocklet project. This command will help developers create related configuration files and directories. +```yml +background: xxx +``` -### Blocklet project structure +or -```shell -├── blocklet.json -├── blocklet.md -└── package.json +```yml +background: +header: xxx +footer: xxx +default: xxx ``` -After the project is created, we can see that a Blocklet project mainly contains two parts: blocklet description information and source code. -Blocklet Server currently only supports the Node.js blocklet projects, so the description of the blocklet will generally contain two parts: Node.js’s package.json and blocklet’s blocklet.json. The content of the blocklet spec we mentioned earlier is in blocklet.json. Of course, blocklet also allow the contents of blocklet.json to be placed in the `blocklet` field of package.json. - -### blocklet.json - -All description information of the blocklet is placed in the blocklet.json file. -As stated earlier, a blocklet is a Node.js project. We know that Node.js package.json file also contains information such as name, description, and version. For a blocklet, These fields have the same values, so Blocklet Server will first read the configuration of blocklet.json. If blocklet.json does not have these values, Blocklet Server will use package.json's values. - -The following is an example of blocklet.json. - -```json -{ - "name": "static-demo-blocklet", - "description": "Demo blocklet that shows how to serve a static html5 game with Blocklet Server", - "version": "1.0.0", - "group": "static", - "color": "primary", - "main": "app/", - "provider": "arcblock", - "requiredEnvironments": { - "name": "DEBUG", - "description": "Enable test flag", - "required": false, - "default": "arcblock*" - }, - "capabilities": { - "dynamicPathPrefix": true - } -} +## Configure Children Source +```yml +children: + - name: c1 + mountPoint: /c1 + + # source has two types + + # 1. url: equivalent to the previous resolved, can be any bundle url, no need to serve in the store, such as +# can serve in a github release, or in a local disk + source: + url: +- https://store.blocklet.dev/api/blocklets/z8ia4e5vAeDsQEE2P26bQqz9oWR1Lxg9qUMaV/blocklet.json +- file:///Users/wangshijun/Develop/arcblock/nft-store/.blocklet/release/blocklet.json + - name: c2 + mountPoint: /c2 + # 2. The bundle served in the store can control the version: you can specify the latest version (default) or a fixed version. Later, if necessary, it can support more forms `^x.x.x`, `~x.x.x`, etc. + # Because the store is decentralized, you need to specify the store + source: + store: https://store.blocklet.dev + name: static-demo # bundle name + version: latest # latest, 1.3.0 + - name: c3 + mountPoint: /c3 + # url can be set to one or more, when the first url is abnormal, it can be downgraded to the following url + source: + url: + -