docs:Add installation documentation.

quanxiang-cloud · Nov 12, 2021 · 0eefbeb · 0eefbeb
1 parent 1986813
commit 0eefbeb
Show file tree

Hide file tree

Showing 4 changed files with 323 additions and 126 deletions.
diff --git a/README.md b/README.md
@@ -11,14 +11,16 @@
  QuanXiang cloud is a powerful, pluggable open source low-code platform.
 </p>
 
+[中文](./README_zh.md)
+
 # Introduction
 
+QuanxiangCloud is a powerful, pluggable open source low-code platform, which can help to quckly 
 
 # Getting Started
 
-Comming soon
+[Deploy QuanxiangCloud](./doc/install.md) [中文](./doc/install_zh.md)
 
 # Contributing
 
-
-Comming soon
+Coming soon
diff --git a/README_zh.md b/README_zh.md
@@ -1,48 +1,56 @@
-# 概述
-全象云低代码平台是一个基于云原生的、完全容器化的工具和平台，用于辅助构建企业各类数字化应用。作为一个集低代码开发能力、 身份认证能力、容器 DevOps 能力于一体的多应用集成和管理平台，全象云平台能够支持快速构建应用、便捷维护管理应用、企业存量业务与全象云构建业务的集成。
+<p align="center">
 
-全象云平台的能力归纳为为四类：应用开发能力、API 管理能力、系统连接能力以及生态共创能力。
+  <a href="https://docs.clouden.io" target="blank"><img src="https://qxp-public.pek3b.qingstor.com/qxp_vertical_logo.svg" width="300" alt="Quanxiang Cloud Logo" /></a>
 
-- **应用开发能力：** 平台提供云上无代码和低代码两种应用开发模式，屏蔽了技术的复杂度。作为通用的低代码工具，既可以可视化构建简单的表单应用、自动化应用，也可以自定义外部或移动端应用，还可以用于生成专用的低代码平台。
-- **API管理能力：** 平台实现了对外部 API 进行代理，使得在应用开发时能够像使用本地数据源一样，使用或组合使用外部数据源。
-- **系统连接能力：** 平台提供丰富的开发接口和强大的插件机制，实现与外部独立的系统进行通信或集成，进而构建更复杂的应用；多个集成到全象云平台的系统能够相互连接，使用彼此的功能。
-- **生态共创能力：** 平台支持多个层级的对接，包括对接应用市场、组件市场、接口市场等。
+</p>
 
-除此之外，全象云平台还为前端和移动端开发工程师提供了丰富的自定义功能，包括组件、页面、应用模板级别的自定义，以及为后端开发工程师提供了 FaaS 能力，结合 API 编排能力。
+<p align="center">
+
+  <br/>
+
+  <a href="https://docs.clouden.io" target="blank">
+    QuanXiang
+
+  </a>
+
+</p>
+
+<p align="center">
 
-# 安装
-全象云低代码平台现阶段仅支持在K8S上进行部署，我们提供了多种部署方式，分别用于开发测试环境和生产环境。
+ QuanXiang cloud is a powerful, pluggable open source low-code platform.
 
-## 必要条件
+</p>
 
-在安装前需要提前准备好Kubernetes，并在运行脚本的主机上安装并配置好kubectl的运行环境。（目前我们仅在qingcloud的QKE环境下验证过我们的脚本，Kubernetes的原生环境后续我们会做进一步验证。）
+**# 概述**
 
-## 环境要求
+全象云低代码平台是一个基于云原生的、完全容器化的工具和平台，用于辅助构建企业各类数字化应用。作为一个集低代码开发能力、 身份认证能力、容器 DevOps 能力于一体的多应用集成和管理平台，全象云平台能够支持快速构建应用、便捷维护管理应用、企业存量业务与全象云构建业务的集成。
+
+全象云平台的能力归纳为为四类：应用开发能力、API 管理能力、系统连接能力以及生态共创能力。
+
+- ***应用开发能力：*** 平台提供云上无代码和低代码两种应用开发模式，屏蔽了技术的复杂度。作为通用的低代码工具，既可以可视化构建简单的表单应用、自动化应用，也可以自定义外部或移动端应用，还可以用于生成专用的低代码平台。
 
-为了保证您的环境能够正常的运行，我们建议您至少有3个Kubernetes的工作节点，我们推荐使用青云的QKE的预生产类型，如果自建需要保证至少每个节点系统配置如下:
+- ***API管理能力：*** 平台实现了对外部 API 进行代理，使得在应用开发时能够像使用本地数据源一样，使用或组合使用外部数据源。
 
-```
-CPU: 4
-Memory: 8G
-Disk: 200GB
-```
+- ***系统连接能力：*** 平台提供丰富的开发接口和强大的插件机制，实现与外部独立的系统进行通信或集成，进而构建更复杂的应用；多个集成到全象云平台的系统能够相互连接，使用彼此的功能。
 
+- ***生态共创能力：*** 平台支持多个层级的对接，包括对接应用市场、组件市场、接口市场等。
 
