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: + - + - ``` - -## Blocklet Environment variables - -The subsequent development work is a normal Web application development. Because blocklets run on Blocklet Server, blocklets depend on the environment of Blocklet Server. Blocklet Server now provides some environment variables for development. - -### Private environment variables - -- BLOCKLET_PORT -- BLOCKLET_APP_DIR -- BLOCKLET_DATA_DIR -- BLOCKLET_LOG_DIR -- BLOCKLET_CACHE_DIR -- BLOCKLET_APP_SK -- BLOCKLET_APP_ID - -## Global environment variables - -- ABT_NODE_DID -- ABT_NODE_PK -- ABT_NODE_URL -- ABT_NODE_DOMAIN -- ABT_NODE_PROTOCOL - -These variables mean what their names indicate. During the development of a blocklet, some values of these variables are environment variables. - -## How to package Blocklet? - -After the blocklet is created, the code needs to be packaged for deployment. The ABT CLI provides the `blocklet bundle` command to package the source code. - -### Test in Blocklet Server - -In the blocklet declaration cycle section, we mentioned the Deploy phase. This phase deploys the packaged project to the local Blocklet Server node to test the blocklet. - -## How to release Blocklet? - -First, publish the developed Blocklet to NPM. The `blocklet bundle` command will put the packaged code in the `.blocklet` directory of the current directory. When publishing or testing, you need to package and release the code in `.blocklet/bundle`. - -Then fork the https://github.com/arcblock/blocklets repository (create Github account first if you don't have one). -Modify the project's registry.yml file and put your blocklet NPM package address in the registry.yml list. Then give a pull request to ArcBlock’s repository: https://github.com/arcblock/blocklets. - -If there are no problems are detected, the PR will be merged into the main branch of the blocklet repository, completing the release. diff --git a/src/developer/blocklet-spec/index.zh.md b/src/developer/blocklet-spec/index.zh.md index 688c872..c781504 100644 --- a/src/developer/blocklet-spec/index.zh.md +++ b/src/developer/blocklet-spec/index.zh.md @@ -1,6 +1,6 @@ --- -title: Blocklet 规范 -description: 'Blocklet 规范' +title: Blocklet 元信息规范 +description: 'Blocklet 元信息配置规范' keywords: 'blocklet server,blocklet,specification' author: zhenqiang category: '' @@ -11,176 +11,230 @@ tags: - specification --- -## 什么是 Blocklet? +> 以下只列出开发者需要关心的配置,完整的文档见 [github.com/blocklet/blocklet-specification](https://github.com/blocklet/blocklet-specification/blob/main/docs/meta.md) + +```yml +did: z8iZrkWYbi3JU3AP9NHJQbBUdrgiRbeorauqf # Blocklet DID +name: example # 人类可读的 Blocklet ID, did 由 name 派生。定义应用名称请使用 title +version: 1.0.0 # Blocklet 版本号 +title: Example APP # 应用名称 +description: App Description # 应用描述 +logo: logo.png # 应用 logo 文件 +files: # 需要将哪些文件打包到 bundle 中 + - logo.png + - screenshots + - hooks +screenshots: # 图片介绍,会展示在 store 的介绍页中 + - 0.png + - 1.png + - 2.png +scripts: # Blocklet hook 指令 + dev: npm run start # 执行 `blocklet dev` 时实际执行的指令 + preInstall: node hooks/pre-install.js # 安装前的 hook + preDeploy: node hooks/pre-deploy.js # 部署前的 hook (以部署方式安装 `blocklet deploy`) + postInstall: node hooks/post-install.js # 安装后的 hook + preStart: node hooks/pre-start.js # 启动前的 hook + preStop: node hooks/pre-stop.js # 停止前的 hook + preUninstall: node hooks/pre-uninstall.js # 删除前的 hook +timeout: + start: 启动超时时间 +payment: # Blocklet 价格 + price: # 可以指定多个币种 + - address: z35n6UoHSi9MED4uaQy6ozFgKPaZj2UKrurBG # token address + value: 8 # 价格 + share: # 分成 + - name: Bob # 账号别名 + address: z1QUDFzp6wKhLFjV4sG1ACY3J3ePcknrviy # 账号 DID + value: 0.7 # 分成比例 + - name: Store # 账号别名 + address: zNKr4EeqcMk4W4TpBYD7MzGj6UEua53vJFx1 # 账号 DID + value: 0.3 # 分成比例 +interfaces: # Blocklet 访问接口( 以下大部分配置不需要关注,只关注 auth 的配置即可 ) + - type: web # 访问接口类型 + services: + - name: auth # 该访问接口的 Auth 服务 + config: + whoCanAccess: all # 谁可以访问 + blockUnauthenticated: false # 是否自动拦截未登录的请求, 并跳转到登录页 + blockUnauthorized: false # 是否自动拦截未授权的请求 + allowSwitchProfile: true # 是否支持切换 Profile + profileFields: # 登录时需要提供的信息 + - fullName + - email + - avatar + ignoreUrls: [] # 哪些接口允许任何请求访问 + protocol: http # 访问接口类型 + name: publicUrl # 通常不需要修改 + port: BLOCKLET_PORT # 接收端口的环境变量 (端口号由 Blocklet Server 生成) + path: / # Bloclet 接收请求时的默认前缀 + prefix: '*' # Blocklet 被挂载的前缀 +environments: # 运行时环境变量 + - name: key # 变量名称 + description: xxxx # 变量描述 + default: '' # 默认值 + required: false # 是否必填 + secure: false # 是否是敏感信息 + shared: true # 是否公开。默认为 true, 当 secure 为 true 时 shared 必为 false +requirements: + server: '>=1.8.0' # server 版本约束 + os: '*' + cpu: '*' + fuels: # 启动前需要的燃料 (token) + endpoint: xxx # 链的地址 + adress: xxx # token address + value: xxx # 价格 + reason: xxx # 需要的原因 ( 比如因为首次启动前需要创建 NFT Factory ) +capabilities: + clusterMode: false # Can blocklet be started in cluster mode + component: true # Can blocklet become a component and be composed by other blocklets +children: # 通常不需要手动维护,通过 `blocklet add/remove` 维护即可 + - name: xxx # 人类可读的 ID (必填) + source: # 安装源 + # 通过 url 安装 + url: xxx + # 通过 store 安装 + store: xxx # store 地址 + name: xxx # Blocklet ID + version: xxx # Blocklet 版本 + mountPoint: /path/to # 挂载点 + title: xxx # 名称 + description: xxx # 描述 +navigation: # 导航信息( 应用地图 ) + - title: xxx 名称 + # 链接到某个 url + link: xxx + # 链接到子组件 + child: xxx # child name or child did + section: # 希望在哪里展示 + - header + - footer + icon: mdi:home # 图标 +theme: # 主题 + background: "#f5f5f5" # 背景色 +copyright: # 版权信息 + owner: Arcblock # 所有者 + year: 2022 # 如不写则取当前年份 -Blocklet 是一种应用协议,同时也是一种软件架构。作为一个协议,它描述了构建 Blocklet Server 平台的方式;作为一个软件架构, 一个独立的 Blocklet 是一个可重用的软件模块,可能是一个 HTTP 服务,也可能是一个函数库等等;当多个 Blocklet 在一起运行时,需要一个平台将它们组合起来,共同构成一个独立的服务,比如 Blocklet Server (Blocklet Server)。 +``` -## 如何定义 Blocklet? +## 配置 Navigation -我们用 JSON 数据格式来描述 Blocklet 的协议。 +比较完整的例子:[Component Demo](https://github.com/blocklet/component-demo/blob/main/blocklet.yml) -## 定义基本信息 +#### 支持 i18n -```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 描述了 Blocklet 的基本信息。其中,group 分为 `dapp` 和 `static` 两种类型。`dapp` 就是常规的 dapp,static 是一中只包含了前端静态资源的 Web 应用,Blocklet Server 内部会用一个 HTTP Server 来 serve `static` Blocklet. - -## 定义运行时设置 +或 -```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: + zh: xxx + en: xxx ``` -除了对 Blocklet 基本信息的描述,Blocklet 还定义了 `main` 这个字段描述 Blocklet 如何开始运行,就是所谓的入口文件的描述。 这个字段和 Blocklet 的运行密切相关。`main` 定义了 dapp 或者 static 类型的 Blocklet 的入口文件或静态资源目录。所以对于 Blocklet Server 来说,`main` 字段是必须的,至关重要,否则 Blocklet Server 没有办法启动 Blocklet. - -除了 main 字段,我们还定义了 `requiredEnvironments` 字段用来声明 Blocklet 运行时需要的环境变量。有 4 个属性描述 1 个环境变量:name, description, required, default. 设置为 required 的变量,并且没有提供默认值时,用户必须在启动前设置该变量。 - -`requiredEnvironments` 不是必须的,Blocklet 需要时可以通过这个字段要求 Blocklet 用户提供相应的信息。比如,Blocklet 依赖 MongoDB 数据库,那么就可以用 requiredEnvironments 来要求用户填写 MongoDB 的连接字符串。 - -`capabilities` 用来告知 Blocklet Server 当前 Blocklet 的能力,比如如果你的 Blocklet 不能运行在任意动态的路由前缀下面,可以如下设置: - -```json - "capabilities": { - "dynamicPathPrefix": false - } +#### header 和 footer 展示不同信息 + +```yml +navigation: + - title: a # 出现在 header 中(默认) + - title: c + section: footer # 只在 footter 中 + - title: d + section: # 既在 header 也在 footer 中 + - header + - footer + - title: e + section: social # 在 footer 的 social media 中 + - title: f + section: bottom # 在 footer 的最下方 ``` -## 其他配置 +#### 展示 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 风格 + - title: a + icon: 'https://xxx' # url + - title: b + icon: '/path/to/xxx' # icon serve 在 app 中 ``` -这里是其他的配置项,对于 Blocklet 来说这些字段是可以选的,我们简单介绍一下这几个字段: - -- provider 是声明 Blocklet 的来源,可选值有两个:arcblock|community. `arcblock` 代表 ArcBlock 官方开发的,`community` 是社区开发的。 -- public_url 是 Blocklet 可公开访问的地址。 -- admin_url 是 Blocklet 管理端地址。 -- config_url 是 Blocklet 配置页面地址。 -- doc_url 是 Blocklet 的文档地址,如果这个地址不存在,Blocklet Server 会使用 Blocklet 的 README 作为文档页面。 - -## Blocklet 生命周期 - -## 生命周期 - -![blocklet lifecycle](./images/blocklet-lifecycle.png) - -在 Blocklet Server 中, Blocklet 完整的生命周期包括 `安装(或部署)、启动、停止、卸载` 这四个阶段。因为可以通过两种方式来安装 Blocklet, 分别是在市场中下载安装,另外一种是直接在本地用 Blocklet Server CLI 部署安装。用 CLI 部署主要是为了开发测试。所以在生命周期的第一阶段中存在安装、部署两种情况。 - -## Hooks - -![blocklet lifecycle](./images/blocklet-lifecycle-hooks.png) - -在在这几个阶段中,Blocklet Server 提供了 hook 功能,用来在执行生命周期的过程中做一些事情。目前包含:`pre-deploy, post-install, pre-start, pre-stop, pre-install, pre-uninstall` 这几个 Hook. - -比如,某个 Blocklet 对于运行的机器有硬件要求:内存不能低于 1G,可用磁盘容量不能低于 500 MB。这个时候就可以利用 pre-install hook 来检测目标机器是否已满足需求,如果满足,正常安装,否则抛出错误消息,并终止安装。 - -hook 其实是一些 Shell 脚本,而这些脚本可能会引用 Blocklet 中的文件,而在打包 Blocklet 的过程中,Blocklet Server 打包工具(Blocklet Server CLI)会将 hook 用到的文件单独打包,所以,开发者需要在 `hookFiles` 中声明哪些文件被 hooks 引用了。 +#### 展示 copyright -## 如何开发 Blocklet? - -在了解了一些基础的 Blocklet 概念和协议后,那么怎么开发一个 Blocklet 呢? +```yml +copyright: + owner: xxx + year: xxx # 如不写则取当前年份 +``` -## 初始化 Blocklet +#### 不同的 background -Blocklet Server CLI 提供了 `blocklet init` 命令来帮助开发者快速创建一个 Blocklet 项目,这个命令会帮助开发者创建相关的配置文件和目录。 +```yml +background: xxx +``` -### 代码结构 +或 -```shell -├── blocklet.json -├── blocklet.md -└── package.json +```yml +background: + header: xxx + footer: xxx + default: xxx ``` -项目创建完成后,我们可以看到一个 Blocklet 项目主要包含两部分:Blocklet 描述信息和源代码。 -Blocklet Server 当前只支持 Node.js 的 Blocklet 项目,所以 Blocklet 的描述信息一般会包含包含两部分:Node.js 的 package.json 和 Blocklet 的 blocklet.json. 我们在前面讲的 Blocklet Spec 的内容会放在 blocklet.json 中。当然,Blocklet 也允许将 blocklet.json 的内容放到 package.json 的 `blocklet` 字段中。 - -### blocklet.json - -Blocklet 所有的描述信息都放在 blocklet.json 文件中。 -前面我们说,Blocklet 是一个 Node.js 项目,我们知道,Node.js 的 package.json 文件中也包含 name, description, version 这些信息。对于 Blocklet 来说,这部分重复的信息是等价的,Blocklet Server 会优先读取 blocklet.json 的配置,如果没有,才会去读取 package.json 中的。 - -如下是 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 - } -} +## 配置 Children Source +```yml +children: + - name: c1 + mountPoint: /c1 + + # source 有两种类型 + + # 1. url: 相当于之前的 resolved, 可以为任意 bundle url, 不需要在 store 中 serve, 比如 + # 可以 serve 在 github release 中,也可以在本地磁盘中 + 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. 在 store 中 serve 的 bundle, 可以控制版本:可指定最新版本(默认)或固定版本。之后若需要可以支持更多形式 `^x.x.x`, `~x.x.x` 等 + # 因为 store 是去中心化的,所以需要指定 store + source: + store: https://store.blocklet.dev + name: static-demo # bundle name + version: latest # latest, 1.3.0 + - name: c3 + mountPoint: /c3 + # url 可以设置一个或多个,当第一个 url 异常时,可降级到后面的url + source: + url: + - + - + - name: c4 + mountPoint: /c4 + # store 可以设置多个,当第一个 store 异常时,可降级到后面的 store + source: + store: + - https://store.blocklet.dev + - https://another-store.blocklet.dev + name: static-demo + version: latest ``` -## Blocklet 环境变量 - -之后的开发工作就是一个普通的 Web 应用开发了。因为 Blocklet 是运行在 Blocklet Server 之中,所以 Blocklet 会依赖于 Blocklet Server 的环境。Blocklet Server 现在提供了一些环境变量供开发使用。 - -### 私有环境变量 - -- BLOCKLET_PORT -- BLOCKLET_APP_DIR -- BLOCKLET_DATA_DIR -- BLOCKLET_LOG_DIR -- BLOCKLET_CACHE_DIR -- BLOCKLET_APP_SK -- BLOCKLET_APP_ID +Demo: [Component Demo](https://github.com/blocklet/component-demo/blob/main/blocklet.yml) -## 全局环境变量 +## 配置 Hooks -- ABT_NODE_DID -- ABT_NODE_PK -- ABT_NODE_URL -- ABT_NODE_DOMAIN -- ABT_NODE_PROTOCOL - -这些变量都是字面意思,在开发 Blocklet 过程中可以从环境变量中读取这变量的些值。 - -## 如何打包 Blocklet? - -Blocklet 开发完成后需要将代码打包才能进行部署,ABT CLI 提供了 `blocklet bundle` 命令来打包源码。 - -### 在 Blocklet Server 中测试 - -在了解 Blocklet 生命周期一节时, 我们提到了部署(Deploy)阶段,这个命令可以将打包好的项目部署到本地 Blocklet Server 中,用来测试 Blocklet。 - -## 如何发布 Blocklet? +![blocklet lifecycle](./images/blocklet-lifecycle-hooks.png) -首先,将开发好的 Blocklet 发布到 NPM。`blocklet bundle` 命令会将打包好的代码放到当前目录的 `.blocklet` 目录中,在发布或者测试时,需要将 `.blocklet/bundle` 中代码打包发布。 +Blocklet Server 提供了 hook 功能用来在执行生命周期的过程中做一些事情。目前包含:`pre-deploy, post-install, pre-start, pre-stop, pre-install, pre-uninstall` 这几个 Hook. -然后分叉 https://github.com/arcblock/blocklets 仓库,(如果没有 Github 账号的话,需要先注册 Github 账号)。修改项目的 registry.yml 文件,将自己的 Blocklet NPM 包地址放到 registry.yml 列表中。然后给 ArcBlock 的仓库: https://github.com/arcblock/blocklets 提一个 Pull Request。 +比如,某个 Blocklet 对于运行的机器有硬件要求:内存不能低于 1G,可用磁盘容量不能低于 500 MB。这个时候就可以利用 pre-install hook 来检测目标机器是否已满足需求,如果满足,正常安装,否则抛出错误消息,并终止安装。 -检查确认没问题后,会将上面创建的 PR 合并到 Blocklet 仓库的主分支,从而完成发布。 +hook 其实是一些 Shell 脚本,而这些脚本可能会引用 Blocklet 中的文件,而在打包 Blocklet 的过程中,Blocklet Server 打包工具(Blocklet Server CLI)会将 hook 用到的文件单独打包,所以,开发者需要在 `hookFiles` 中声明哪些文件被 hooks 引用了。 \ No newline at end of file diff --git a/src/index.md b/src/index.md index 63ab9b3..59bbee1 100644 --- a/src/index.md +++ b/src/index.md @@ -42,9 +42,8 @@ Welcome to Blocklet Server documentation - [Deploy with AWS AMI](./deployment/from-aws-ami) - [Run behind Reverse Proxy](./deployment/behind-reverse-proxy) - [Developer Guide](./developer) - - [Blocklet Server CLI](./developer/blocklet-cli) - [Blocklet CLI](./developer/blocklet-cli) - - [Blocklet Specification](./developer/blocklet-spec) + - [Blocklet Meta Specification](./developer/blocklet-spec) - [Blocklet SDK](./developer/blocklet-sdk) - [Configure Auth Service](./developer/service-auth) - [Send notification to DID Wallet](./developer/service-notification) diff --git a/src/index.zh.md b/src/index.zh.md index e480a7a..b9d74bc 100644 --- a/src/index.zh.md +++ b/src/index.zh.md @@ -37,9 +37,8 @@ tags: - [在 AWS 上部署](./deployment/from-aws-ami) - [运行在反向代理后面](./deployment/behind-reverse-proxy) - [开发者指南](./developer) - - [Blocklet Server CLI 工具](./developer/blocklet-cli) - [Blocklet CLI 工具](./developer/blocklet-cli) - - [Blocklet 规范](./developer/blocklet-spec) + - [Blocklet 元信息规范](./developer/blocklet-spec) - [Blocklet SDK](./developer/blocklet-sdk) - [配置 Auth Service](./developer/service-auth) - [向 DID Wallet 发送消息](./developer/service-notification) diff --git a/version b/version index 844f6a9..d2b13eb 100644 --- a/version +++ b/version @@ -1 +1 @@ -0.6.3 +0.6.4