This is an automated email from the ASF dual-hosted git repository.
shreemaanabhishek 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 abc86a539 docs: add docs for building apisix development environment
in Docker (#10899)
abc86a539 is described below
commit abc86a539eb656210fa6a128a579451735fe98ff
Author: Vacant <[email protected]>
AuthorDate: Mon Feb 5 21:46:49 2024 +0800
docs: add docs for building apisix development environment in Docker
(#10899)
---
.../images/update-docker-desktop-file-sharing.png | Bin 0 -> 166679 bytes
.../latest/build-apisix-dev-environment-on-mac.md | 94 +++++++++++++++++++++
docs/en/latest/config.json | 4 +
.../latest/build-apisix-dev-environment-on-mac.md | 94 +++++++++++++++++++++
docs/zh/latest/config.json | 4 +
example/build-dev-image.dockerfile | 32 +++++++
6 files changed, 228 insertions(+)
diff --git a/docs/assets/images/update-docker-desktop-file-sharing.png
b/docs/assets/images/update-docker-desktop-file-sharing.png
new file mode 100644
index 000000000..39999ac57
Binary files /dev/null and
b/docs/assets/images/update-docker-desktop-file-sharing.png differ
diff --git a/docs/en/latest/build-apisix-dev-environment-on-mac.md
b/docs/en/latest/build-apisix-dev-environment-on-mac.md
new file mode 100644
index 000000000..fb31e5adf
--- /dev/null
+++ b/docs/en/latest/build-apisix-dev-environment-on-mac.md
@@ -0,0 +1,94 @@
+---
+id: build-apisix-dev-environment-on-mac
+title: Build development environment on Mac
+description: This paper introduces how to use Docker to quickly build the
development environment of API gateway Apache APISIX on Mac.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+If you want to quickly build and develop APISIX on your Mac platform, you can
refer to this tutorial.
+
+:::note
+
+This tutorial is suitable for situations where you need to quickly start
development on the Mac platform, if you want to go further and have a better
development experience, the better choice is the Linux-based virtual machine,
or directly use this kind of system as your development environment.
+
+You can see the specific supported systems
[here](install-dependencies.md#install).
+
+:::
+
+## Quick Setup of Apache APISIX Development Environment
+
+### Implementation Idea
+
+We use Docker to build the test environment of Apache APISIX. When the
container starts, we can mount the source code of Apache APISIX into the
container, and then we can build and run test cases in the container.
+
+### Implementation Steps
+
+First, clone the APISIX source code, build an image that can run test cases,
and compile the Apache APISIX.
+
+```shell
+git clone https://github.com/apache/apisix.git
+cd apisix
+docker build -t apisix-dev-env -f example/build-dev-image.dockerfile .
+```
+
+Next, start Etcd:
+
+```shell
+docker run -d --name etcd-apisix --net=host pachyderm/etcd:v3.5.2
+```
+
+Mount the APISIX directory and start the development environment container:
+
+```shell
+docker run -d --name apisix-dev-env --net=host -v $(pwd):/apisix:rw
apisix-dev-env:latest
+```
+
+Finally, enter the container, build the Apache APISIX runtime, and configure
the test environment:
+
+```shell
+docker exec -it apisix-dev-env make deps
+docker exec -it apisix-dev-env ln -s /usr/bin/openresty /usr/bin/nginx
+```
+
+### Run and Stop APISIX
+
+```shell
+docker exec -it apisix-dev-env make run
+docker exec -it apisix-dev-env make stop
+```
+
+:::note
+
+If you encounter an error message like `nginx: [emerg] bind() to
unix:/apisix/logs/worker_events.sock failed (95: Operation not supported)`
while running `make run`, please use this solution.
+
+Change the `File Sharing` settings of your Docker-Desktop:
+
+
+
+Changing to either `gRPC FUSE` or `osxfs` can resolve this issue.
+
+:::
+
+### Run Specific Test Cases
+
+```shell
+docker exec -it apisix-dev-env prove t/admin/routes.t
+```
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 480f63489..fd9a43f2f 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -243,6 +243,10 @@
"type": "doc",
"id": "building-apisix"
},
+ {
+ "type": "doc",
+ "id": "build-apisix-dev-environment-on-mac"
+ },
{
"type": "doc",
"id": "support-fips-in-apisix"
diff --git a/docs/zh/latest/build-apisix-dev-environment-on-mac.md
b/docs/zh/latest/build-apisix-dev-environment-on-mac.md
new file mode 100644
index 000000000..e38c0b391
--- /dev/null
+++ b/docs/zh/latest/build-apisix-dev-environment-on-mac.md
@@ -0,0 +1,94 @@
+---
+id: build-apisix-dev-environment-on-mac
+title: 在 Mac 上构建开发环境
+description: 本文介绍了如何用 Docker 的方式在 Mac 上快速构建 API 网关 Apache APISIX 的开发环境。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+如果你希望快速的在你的 Mac 平台上构建和开发 APISIX，你可以参考本教程。
+
+:::note
+
+本教程适合需要在 Mac 平台快速开始入门阶段开发的情况，如果你想要更进一步，有更好的开发体验，更好的选择是 Linux-based
虚拟机，或是直接使用这类系统作为你的开发环境。
+
+你可以在[这里](install-dependencies.md#安装)看到具体支持的系统。
+
+:::
+
+## 快速构建 Apache APISIX 开发环境
+
+### 实现思路
+
+我们通过 Docker 来构建 Apache APISIX 的测试环境，在容器启动时将 Apache APISIX
的源代码挂载到容器内，就可以做到在容器内构建以及运行测试用例。
+
+### 实现步骤
+
+首先，我们需要拉取 APISIX 源码，并构建一个可以运行测试用例以及编译运行 Apache APISIX 的镜像：
+
+```shell
+git clone https://github.com/apache/apisix.git
+cd apisix
+docker build -t apisix-dev-env -f example/build-dev-image.dockerfile .
+```
+
+然后，我们要启动 Etcd：
+
+```shell
+docker run -d --name etcd-apisix --net=host pachyderm/etcd:v3.5.2
+```
+
+挂载 APISIX 目录并启动开发环境容器：
+
+```shell
+docker run -d --name apisix-dev-env --net=host -v $(pwd):/apisix:rw
apisix-dev-env:latest
+```
+
+最后，构建 Apache APISIX 运行时并配置测试环境：
+
+```shell
+docker exec -it apisix-dev-env make deps
+docker exec -it apisix-dev-env ln -s /usr/bin/openresty /usr/bin/nginx
+```
+
+### 启动和停止 APISIX
+
+```shell
+docker exec -it apisix-dev-env make run
+docker exec -it apisix-dev-env make stop
+```
+
+:::note
+
+如果你在运行 `make run` 时收到类似 `nginx: [emerg] bind() to
unix:/apisix/logs/worker_events.sock failed (95: Operation not supported)`
的错误消息，请使用此解决方案。
+
+更改你的 Docker-Desktop 的 `File Sharing` 设置：
+
+
+
+修改为 `gRPC FUSE` 或 `osxfs` 都可以解决此问题。
+
+:::
+
+### 运行指定测试用例
+
+```shell
+docker exec -it apisix-dev-env prove t/admin/routes.t
+```
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index 5d192eaa9..ba732d033 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -227,6 +227,10 @@
"type": "doc",
"id": "building-apisix"
},
+ {
+ "type": "doc",
+ "id": "build-apisix-dev-environment-on-mac"
+ },
{
"type": "doc",
"id": "support-fips-in-apisix"
diff --git a/example/build-dev-image.dockerfile
b/example/build-dev-image.dockerfile
new file mode 100644
index 000000000..da0d827ba
--- /dev/null
+++ b/example/build-dev-image.dockerfile
@@ -0,0 +1,32 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+FROM ubuntu:20.04
+
+# Install Test::Nginx
+RUN apt update
+RUN apt install -y cpanminus make
+RUN cpanm --notest Test::Nginx
+
+# Install development utils
+RUN apt install -y sudo git gawk curl nano vim inetutils-ping
+
+WORKDIR /apisix
+
+ENV PERL5LIB=.:$PERL5LIB
+
+ENTRYPOINT ["tail", "-f", "/dev/null"]