-**开发环境：**
-我们为您提供了一键部署脚本，此脚本仅供开发测试环境使用，命令如下：
+除此之外，全象云平台还为前端和移动端开发工程师提供了丰富的自定义功能，包括组件、页面、应用模板级别的自定义，以及为后端开发工程师提供了 FaaS 能力，结合 API 编排能力。
+
+# 快速开始
 
-```
-# ./install.sh
-```
+全象云低代码平台现阶段仅提供在K8S上进行部署，现阶段仅提供KubeSphere发行版上的安装部署，后续会提供更多K8S的发行版支持。
 
-**生产环境：**
+## 安装
 
-Comming soon.
+[一键安装全象低代码平台](./doc/install_zh.md)
 
-# 功能列表：
+# 功能列表
 
 - 表单引擎
+
 - 数据模型
+
 - API代理
-- 工作流
 
+- 工作流
diff --git a/doc/install.md b/doc/install.md
@@ -1,60 +1,147 @@
-# Quanxiang platform installation
-quanxiang project is a holographic platform installation tool written in go language, which can run on various architecture machines
-## Prerequisites for using this installer
+# Getting Started
 
-* helm3 needs to be installed on the deployment machine
-* kubectl needs to be installed on the deployment machine
-* go needs to be installed on the deployment machine
-## Feature
+## Overview
 
-* Support the optional deployment of middleware services (if you already have ready-made middleware available, you can set the middleware to false in the configuration file configs / configs.yml)
-* Support the compilation and use of various architecture machines
+QuanxiangCloud privode a deployment tool, which can help user to quckly deploy QuanxiangCloud low-code platform with a single line of command . Quangxiang deployment tool support most of popular K8S release: 
 
