docs: update CN and EN how-to-build document

apache · Jul 13, 2021 · 651a416 · 651a416
1 parent 59e9b41
commit 651a416
Show file tree

Hide file tree

Showing 4 changed files with 281 additions and 139 deletions.
diff --git a/docs/en/latest/getting-started.md b/docs/en/latest/getting-started.md
@@ -75,7 +75,7 @@ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"
 - We use the [curl](https://curl.se/docs/manpage.html) command for API testing. You can also use other tools such as [Postman](https://www.postman.com/) for testing.
 
 :::note Note
-If you already have Apache APISIX installed, please skip Step 1, and go to [Step 2](getting-started.md#Step-2-Create-a-Route) directly.
+If you already have Apache APISIX installed, please skip Step 1, and go to [Step 2](getting-started.md#step-2-create-a-route) directly.
 :::
 
 ## Step 1: Install Apache APISIX

diff --git a/docs/en/latest/how-to-build.md b/docs/en/latest/how-to-build.md
@@ -21,152 +21,221 @@ title: How to build Apache APISIX
 #
 -->
 
-## 1. Install dependencies
+## Step 1: Install dependencies
 
-The runtime environment for Apache APISIX requires Nginx and etcd.
+The Apache APISIX runtime environment requires dependencies on NGINX and etcd.
 
-So before installation, please follow the different operating systems [install Dependencies](install-dependencies.md).
+Before installing Apache APISIX, please install dependencies according to the operating system you are using. We provide the dependencies installation instructions for **CentOS7**, **Fedora 31 & 32**, **Ubuntu 16.04 & 18.04**, **Debian 9 & 10**, and **MacOS**, please refer to [Install Dependencies](install-dependencies.md) for more details.
 
-The Docker / Helm Chart installation may already contain the required Nginx or etcd.
-Please refer to their own documentations.
+## Step 2: Install Apache APISIX
 
-## 2. Install Apache APISIX
+You can install Apache APISIX via source release packages, RPM package, Docker and Helm Chart. Please choose one from the following options.
 
-You can install Apache APISIX in a variety of ways, including source code packages, Docker, and Helm Chart.
+### Installation via Source Release Package
 
-### Installation via RPM package (CentOS 7)
+1. Create a directory named `apisix-2.7`.
+
+  ```shell
+  mkdir apisix-2.7
+  ```
+
+2. Download Apache APISIX Release source package.
+
+  ```shell
+  wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+  ```
+
+  You can also download the Apache APISIX Release source package from the Apache APISIX website. The [Apache APISIX Official Website - Download Page](https://apisix.apache.org/downloads/) also provides source packages for Apache APISIX, APISIX Dashboard and APISIX Ingress Controller.
+
+3. Unzip the Apache APISIX Release source package.
+
+  ```shell
+  tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+  ```
+
+4. Install the runtime dependent Lua libraries.
+
+  ```shell
+  # Switch to the apisix-2.7 directory
+  cd apisix-2.7
+  # Create dependencies
+  make deps
+  ```
+
+### Installation via RPM Package(CentOS 7)
+
+This installation method is suitable for CentOS 7, please run the following command to install Apache APISIX.
 
 ```shell
 sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
 ```
 
 ### Installation via Docker
 
-See https://hub.docker.com/r/apache/apisix
+Please refer to: [Installing Apache APISIX with Docker](https://hub.docker.com/r/apache/apisix).
 
 ### Installation via Helm Chart
 
-See https://github.com/apache/apisix-helm-chart
+Please refer to: [Installing Apache APISIX with Helm Chart](https://github.com/apache/apisix-helm-chart).
+
+## Step 3: Manage Apache APISIX Server
+
+We can initialize dependencies, start service, and stop service with commands in the Apache APISIX directory, we can also view all commands and their corresponding functions with the `make help` command.
 
-### Installation via source release
+### Initializing Dependencies
 
-You need to download the Apache source release first:
+Run the following command to initialize the NGINX configuration file and etcd.
 
 ```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+# initialize NGINX config file and etcd
+make init
 ```
 
-Install the Lua libraries that the runtime depends on:
+### Start Apache APISIX
+
+Run the following command to start Apache APISIX.
 
 ```shell
-cd apisix-2.7
-make deps
+# start Apache APISIX server
+make run
 ```
 
-## 3. Manage (start/stop) APISIX Server
+### Stop Apache APISIX
+
+Both `make quit` and `make stop` can stop Apache APISIX. The main difference is that `make quit` stops Apache APISIX gracefully, while `make stop` stops Apache APISIX immediately.
+
+It is recommended to use gracefully stop command `make quit` because it ensures that Apache APISIX will complete all the requests it has received before stopping down. In contrast, `make stop` will trigger a forced shutdown, it stops Apache APISIX immediately, in which case the incoming requests will not be processed before the shutdown.
 
-We can start the APISIX server by command `make run` in APISIX home folder,
-or we can stop APISIX server by command `make stop`.
+The command to perform a graceful shutdown is shown below.
 
 ```shell
-# init nginx config file and etcd
-$ make init
+# stop Apache APISIX server gracefully
+make quit
+```
 
-# start APISIX server
-$ make run
+The command to perform a forced shutdown is shown below.
 
-# stop APISIX server gracefully
-$ make quit
+```shell
+# stop Apache APISIX server immediately
+make stop
+```
 
-# stop APISIX server immediately
-$ make stop
+### View Other Operations
 
+Run the `make help` command to see the returned results and get commands and descriptions of other operations.
+
+```shell
 # more actions find by `help`
-$ make help
+make help
 ```
 
-Environment variable can be used to configure APISIX. Please take a look at `conf/config.yaml` to
-see how to do it.
+## Step 4: Run Test Cases
+
+1. Install `cpanminus`, the package manager for `perl`.
+
+2. Then install the test-nginx dependencies via `cpanm`:
+
+  ```shell
+  sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+  ```
 
-## 4. Test
+3. Run the `git clone` command to clone the latest source code locally, please use the version we forked out：
 
-1. Install perl's package manager `cpanminus` first
-2. Then install `test-nginx`'s dependencies via `cpanm`:：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. Clone source code：`git clone https://github.com/iresty/test-nginx.git`. Note that we should use our fork.
-4. Load the `test-nginx` library with perl's `prove` command and run the test cases in the `/t` directory:
-    * Set PERL5LIB for perl module: `export PERL5LIB=.:$PERL5LIB`
-    * Run the test cases: `make test`
-    * To set the path of nginx to run the test cases: `TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`
-    * Some tests depend on external services and modified system configuration. If you want to setup a local CI environment,
-      you can refer to `ci/linux_openresty_common_runner.sh`.
+  ```shell
+  git clone https://github.com/iresty/test-nginx.git
+  ```
+
+4. Load the test-nginx library with the `prove` command in `perl` and run the test case set in the `/t` directory.
+
+  - Append the current directory to the perl module directory: `export PERL5LIB=.:$PERL5LIB`, then run `make test` command.
+
+  - Or you can specify the NGINX binary path by running this command: `TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`.
+
+  :::note Note
+  Some of the tests rely on external services and system configuration modification. For a complete test environment build, you can refer to `ci/linux_openresty_common_runner.sh`.
+  :::
 
 ### Troubleshoot Testing
 
-**Set Nginx Path**
+**Configuring NGINX Path**
 
-- If you run in to an issue `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-make sure to set openresty as default nginx. And export the path as below.
+The solution to the `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` error is as shown below.
 
-* export PATH=/usr/local/openresty/nginx/sbin:$PATH
-    - Linux default installation path:
-        * export PATH=/usr/local/openresty/nginx/sbin:$PATH
-    - OSx default installation path via homebrew:
-        * export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
+Ensure that Openresty is set to the default NGINX, and export the path as follows:
 
-**Run Individual Test Cases**
+* `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
+  * Linux default installation path:
+    * `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
+  * MacOS default installation path via homebrew:
+    * `export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH`
 
-- Use the following command to run test cases constrained to a file:
-    - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+**Run a Single Test Case**
 
-## 5. Update Admin API token to protect Apache APISIX
+Run the specified test case using the following command.
 
-Changes the `apisix.admin_key` in the file `conf/config.yaml` and restart the service.
-Here is an example:
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## Step 5: Update Admin API token to Protect Apache APISIX
+
+You need to modify the Admin API key to protect Apache APISIX.
+
+Please modify `apisix.admin_key` in `conf/config.yaml` and restart the service as shown below.
 
 ```yaml
 apisix:
   # ... ...
   admin_key
     -
       name: "admin"
-      key: abcdefghabcdefgh
+      key: abcdefghabcdefgh # Modify the original key to abcdefghabcdefgh
       role: admin
 ```
 
-When calling the Admin API, `key` can be used as a token.
+When we need to access the Admin API, we can use the key above, as shown below.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+```
+
+The status code 200 in the returned result indicates that the access was successful, as shown below.
 
 ```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
 HTTP/1.1 200 OK
 Date: Fri, 28 Feb 2020 07:48:04 GMT
 Content-Type: text/plain
 ... ...
 {"node":{...},"action":"get"}
+```
 
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh-invalid -i
+At this point, if the key you enter does not match the value of `apisix.admin_key` in `conf/config.yaml`, for example, we know that the correct key is `abcdefghabcdefgh`, but we enter an incorrect key, such as `wrong- key`, as shown below.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
+```
+
+The status code `401` in the returned result indicates that the access failed because the `key` entered was incorrect and did not pass authentication, triggering an `Unauthorized` error, as shown below.
+
+```shell
 HTTP/1.1 401 Unauthorized
 Date: Fri, 28 Feb 2020 08:17:58 GMT
 Content-Type: text/html
 ... ...
 {"node":{...},"action":"get"}
 ```
 
-## 6. Build OpenResty for APISIX
+## Step 6: Build OpenResty for Apache APISIX
 
-Some features require you to build OpenResty with extra Nginx modules.
-If you need those features, you can build OpenResty with
-[this build script](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh).
+Some features require additional NGINX modules to be introduced into OpenResty. If you need these features, you can build OpenResty with [this script](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh).
 
-## 7. Add systemd unit file for APISIX
+## Step 7: Add Systemd Unit File for Apache APISIX
 
-If you install APISIX with rpm package, the unit file is installed automatically, and you could directly do
+If you are using CentOS 7 and you installed Apache APISIX via the RPM package in step 2, the configuration file is already in place automatically and you can run the following command directly.
 
-```
-$ systemctl start apisix
-$ systemctl stop apisix
-$ systemctl enable apisix
+```shell
+systemctl start apisix
+systemctl stop apisix
 ```
 
-If installed in other methods, you could refer to [the unit file template](https://github.com/api7/apisix-build-tools/blob/master/usr/lib/systemd/system/apisix.service), modify if needed, and place it as `/usr/lib/systemd/system/apisix.service`.
+If you installed Apache APISIX by other methods, you can refer to the [configuration file template](https://github.com/api7/apisix-build-tools/blob/master/usr/lib/systemd/system/apisix.service) for modification and put it in the `/usr/lib/systemd/system/apisix.service` path.
diff --git a/docs/zh/latest/getting-started.md b/docs/zh/latest/getting-started.md
@@ -25,7 +25,7 @@ title: 快速入门指南
 
 本文是 Apache APISIX 的快速入门指南。快速入门分为三个步骤：
 
-1. 通过[Docker Compose](https://docs.docker.com/compose/) 安装 Apache APISIX。
+1. 通过 [Docker Compose](https://docs.docker.com/compose/) 安装 Apache APISIX。
 1. 创建路由并绑定上游。
 1. 使用命令行语句 `curl` 验证绑定之后返回的结果是否符合预期。
 
@@ -75,7 +75,7 @@ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"
 - 本文使用 [curl](https://curl.se/docs/manpage.html) 命令行进行 API 测试。您也可以使用其他工具例如 [Postman](https://www.postman.com/)等，进行测试。
 
 :::note 说明
-如果您已经安装了 Apache APISIX，请直接阅读 [第二步](getting-started.md#第二步-创建一个-Route)
+如果您已经安装了 Apache APISIX，请直接阅读 [第二步](getting-started.md#第二步：创建路由)
 :::
 
 ## 第一步：安装 Apache APISIX