Skip to content

Commit

Permalink
docs(getting-started): rewrite the install section (#8807)
Browse files Browse the repository at this point in the history 
Co-authored-by: 琚致远 / Zhiyuan Ju <juzhiyuan@apache.org>
Co-authored-by: Abhishek Choudhary <shreemaan.abhishek@gmail.com>
  • Loading branch information
@An-DJ @juzhiyuan @shreemaan-abhishek
3 people authored Feb 8, 2023
1 parent e587bc4 commit e021266
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 114 deletions.
74 changes: 18 additions & 56 deletions docs/en/latest/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,41 +119,20 @@ We receive a JSON response when we send the request:

## Install Apache APISIX

To get started, we will install Apache APISIX with Docker and enable the [Admin API](./admin-api.md).
APISIX can be easily installed and started with the quickstart script.

First clone the [apisix-docker](https://github.com/apache/apisix-docker) repository:

```shell
git clone https://github.com/apache/apisix-docker.git
cd apisix-docker/example
```

Now, you can use `docker-compose` to start APISIX.

<Tabs
groupId="cpu-arch"
defaultValue="x86"
values={[
{label: 'x86', value: 'x86'},
{label: 'ARM/M1', value: 'arm'},
]}>
<TabItem value="x86">

```shell
docker-compose -p docker-apisix up -d
```sh
curl -sL https://run.api7.ai/apisix/quickstart | sh
```

</TabItem>
This command runs APISIX and etcd locally with Docker. APISIX uses etcd to save and synchronize configuration. Both etcd and APISIX use the [**host**](https://docs.docker.com/network/host/) Docker network mode. That is, APISIX can be accessed locally.

<TabItem value="arm">
If everything is ok, you will see the following message.

```shell
docker-compose -p docker-apisix -f docker-compose-arm64.yml up -d
```text
✔ APISIX is ready!
```

</TabItem>
</Tabs>

:::note

You can check out [Installing Apache APISIX](./installation-guide.md) for different installation methods.
Expand All @@ -164,39 +143,22 @@ You can check out [Installing Apache APISIX](./installation-guide.md) for differ

Make sure that all the required ports (default: 9080, 9180, 9443 and 2379) are available and not used by other system processes.

On Unix-based systems, you can run the command below to terminate a process listening on a specific port:

```bash
sudo fuser -k 9443/tcp
```

If a Docker container is crashing, you can inspect the logs to diagnose the problem:

```bash
docker logs -f --tail <container_id>
```

:::

Once APISIX is running, you can use `curl` to access the Admin API. You can also check if APISIX is running properly by running this command and checking the response.
Once APISIX is running, you can use curl to access it. Send a simple HTTP request to validate if APISIX is working properly or not.

```bash
curl "http://127.0.0.1:9180/apisix/admin/services/" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```sh
curl "http://127.0.0.1:9080" --head | grep Server
```

This response indicates that APISIX is running successfully:
If everything is ok, you will get the following response.

```json
{
"count":0,
"node":{
"key":"/apisix/services",
"nodes":[],
"dir":true
}
}
```text
Server: APISIX/3.1.0
```

You now have APISIX installed and running successfully!​

## Create a Route

From the previous step, we have a running instance of APISIX in Docker. Now let's create a Route.
Expand All @@ -206,7 +168,7 @@ APISIX provides a powerful [Admin API](./admin-api.md) and [APISIX Dashboard](ht
We will configure the Route so that APISIX can forward the request to the corresponding Upstream service:

```bash
curl "http://127.0.0.1:9180/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
curl "http://127.0.0.1:9180/apisix/admin/routes/1" -X PUT -d '
{
"methods": ["GET"],
"host": "example.com",
Expand Down Expand Up @@ -241,7 +203,7 @@ Instead of configuring the Upstream directly to the Route, you can create an Ups
To create an Upstream object:

```bash
curl "http://127.0.0.1:9180/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
curl "http://127.0.0.1:9180/apisix/admin/upstreams/1" -X PUT -d '
{
"type": "roundrobin",
"nodes": {
Expand All @@ -255,7 +217,7 @@ This is the same as the Upstream service we configured directly into the Route o
To bind this Upstream to the Route, we can use the `upstream_id` as `1`:

```bash
curl "http://127.0.0.1:9180/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
curl "http://127.0.0.1:9180/apisix/admin/routes/1" -X PUT -d '
{
"methods": ["GET"],
"host": "example.com",
Expand Down
75 changes: 17 additions & 58 deletions docs/zh/latest/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,41 +111,20 @@ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"

## 安装 APISIX

我们将使用 Docker 安装 APISIX 并启用 [Admin API](./admin-api.md)。
APISIX 可以借助 quickstart 脚本快速安装并启动。

首先，通过 `git` 命令克隆 [apisix-docker](https://github.com/apache/apisix-docker) 仓库：

```bash
git clone https://github.com/apache/apisix-docker.git
cd apisix-docker/example
```

现在你可以通过 `docker-compose` 启动 APISIX。

<Tabs
groupId="cpu-arch"
defaultValue="x86"
values={[
{label: 'x86', value: 'x86'},
{label: 'ARM/M1', value: 'arm'},
]}>
<TabItem value="x86">

```shell
docker-compose -p docker-apisix up -d
```sh
curl -sL https://run.api7.ai/apisix/quickstart | sh
```

</TabItem>
该命令在本地安装并运行了基于 Docker 的 APISIX 和 etcd 容器，其中 APISIX 采用 etcd 保存和同步配置信息。APISIX 和 etcd 容器使用 [**host**](https://docs.docker.com/network/host/) 的 Docker 网络模式，因此可以从本地直接访问。

<TabItem value="arm">
如果一切顺利，将输出如下信息。

```shell
docker-compose -p docker-apisix -f docker-compose-arm64.yml up -d
```text
✔ APISIX is ready!
```

</TabItem>
</Tabs>

:::note

你也可以参考 [APISIX 安装指南](./installation-guide.md)了解不同的安装方法。
Expand All @@ -156,41 +135,21 @@ docker-compose -p docker-apisix -f docker-compose-arm64.yml up -d

请确保其他系统进程没有占用 **9080、9180、9443 和 2379** 端口。

在基于 UNIX 的系统中，可以使用以下命令来终止指定监听端口的运行：

```bash
sudo fuser -k 9443/tcp
```

如果 Docker 容器不能正常运行，你可以通过以下命令检查日志进行问题诊断：

```bash
docker logs -f --tail $<container_id>
```

:::

安装完成后，你可以在运行 Docker 的宿主机上执行 `curl` 命令访问 Admin API，根据返回数据判断 APISIX 是否成功启动。
你可以通过 curl 来访问正在运行的 APISIX 实例。比如，你可以发送一个简单的 HTTP 请求来验证 APISIX 运行状态是否正常。

```bash
# 注意：请在运行 Docker 的宿主机上执行 curl 命令。
curl "http://127.0.0.1:9180/apisix/admin/services/" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```sh
curl "http://127.0.0.1:9080" --head | grep Server
```

如果返回数据如下所示，则表示 APISIX 成功启动：
I如果一切顺利，将输出如下信息。

```json
{
"count":0,
"node":{
"key":"/apisix/services",
"nodes":[],
"dir":true
}
}
```text
Server: APISIX/3.1.0
```

完成上述步骤后，你就已经拥有了一个正在运行的 APISIX 的实例了，现在你可以从之后的小节中学习如何创建路由以及了解 APISIX Dashboard 的操作。
现在，你已经成功安装并运行了 APISIX ！

## 创建路由

Expand All @@ -199,7 +158,7 @@ APISIX 提供了强大的 [Admin API](./admin-api.md) 和 [Dashboard](https://gi
以下示例代码中，我们将为路由配置匹配规则，以便 APISIX 可以将请求转发到对应的上游服务：

```bash
curl "http://127.0.0.1:9180/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
curl "http://127.0.0.1:9180/apisix/admin/routes/1" -X PUT -d '
{
"methods": ["GET"],
"host": "example.com",
Expand Down Expand Up @@ -232,7 +191,7 @@ curl -i -X GET "http://127.0.0.1:9080/anything/foo?arg=10" -H "Host: example.com
你可以通过以下命令创建一个上游，并在路由中使用它，而不是直接将其配置在路由中：

```bash
curl "http://127.0.0.1:9180/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
curl "http://127.0.0.1:9180/apisix/admin/upstreams/1" -X PUT -d '
{
"type": "roundrobin",
"nodes": {
Expand All @@ -246,7 +205,7 @@ curl "http://127.0.0.1:9180/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f0343
上游服务创建完成后，可以通过以下命令绑定到指定路由：

```bash
curl "http://127.0.0.1:9180/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
curl "http://127.0.0.1:9180/apisix/admin/routes/1" -X PUT -d '
{
"uri": "/get",
"host": "httpbin.org",
Expand Down

0 comments on commit e021266

Please sign in to comment.