Skip to content

Commit 6dae80b

Browse files
juzhiyuanjohzchen
juzhiyuan
and
johzchen
authored
feat(docs): improve README & Deploy (#785)
* feat(doc): update README & deploy * feat(docs): added FAQ * fix: linkx * feat(docs): update deploy with docker * feat(docs): update FAQ * feat: update README * feat: update README * feta: update README * fix: link * feat: update deploy with docker * feat(docs): added tip for some users * feat(doc): improve deploy with docker * feat(docs): improve deploy with docker * feat(doc): update run with docker * feat(doc): improve deploy * feat(doc): added more info * feat(doc): added more info * feat(doc): remove extra info * feat: added more detailed * fix: CI fail according `api/conf/conf.yaml ` is changed. * fix: revert changed * feat(docs): improve English version * feat(docs): use frontend instead, just like backend * feat(docs): remove extra statements * feat(docs): update typo * feat(docs): remove startup with message * feat: update CI's name Co-authored-by: nic-chen <[email protected]>
1 parent a539f48 commit 6dae80b

16 files changed

+399
-479
lines changed

‎.github/workflows/frontend-e2e-test.yml

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Front-end e2e test
1+
name: Frontend e2e test
22

33
on:
44
push:
@@ -14,7 +14,7 @@ defaults:
1414

1515
jobs:
1616
web-e2e:
17-
name: Front-end e2e test
17+
name: Frontend e2e test
1818
runs-on: ubuntu-latest
1919
steps:
2020
- name: Checkout
@@ -36,5 +36,5 @@ jobs:
3636
if: steps.node_modules_cache_id.outputs.cache-hit != 'true'
3737
run: yarn install
3838

39-
- name: Start Front-end then test
39+
- name: Start frontend then test
4040
run: yarn test:e2e

‎CHANGELOG.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -29,18 +29,18 @@ This is a release candidate.
2929

3030
# Core
3131

32-
- Refactor front-end with Admin-API.
32+
- Refactor frontend with Admin-API.
3333
- Manager-API removes dependency on MySQL.
3434
- Support plugin orchestration.
35-
- Setting standards for front-end internationalization.
35+
- Setting standards for frontend internationalization.
3636
- New deployment pattern.
3737
- Add more test cases.
3838
- Document Enhancement.
3939
- Add back-end E2E test examples.
4040
- Improve CI testing.
4141
- Support log save to local file.
4242
- Optimize the deployment process.
43-
- Add E2E test examples to the front-end. [#619](https://github.com/apache/apisix-dashboard/pull/619)
43+
- Add E2E test examples to the frontend. [#619](https://github.com/apache/apisix-dashboard/pull/619)
4444
- Fix the Promethues plugin updating incorrect values when updating routes. [#666](https://github.com/apache/apisix-dashboard/pull/666)
4545
- Fix page display exceptions when the Redirect option is selected as Enable HTTPS in the Route page. [#692](https://github.com/apache/apisix-dashboard/pull/692)
4646

‎README.md

+36-62
Original file line numberDiff line numberDiff line change
@@ -21,90 +21,64 @@ English | [简体中文](./README.zh-CN.md)
2121

2222
# Apache APISIX Dashboard
2323

24-
Apache APISIX Dashboard for [Apache APISIX](https://github.com/apache/apisix)
24+
## What's Apache APISIX Dashboard
2525

26-
The goal of Apache APISIX Dashboard project is to let users to quickly experience and learn Apache APISIX, but it still cannot be used directly in a production environment.
26+
The Apache APISIX Dashboard is designed to make it as easy as possible for users to operate [Apache APISIX](https://github.com/apache/apisix) through a frontend interface.
2727

28-
Its function is always a subset of Apache APISIX, and may lag behind the rapid iteration of Apache APISIX.
28+
The Dashboard is the control plane and performs all parameter checks; Apache APISIX mixes data and control planes and will evolve to a pure data plane.
2929

30-
If you need to use the Apache APISIX Dashboard project in a production system, you need to enhance user permissions, communication security, high availability and other advanced features.
30+
This project includes `manager-api`, which will gradually replace `admin-api` in Apache APISIX.
3131

32-
## Installation
32+
Note: Currently the Dashboard does not have complete coverage of Apache APISIX features, [visit here](https://github.com/apache/apisix-dashboard/milestones) to view the milestones.
3333

34-
Support multiple ways to install Apache APISIX Dashboard
34+
![architecture](./docs/images/architecture.png)
3535

36-
### Docker
36+
## Project structure
3737

38-
Start a runnable version by the following method
39-
40-
- [Deploy With Docker](./docs/deploy-with-docker.md)
41-
42-
### Build from Source Code
43-
44-
To build Apache APISIX Dashboard from source code, first make sure that your `golang` version is 1.13 or greater.
45-
46-
Also you need to make sure that `Node.js` and `yarn` are installed.
47-
48-
```sh
49-
$ git clone -b v2.0 https://github.com/apache/apisix-dashboard.git
50-
$ cd apisix-dashboard
51-
$ make build
5238
```
53-
54-
Then you can find all files (configuration files, executable files, web static resources) needed to run Apache APISIX Dashboard in the `./output` directory.
55-
56-
Start by the following commands.
57-
58-
```sh
59-
$ cd ./output
60-
$ exec ./manager-api
39+
.
40+
├── CHANGELOG.md
41+
├── CHANGELOG.zh-CN.md
42+
├── CODE_OF_CONDUCT.md
43+
├── CONTRIBUTING.md
44+
├── Dockerfile
45+
├── LICENSE
46+
├── Makefile
47+
├── NOTICE
48+
├── README.md
49+
├── README.zh-CN.md
50+
├── api
51+
├── docs
52+
├── licenses
53+
└── web
6154
```
6255

63-
`makefile` provides the following commands.
56+
1. The `api` directory is used to store the `manager-api` source codes, which is used to manage `etcd` and provide APIs to the frontend interface.
57+
2. The `web` directory is used to store the frontend source codes.
6458

65-
```text
66-
Makefile rules:
59+
## Build then launch
6760

68-
help: Show Makefile rules
69-
build: Build Apache APISIX Dashboard, it contains web and manager-api
70-
api-test: Run the tests of manager-api
71-
api-run: Run the manager-api
72-
api-stop: stop manager-api
73-
go-lint: Lint Go source code
74-
license-check: Check Apache APISIX Dashboard Source Codes for Apache License
75-
```
61+
Support the following ways currently.
7662

77-
For more detailed construction steps, see - [Build from Source Codes](./docs/deploy.md)
63+
- [Source Codes](./docs/deploy.md)
64+
- [Docker](./docs/deploy-with-docker.md)
7865

79-
### For developer
66+
## Development
8067

81-
Apache APISIX Dashboard provides a management interface for [Apache APISIX](https://github.com/apache/apisix), you need to [install APISIX first](https://github.com/apache/apisix#configure-and-installation).
68+
Please refer to the [Development Guide](./docs/develop.md).
8269

83-
Please refer to here to start `manager-api` and `web`respectively.
70+
## User Guide
8471

85-
- [Develop Apache APISIX Dashboard](./docs/develop.md)
86-
87-
## User guide
88-
89-
Please refer to [User Guide](./docs/USER_GUIDE.md)
90-
91-
## Milestones
92-
93-
- [2.0](https://github.com/apache/apisix-dashboard/milestone/4)
94-
- [2.1](https://github.com/apache/apisix-dashboard/milestone/5)
72+
Please refer to the [User Guide](./docs/USER_GUIDE.md).
9573

9674
## Contributing
9775

98-
See [CONTRIBUTING](./CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
99-
100-
## License
101-
102-
Apache License 2.0, [LICENSE](https://github.com/apache/apisix-dashboard/blob/master/LICENSE)
76+
Please refer to the [Contribution Guide](./CONTRIBUTING.md) for a more detailed infomation.
10377

10478
## FAQ
10579

106-
1. If you need the Apache APISIX Dashboard 1.0 which is built with Vue.js, please refer to [master-vue](https://github.com/apache/apisix-dashboard/tree/master-vue).
80+
Please refer to the [FAQ](./docs/FAQ.md) for more known issues.
10781

108-
2. The Apache APISIX Dashboard 2.0 removes MySQL which [Apache APISIX Dashboard 1.5](https://github.com/apache/apisix-dashboard/tree/backup-1.5-latest) is relied on.
82+
## License
10983

110-
3. If you are using APISIX 1.5 or below, kindly note that the v2 api store and v3 api store are [separate and isolated](https://etcd.io/docs/v3.4.0/op-guide/v2-migration/). Apache APISIX Dashboard v2.0 and above use the etcd v3 api, APISIX 1.5 and below use the etcd v2 api.
84+
[Apache License 2.0](./LICENSE)

‎README.zh-CN.md

+36-58
Original file line numberDiff line numberDiff line change
@@ -21,86 +21,64 @@
2121

2222
# Apache APISIX Dashboard
2323

24-
Apache APISIX Dashboard 项目的目标是为了让大家快速上手体验和学习 Apache APISIX，并不能直接用于生产环境。
24+
## 介绍
2525

26-
它的功能永远都是 Apache APISIX 的子集，也可能会滞后于 Apache APISIX 的快速迭代。
26+
Apache APISIX Dashboard 旨在通过前端界面，让用户尽可能更方便地操作 [Apache APISIX](https://github.com/apache/apisix)。
2727

28-
如果你需要把 Apache APISIX Dashboard 项目用于生产系统，需要对用户权限、通讯安全、高可用、高级功能等方面做增强。
28+
Dashboard 为控制平面，完成所有参数的校验；Apache APISIX 混合了数据平面与控制平面，会逐渐演进为纯粹的数据平面。
2929

30-
## 安装
30+
本项目包含了 `manager-api` 与前端界面，前者将逐渐替代 Apache APISIX 中的 `admin-api`，我们正在积极地迁移相关逻辑。
3131

32-
提供多种方式来安装 Apache APISIX Dashboard
32+
注意：目前 Dashboard 尚未完整覆盖 Apache APISIX 的功能，[访问此处](https://github.com/apache/apisix-dashboard/milestones)以查看里程碑。
3333

34-
### Docker
34+
![architecture](./docs/images/architecture.png)
3535

36-
通过下面的方法来启动一个可运行的版本
36+
## 目录结构
3737

38-
- [使用 Docker 一键部署](./docs/deploy-with-docker.zh-CN.md)
39-
40-
### 从源代码构建
41-
42-
从源代码构建，首先先确认你的 `golang` 版本在 1.13 或者 更高的版本。
43-
44-
同样你也需要提前安装好 `Node.js` 和 `yarn`。
45-
46-
```sh
47-
$ git clone -b v2.0 https://github.com/apache/apisix-dashboard.git
48-
$ cd apisix-dashboard
49-
$ make build
5038
```
51-
52-
然后你可以在 `./output` 目录下找到运行 Apache APISIX Dashboard 需要的所有文件(配置文件、可执行文件、web静态资源)
53-
54-
通过下面的命令启动
55-
56-
```sh
57-
$ cd ./output
58-
$ exec ./manager-api
39+
.
40+
├── CHANGELOG.md
41+
├── CHANGELOG.zh-CN.md
42+
├── CODE_OF_CONDUCT.md
43+
├── CONTRIBUTING.md
44+
├── Dockerfile
45+
├── LICENSE
46+
├── Makefile
47+
├── NOTICE
48+
├── README.md
49+
├── README.zh-CN.md
50+
├── api
51+
├── docs
52+
├── licenses
53+
└── web
5954
```
6055

61-
`makefile` 提供以下几种命令
56+
1. `api` 目录用于存放 `manager-api` 源码，它用于管理 `etcd` 并为前端界面提供接口。
57+
2. `web` 目录用于存放前端源码。
6258

63-
```text
64-
Makefile rules:
59+
## 构建并启动
6560

66-
help: Show Makefile rules
67-
build: Build Apache APISIX Dashboard, it contains web and manager-api
68-
api-test: Run the tests of manager-api
69-
api-run: Run the manager-api
70-
api-stop: stop manager-api
71-
go-lint: Lint Go source code
72-
license-check: Check Apache APISIX Dashboard Source Codes for Apache License
73-
```
74-
75-
更详细的构建步骤参见这里 - [从源代码构建](./docs/deploy.zh-CN.md)
61+
支持以下方式：
7662

77-
### 对于开发者
63+
- [源码](./docs/deploy.zh-CN.md)
64+
- [Docker](./docs/deploy-with-docker.zh-CN.md)
7865

79-
Apache APISIX Dashboard 为 [Apache APISIX](https://github.com/apache/apisix) 提供管理界面，需要先[安装 APISIX](https://github.com/apache/apisix#configure-and-installation).
66+
## 本地开发
8067

81-
然后请参考这里分别启动 `manager-api` 和 `web`
82-
83-
- [开发 Apache APISIX Dashboard](./docs/develop.zh-CN.md)
68+
请参考[开发指南](./docs/develop.zh-CN.md)
8469

8570
## 使用指南
8671

87-
请参考 [用户指南](./docs/USER_GUIDE.zh-CN.md)
72+
请参考[用户指南](./docs/USER_GUIDE.zh-CN.md)
8873

89-
## 里程碑
74+
## 参与贡献
9075

91-
- [2.0](https://github.com/apache/apisix-dashboard/milestone/4)
92-
- [2.1](https://github.com/apache/apisix-dashboard/milestone/5)
76+
请参考[贡献指南](./CONTRIBUTING.md)以获取更详细的流程
9377

94-
## 贡献
78+
## FAQ
9579

96-
请参考[贡献指南](./CONTRIBUTING.md)以获取更详细的流程。
80+
请参考 [FAQ 汇总](./docs/FAQ.zh-CN.md)以查看更多已知问题
9781

9882
## License
9983

100-
Apache License 2.0, [LICENSE](https://github.com/apache/apisix-dashboard/blob/master/LICENSE)
101-
102-
## FAQ
103-
104-
1. 如果你需要 Vue.js 构建的 Apache APISIX Dashboard 1.0，请使用 [master-vue 分支](https://github.com/apache/apisix-dashboard/tree/master-vue)。
105-
2. 2.0 版本的控制台移除了[1.5 版本](https://github.com/apache/apisix-dashboard/tree/backup-1.5-latest)中的 MySQL，将直接操作 etcd。
106-
3. 如果你使用 v2.0 以下版本的 Apache APISIX，需要注意 etcd v2 API 的数据与 v3 API 的数据是[不互通的](https://etcd.io/docs/v3.4.0/op-guide/v2-migration/)。Apache APISIX Dashboard v2.0 及以上版本使用 etcd v3 API，apisix 1.5 及以下版本使用 etcd v2 API。
84+
[Apache License 2.0](./LICENSE)

‎api/conf/conf.yaml

+13-11
Original file line numberDiff line numberDiff line change
@@ -17,23 +17,25 @@
1717

1818
conf:
1919
listen:
20-
host: 127.0.0.1 # `manager api` listening ip or host name
21-
port: 8080 # `manager api` listening port
20+
host: 127.0.0.1 # `manager api` listening ip or host name
21+
port: 8080 # `manager api` listening port
2222
etcd:
23-
endpoints: # supports defining multiple etcd host addresses for an etcd cluster
23+
endpoints: # supports defining multiple etcd host addresses for an etcd cluster
2424
- 127.0.0.1:2379
2525
log:
2626
error_log:
27-
level: warn # supports levels, lower to higher: debug, info, warn, error, panic, fatal
28-
file_path: logs/error.log # supports relative path, absolute path, standard output
29-
# such as: logs/error.log, /tmp/logs/error.log, /dev/stdout, /dev/stderr
27+
level: warn # supports levels, lower to higher: debug, info, warn, error, panic, fatal
28+
file_path:
29+
logs/error.log # supports relative path, absolute path, standard output
30+
# such as: logs/error.log, /tmp/logs/error.log, /dev/stdout, /dev/stderr
3031
authentication:
31-
secret: secret # secret for jwt token generation.
32-
# *NOTE*: Highly recommended to modify this value to protect `manager api`.
33-
# if it's default value, when `manager api` start , it will generate a random string to replace it.
34-
expire_time: 3600 # jwt token expire time, in second
32+
secret:
33+
secret # secret for jwt token generation.
34+
# NOTE: Highly recommended to modify this value to protect `manager api`.
35+
# if it's default value, when `manager api` start , it will generate a random string to replace it.
36+
expire_time: 3600 # jwt token expire time, in second
3537
users:
36-
- username: admin # username and password for login `manager api`
38+
- username: admin # username and password for login `manager api`
3739
password: admin
3840
- username: user
3941
password: user

‎docs/FAQ.md

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
<!--
2+
#
3+
# Licensed to the Apache Software Foundation (ASF) under one or more
4+
# contributor license agreements. See the NOTICE file distributed with
5+
# this work for additional information regarding copyright ownership.
6+
# The ASF licenses this file to You under the Apache License, Version 2.0
7+
# (the "License"); you may not use this file except in compliance with
8+
# the License. You may obtain a copy of the License at
9+
#
10+
# http://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# Unless required by applicable law or agreed to in writing, software
13+
# distributed under the License is distributed on an "AS IS" BASIS,
14+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
# See the License for the specific language governing permissions and
16+
# limitations under the License.
17+
#
18+
-->
19+
20+
# FAQ
21+
22+
### 1. Vue.js version of the Dashboard
23+
24+
If you need a Vue.js build of the Apache APISIX Dashboard 1.0, use the [master-vue branch](https://github.com/apache/apisix-dashboard/tree/master-vue).
25+
26+
### What are the differences between Dashboard version 2.0 and version 1.5?
27+
28+
The 2.0 version of the dashboard removed MySQL from [version 1.5](https://github.com/apache/apisix-dashboard/tree/backup-1.5-latest) and will operate directly on etcd.
29+
30+
### 3. Etcd compatibility issues
31+
32+
If you are using Apache APISIX below v2.0, be aware that the data from the etcd v2 API is [not compatible](https://etcd.io/docs/v3.4.0/op-guide/v2-migration/) with the data from the v3 API. Apache APISIX Dashboard v2.0 and above uses the etcd v3 API, and apisix 1.5 and below uses the etcd v2 API.
33+
34+
### 4. After modifying the plugin schema or creating a custom plugin in Apache APISIX, why can't I find it on the dashboard?
35+
36+
Since the Dashboard caches the jsonschema data of the plugins in Apache APISIX, you need to synchronize the data in the Dashboard after you create your custom plugins in Apache APISIX, which currently **only supports manual operation**, this issue will be optimized in the following versions. Please follow the following guide.
37+
38+
1. Install [Lua](https://www.lua.org/download.html) and `zip`.
39+
40+
2. Execute the following commands.
41+
42+
```sh
43+
# `$version` is the version number of Apache APISIX, e.g. master or 2.0.
44+
$ api/build-tools/schema-sync.sh $version
45+
```
46+
47+
If you have a custom plugin, make sure it is in the `apisix` directory and use the following command.
48+
49+
```sh
50+
$ api/build-tools/schema-sync.sh /path/to/apisix
51+
52+
# e.g
53+
$ api/build-tools/schema-sync.sh /usr/local/apisix
54+
```
55+
56+
After the command finishes executing, if you are using a binary `manager-api` that has already been built, you will need to manually copy `api/conf/schema.json` to the `conf` directory under the Dashboard **working directory**. where **working directory** refers to the `conf` directory under this [document](./deploy.md) is the `output` directory, or the directory with the modified name, that is generated in the root directory after the build is complete.

0 commit comments

Comments
 (0)