You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/02/13 12:01:45 UTC
[apisix] branch master updated: docs: added cpanm installation commands and remove $ sign (#6284)
This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 5c0896a docs: added cpanm installation commands and remove $ sign (#6284)
5c0896a is described below
commit 5c0896a9896cf9918913ea256573ec8a7947c28b
Author: homeward <97...@users.noreply.github.com>
AuthorDate: Sun Feb 13 20:01:06 2022 +0800
docs: added cpanm installation commands and remove $ sign (#6284)
---
docs/en/latest/how-to-build.md | 78 ++++++++++++++++++++++--------------------
docs/zh/latest/how-to-build.md | 76 ++++++++++++++++++++--------------------
2 files changed, 79 insertions(+), 75 deletions(-)
diff --git a/docs/en/latest/how-to-build.md b/docs/en/latest/how-to-build.md
index e02f362..12a73e9 100644
--- a/docs/en/latest/how-to-build.md
+++ b/docs/en/latest/how-to-build.md
@@ -32,26 +32,26 @@ This installation method is suitable for CentOS 7.
If the official OpenResty repository is not installed yet, the following command will help you automatically install both the repositories of OpenResty and Apache APISIX.
```shell
-$ sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
+sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
```
If the official OpenResty repository is installed, the following command will help you automatically install the repositories of Apache APISIX.
```shell
-$ sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo
+sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo
```
Please run the following commands to install the repository and Apache APISIX.
```shell
# View the information of the latest apisix package
-$ sudo yum info -y apisix
+sudo yum info -y apisix
# Will show the existing apisix packages
-$ sudo yum --showduplicates list apisix
+sudo yum --showduplicates list apisix
# Will install the latest apisix package
-$ sudo yum install apisix
+sudo yum install apisix
```
### Installation via RPM Offline Package(CentOS 7)
@@ -59,16 +59,16 @@ $ sudo yum install apisix
Download APISIX offline RPM package to `./apisix` folder
```shell
-$ sudo mkdir -p apisix
-$ sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
-$ sudo yum clean all && yum makecache
-$ sudo yum install -y --downloadonly --downloaddir=./apisix apisix
+sudo mkdir -p apisix
+sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
+sudo yum clean all && yum makecache
+sudo yum install -y --downloadonly --downloaddir=./apisix apisix
```
Copy `./apisix` folder to the target host, run the following command to install Apache APISIX.
```shell
-$ sudo yum install ./apisix/*.rpm
+sudo yum install ./apisix/*.rpm
```
### Installation via Docker
@@ -84,14 +84,14 @@ Please refer to: [Installing Apache APISIX with Helm Chart](https://github.com/a
1. Create a directory named `apisix-2.12.0`.
```shell
- $ APISIX_VERSION='2.12.0'
- $ mkdir apisix-${APISIX_VERSION}
+ APISIX_VERSION='2.12.0'
+ mkdir apisix-${APISIX_VERSION}
```
2. Download Apache APISIX Release source package.
```shell
- $ wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-src.tgz
+ wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-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.
@@ -99,18 +99,18 @@ Please refer to: [Installing Apache APISIX with Helm Chart](https://github.com/a
3. Unzip the Apache APISIX Release source package.
```shell
- $ tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}
+ tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}
```
4. Install the runtime dependent Lua libraries.
```shell
# Switch to the apisix-${APISIX_VERSION} directory
- $ cd apisix-${APISIX_VERSION}
+ cd apisix-${APISIX_VERSION}
# Create dependencies
- $ make deps
+ make deps
# Install apisix command
- $ make install
+ make install
```
- 4.1 `make deps` install `lualdap` failed, error like: `Could not find header file for LDAP`
@@ -121,9 +121,9 @@ Please refer to: [Installing Apache APISIX with Helm Chart](https://github.com/a
```shell
# Uninstall apisix command
- $ make uninstall
+ make uninstall
# Purge dependencies
- $ make undeps
+ make undeps
```
Attention please, this operation will totally **remove** the related files.
@@ -139,12 +139,12 @@ This step is required if you have installed only Apache APISIX via RPM, Docker o
You can install ETCD via Docker or binary etc. The following command installs ETCD via binary.
```shell
-$ ETCD_VERSION='3.4.13'
-$ wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz
-$ tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && \
- cd etcd-v${ETCD_VERSION}-linux-amd64 && \
- sudo cp -a etcd etcdctl /usr/bin/
-$ nohup etcd &
+ETCD_VERSION='3.4.13'
+wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz
+tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && \
+ cd etcd-v${ETCD_VERSION}-linux-amd64 && \
+ sudo cp -a etcd etcdctl /usr/bin/
+nohup etcd >/tmp/etcd.log 2>&1 &
```
## Step 3: Manage Apache APISIX Server
@@ -157,7 +157,7 @@ Run the following command to initialize the NGINX configuration file and etcd.
```shell
# initialize NGINX config file and etcd
-$ apisix init
+apisix init
```
### Test configuration file
@@ -166,7 +166,7 @@ Run the following command to test the configuration file. APISIX will generate `
```shell
# generate `nginx.conf` from `config.yaml` and test it
-$ apisix test
+apisix test
```
### Start Apache APISIX
@@ -175,7 +175,7 @@ Run the following command to start Apache APISIX.
```shell
# start Apache APISIX server
-$ apisix start
+apisix start
```
### Stop Apache APISIX
@@ -188,14 +188,14 @@ The command to perform a graceful shutdown is shown below.
```shell
# stop Apache APISIX server gracefully
-$ apisix quit
+apisix quit
```
The command to perform a forced shutdown is shown below.
```shell
# stop Apache APISIX server immediately
-$ apisix stop
+apisix stop
```
### View Other Operations
@@ -204,23 +204,25 @@ Run the `apisix help` command to see the returned results and get commands and d
```shell
# more actions find by `help`
-$ apisix help
+apisix help
```
## Step 4: Run Test Cases
1. Install `cpanminus`, the package manager for `perl`.
+Please refer to: [Installing package manager `cpanminus`](https://metacpan.org/pod/App::cpanminus#INSTALLATION).
+
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)
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
```
3. Run the `git clone` command to clone the latest source code locally, please use the version we forked out：
```shell
- $ git clone https://github.com/iresty/test-nginx.git
+ git clone https://github.com/iresty/test-nginx.git
```
4. Here are two ways of running tests:
@@ -262,7 +264,7 @@ Ensure that OpenResty is set to the default NGINX, and export the path as follow
Run the specified test case using the following command.
```shell
-$ prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
```
For more details on the test cases, see the [testing framework](https://github.com/apache/apisix/blob/master/docs/en/latest/internal/testing-framework.md).
@@ -286,7 +288,7 @@ apisix:
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
+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.
@@ -302,7 +304,7 @@ Content-Type: text/plain
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
+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.
@@ -326,8 +328,8 @@ You can refer to the source of [api7/apisix-build-tools](https://github.com/api7
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.
```shell
-$ systemctl start apisix
-$ systemctl stop apisix
+systemctl start apisix
+systemctl stop apisix
```
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/how-to-build.md b/docs/zh/latest/how-to-build.md
index 5fe544e..9823906 100644
--- a/docs/zh/latest/how-to-build.md
+++ b/docs/zh/latest/how-to-build.md
@@ -32,26 +32,26 @@ title: 如何构建 Apache APISIX
如果尚未安装 OpenResty 的官方 RPM 仓库，请使用以下命令自动安装 OpenResty 和 Apache APISIX 的 RPM 仓库。
```shell
-$ sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
+sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
```
如果已安装 OpenResty 的官方 RPM 仓库，请使用以下命令自动安装 Apache APISIX 的 RPM 仓库。
```shell
-$ sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo
+sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo
```
请运行以下命令安装 Apache APISIX。
```shell
# 查看仓库中最新的 apisix 软件包的信息
-$ sudo yum info -y apisix
+sudo yum info -y apisix
# 显示仓库中现有的 apisix 软件包
-$ sudo yum --showduplicates list apisix
+sudo yum --showduplicates list apisix
# 安装最新的 apisix 软件包
-$ sudo yum install apisix
+sudo yum install apisix
```
### 通过 RPM 包离线安装（CentOS 7）
@@ -59,16 +59,16 @@ $ sudo yum install apisix
下载 APISIX 离线 RPM 包到 `./apisix` 文件夹
```shell
-$ sudo mkdir -p apisix
-$ sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
-$ sudo yum clean all && yum makecache
-$ sudo yum install -y --downloadonly --downloaddir=./apisix apisix
+sudo mkdir -p apisix
+sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
+sudo yum clean all && yum makecache
+sudo yum install -y --downloadonly --downloaddir=./apisix apisix
```
拷贝 `./apisix` 文件夹到目标主机，使用以下命令安装 Apache APISIX。
```shell
-$ sudo yum install ./apisix/*.rpm
+sudo yum install ./apisix/*.rpm
```
### 通过 Docker 安装
@@ -84,14 +84,14 @@ $ sudo yum install ./apisix/*.rpm
1. 创建一个名为 `apisix-2.12.0` 的目录。
```shell
- $ APISIX_VERSION='2.12.0'
- $ mkdir apisix-${APISIX_VERSION}
+ APISIX_VERSION='2.12.0'
+ mkdir apisix-${APISIX_VERSION}
```
2. 下载 Apache APISIX Release 源码包：
```shell
- $ wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-src.tgz
+ wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-src.tgz
```
您也可以通过 Apache APISIX 官网下载 Apache APISIX Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考 [Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
@@ -99,18 +99,18 @@ $ sudo yum install ./apisix/*.rpm
3. 解压 Apache APISIX Release 源码包：
```shell
- $ tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}
+ tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}
```
4. 安装运行时依赖的 Lua 库：
```shell
# 切换到 apisix-${APISIX_VERSION} 目录
- $ cd apisix-${APISIX_VERSION}
+ cd apisix-${APISIX_VERSION}
# 安装依赖
- $ LUAROCKS_SERVER=https://luarocks.cn make deps
+ LUAROCKS_SERVER=https://luarocks.cn make deps
# 安装 apisix 命令
- $ make install
+ make install
```
- 4.1 `make deps` 安装 `lualdap` 失败, 错误信息如: `Could not find header file for LDAP`
@@ -121,9 +121,9 @@ $ sudo yum install ./apisix/*.rpm
```shell
# 卸载 apisix 命令
- $ make uninstall
+ make uninstall
# 卸载依赖
- $ make undeps
+ make undeps
```
请注意，该操作将完整**删除**相关文件。
@@ -140,11 +140,11 @@ $ sudo yum install ./apisix/*.rpm
```shell
ETCD_VERSION='3.4.13'
-$ wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz
-$ tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && \
- cd etcd-v${ETCD_VERSION}-linux-amd64 && \
- sudo cp -a etcd etcdctl /usr/bin/
-$ nohup etcd &
+wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz
+tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && \
+ cd etcd-v${ETCD_VERSION}-linux-amd64 && \
+ sudo cp -a etcd etcdctl /usr/bin/
+nohup etcd >/tmp/etcd.log 2>&1 &
```
## 步骤3：管理 Apache APISIX 服务
@@ -157,7 +157,7 @@ $ nohup etcd &
```shell
# initialize NGINX config file and etcd
-$ apisix init
+apisix init
```
### 测试配置文件
@@ -166,7 +166,7 @@ $ apisix init
```shell
# generate `nginx.conf` from `config.yaml` and test it
-$ apisix test
+apisix test
```
### 启动 Apache APISIX
@@ -175,7 +175,7 @@ $ apisix test
```shell
# start Apache APISIX server
-$ apisix start
+apisix start
```
### 停止运行 Apache APISIX
@@ -186,14 +186,14 @@ $ apisix start
```shell
# stop Apache APISIX server gracefully
-$ apisix quit
+apisix quit
```
执行强制停机的命令如下所示：
```shell
# stop Apache APISIX server immediately
-$ apisix stop
+apisix stop
```
### 查看其他操作
@@ -202,23 +202,25 @@ $ apisix stop
```shell
# more actions find by `help`
-$ apisix help
+apisix help
```
## 步骤4：运行测试案例
1. 安装 `perl` 的包管理器 `cpanminus`。
+详情请参考：[安装包管理器 `cpanmius`](https://metacpan.org/pod/App::cpanminus#INSTALLATION)。
+
2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
```shell
- $ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
```
3. 运行 `git clone` 命令，将最新的源码克隆到本地，请使用我们 fork 出来的版本：
```shell
- $ git clone https://github.com/iresty/test-nginx.git
+ git clone https://github.com/iresty/test-nginx.git
```
4. 有两种方法运行测试：
@@ -260,7 +262,7 @@ $ apisix help
使用以下命令运行指定的测试用例：
```shell
-$ prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
```
关于测试用例的更多细节，参见 [测试框架](https://github.com/apache/apisix/blob/master/docs/en/latest/internal/testing-framework.md)
@@ -284,7 +286,7 @@ apisix:
当我们需要访问 Admin API 时，就可以使用上面记录的 key 了，如下所示：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
```
返回结果中的状态码 200 说明访问成功，如下所示：
@@ -300,7 +302,7 @@ Content-Type: text/plain
在这个时候，如果您输入的 key 与 `conf/config.yaml` 中 `apisix.admin_key` 的值不匹配，例如，我们已知正确的 key 是 `abcdefghabcdefgh`，但是我们选择输入一个错误的 key，例如 `wrong-key`，如下所示：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
```
返回结果中的状态码 `401` 说明访问失败，原因是输入的 `key` 有误，未通过认证，触发 `Unauthorized` 错误，如下所示：
@@ -324,8 +326,8 @@ Content-Type: text/html
如果您使用的操作系统是 CentOS 7，且在步骤 2 中通过 RPM 包安装 Apache APISIX，配置文件已经自动安装到位，你可以直接运行以下命令：
```shell
-$ systemctl start apisix
-$ systemctl stop apisix
+systemctl start apisix
+systemctl stop apisix
```
如果通过其他方法安装，可以参考 [配置文件模板](https://github.com/api7/apisix-build-tools/blob/master/usr/lib/systemd/system/apisix.service) 进行修改，并将其放置在 `/usr/lib/systemd/system/apisix.service` 路径下。