-## Installation steps
- >（1）Generate executable：
-```shell
-    git clone git@github.com:quanxiang-cloud/quanxiang.git
-    git checkout master
-    cd quanxiang
-    CGO_ENABLED=0 GOOS=darwin/linux/windows/freebsd GOARCH=amd64/arm/386 go build -o quanxiangApp main.go
-````
- >（2）Modify profile
+- [Deploy QuanxiangCloud on KubeShpere](#Deploy QuanxiangCloud on KubeShpere(recommend))
+- [Deploy QuanxiangCloud on Kubernetes](#Deploy QuanxiangCloud on Kubernetes)
 
-`vi configs/configs.yml`
-Set the middleware password and configure the service configuration information. Refer to the notes in the configuration file for details
- >（3）Deploy：
+## Prerequisites 
 
-`./installAppMac start -k  -c -d  -i -H -P -u -p -n`
+* Kubernetes cluster environment 
 
-Parameter description：
+## Deploy QuanxiangCloud on KubeShpere(recommend)
 
-| parameter | purpose |Description  |
-------------|---------|--------------
-| -c/--configfile | relative or absolute path of the configuration file  |Indicates the absolute or relative path of the current project configs / configs.yml |
-| -d/--deploymentFile | absolute or relative path of deployment folder | absolute or relative path to the current project deployment folder  |
-| -k/--kubeconfig |the profile path than can access to k8s cluster  | If the file is in the default location ~ /. Kube / config, you can not specify this parameter |
-| -i/--middlerwareInit | middleware initialization | If specified, perform middleware initialization |
-| -n/--namespace | The namespace in which the service is deployed in the k8s cluster | If not specified, the default namespace is default |
+### Deploy KubeSphere
+
+There are two ways to deploy KubeSphere: 
+
+- Deploy KubeSphere manully, refer [office documentation](!https://kubesphere.io/docs/) for more details.
+- Using  [KubeSphere(R)（QKE） ](https://docsv3.qingcloud.com/container/qke/)(recommend) to deploy  KubeShere cluster, which is high availability and support automatic inspection and repair. 
+
+ KubeSphere cluster requirments:
+
+| Node Type | quantity | Resource Requirment                    |
+| --------- | -------- | -------------------------------------- |
+| Master    | 1        | CPU: 4 core, Memory: 8 GB, Disk: 80 GB |
+| Worker    | 5        | CPU: 4 core, Memory: 8 GB, Disk: 80 GB |
+
+>**Notice**
+>
+>Scale nodes' resources to double and use PaaS that privode by cloud vendors, if you want to use QuanxiangCloud as production.
+
+### QuanxiangCloud installation
+
+#### Prerequisite
+
+Before deploying QuanxingCloud,  below options are required in local environment:
+
+- Accessible KubeSphere cluster 
+- 'kubectl' is installed on local. refer [kubectl installation](!https://kubernetes.io/docs/tasks/tools/) to install kubectl.
+- Kubeconfig is configured. refer below steps to configure kubeconfig
+  - Get QKE kubeconfig from QingCloud console.
+  - For KubeSphere kubeconfig, refer to [documentation](!https://kubesphere.com.cn/docs/) or ask [community](!https://github.com/kubesphere) for more help.
+
+- Helm3 is required. refer [helm3 installation](!https://helm.sh/docs/intro/install/) to install helm3.
+
+#### Download release
+
+You can download the  [release](!https://github.com/quanxiang-cloud/quanxiang/releases)  version directly.    **QuanxiangCloud privode various architecture package.**
+
+#### Build from source code
+
+To build QianxiangCloud deployment tool, that golang 1.16 is needed and special correct GOOS, GOARCH. Example  command with Linux and amd64.
+
+```bash
+ git clone https://github.com/quanxiang-cloud/quanxiang.git
+ cd quanxiang
+ git checkout master
+ CGO_ENABLED=0 GOOS=linux GOARCH=adm64 go build -o installApp main.go
+```
+
+> Notice
+>
+> - GOOS: darwin, Linux, Windows, FreeBSD etc.
+> - GOARCH: amd64, 386, arm etc.
+
+#### Deploy QuanxiangCloud
 
- > (4)Undeploy
+QuanxiangCloud deployment tool support production and demo:
+
+- For production,  database, cache,  message etc. should be installed, refer [configurations](#Configurations) for more details.
+- For demo, all services will be deployed in Kubernetes.
+
+###### Configurations
+
+For production,  you cat set  `enable`  to `false` to disable middle services in configuration file `configs/configs.yml` . refer to notes in configuration file for more details. 
+
+```bash
+ vim configs/configs.yml
+    #Middleware Services 中间件服务
+    mysql:
+      enabled: true
+      rootPassword: qxp1234     #It is required to set the root user password if enabled equal to true    设置root用户密码 enabled为true时必填
+    redis:
+      enabled: true
+      password: cXhwMTIzNA==    #The password here is the base64 code of the password. For example, the base64 code of qxp1234 is cxhwmjm0cg==  这里的password为密码的base64编码，比如qxp1234的base64编码为cXhwMjM0Cg==
+    kafka:
+              .....
+```
+
+###### Installation
+
+Run  `installApp`  to install the trial version:
+
+```
+./installApp start -k ~/.kube/config  -i -n lowcode
+```
+
+Parameters description:
+
+| parameter            | purpose                                                      | Description                                                  |
+| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| -c/--configfile      | relative or absolute path of the configuration file          | Indicates the absolute or relative path of the current project configs / configs.yml |
+| -d/--deploymentFile  | absolute or relative path of deployment folder               | absolute or relative path to the current project deployment folder |
+| -k/--kubeconfig      | the profile path than can access to k8s cluster              | If the file is in the default location ~ /. Kube / config, you can not specify this parameter |
+| -i/--middlerwareInit | middleware initialization                                    | If specified, perform middleware initialization              |
+| -n/--namespace       | The namespace in which the service is deployed in the k8s cluster | If not specified, the default namespace is default           |
+
+###### Uninstall
+
+```
+./installApp uninstall -k ~/.kube/config -n lowcode
+```
+
+Parameters description:
 
-`./installAppMac uninstall -n specify the namespace of the k8s cluster`
 | parameter | purpose |Description  |
 -------|------|----------
 | -d/--deploymentFile | The path to the deployment folder  | Absolute or relative path to the current project deployment folder  |
 | -k/--kubeconfig | the profile path than can access to k8s cluster  | If the file is in the default location ~ /. Kube / config, you can not specify this parameter |
 | -n/--namespace | The namespace in which the service is deployed in the k8s cluster | If not specified, the default namespace is default |
 | -u/--uninstallMiddlerware | Do you need to uninstall the middleware deployed by the tool | If there is no middleware deployed using this tool, you can not add this parameter. When the middleware is loaded and unloaded, it will be reported that there is no such resource and can be ignored |
 
- > (5)Configure gateway
+#### How to access
+
+###### Configure gateway
+
+Refer [KubeSphere official documentation](https://kubesphere.io/docs/project-administration/project-gateway/) to configure gateway. LoadBalancer is recommend.
+
+###### Access QuanxiangCloud
+
+To access QuanxiangCloud console,  you should configure your hosts file or add dns records into dns server.  Use default admin user and password `Admin@Admin.com)/654321a..` to login.
+
+Go to http://portal.qxp.com to access QuanxiangCloud administration console. 
+
+Go to http://home.qxp.com to access QuanxiangCloud client console. 
 
-Log in to kubesphere web console as project admin user, enter your project, enter the advanced settings page under project settings from the left navigation bar, and then click Set gateway
+> **Notice**
+>
+> refer [KubeSphere office documentation](https://kubesphere.io/zh/docs/project-user-guide/application-workloads/routes/) to customize the domain *
 
-, select loadbalancer. Before selecting loadbalancer, you must configure the load balancer. The IP address of the load balancer will be bound to the gateway so that internal services and routes can be used
 
-To access, you can use [porterlb](https://github.com/kubesphere/openelb) As load balancer
 
-> (6)Configure access
+### Deploy QuanxiangCloud on Kubernetes
 
-Configure access. If it is an intranet gateway, you need to configure the hosts file on the access host `Gateway IP portal.qxp.com home.qxp.com`
-The browser accesses the above domain name, and the initial user name and password are：`Admin@Admin.com/654321a..
+Coming Soon