This is an automated email from the ASF dual-hosted git repository.
bzp2010 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 f1630d2f2 feat: support devcontainer (#11765)
f1630d2f2 is described below
commit f1630d2f2b3f834c8d6b1c172e79755962ba8493
Author: Zeping Bai <bzp2...@apache.org>
AuthorDate: Sun Jun 1 14:28:42 2025 +0800
feat: support devcontainer (#11765)
Co-authored-by: SkyeYoung <isk...@outlook.com>
---
.devcontainer/Dockerfile | 38 +++++++
.devcontainer/devcontainer.json | 14 +++
.devcontainer/docker-compose.yml | 37 +++++++
.gitignore | 1 +
.../images/build-devcontainers-vscode-command.png | Bin 0 -> 19999 bytes
.../build-devcontainers-vscode-progressbar.png | Bin 0 -> 6033 bytes
.../build-apisix-dev-environment-devcontainers.md | 119 +++++++++++++++++++++
docs/en/latest/config.json | 4 +
8 files changed, 213 insertions(+)
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 000000000..4402db7e8
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,38 @@
+#
+# 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:24.04
+
+RUN apt update && export DEBIAN_FRONTEND=noninteractive \
+ && apt install -y sudo git make gcc tini
+
+COPY Makefile .requirements apisix-master-0.rockspec ./
+COPY utils/install-dependencies.sh utils/linux-install-luarocks.sh utils/
+
+RUN make install-runtime
+
+RUN cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log &&
exit 1)
+
+ARG ETCD_VER=v3.5.17
+ARG BUILDARCH
+RUN curl -L
https://github.com/etcd-io/etcd/releases/download/${ETCD_VER}/etcd-${ETCD_VER}-linux-${BUILDARCH}.tar.gz
-o /tmp/etcd-${ETCD_VER}-linux-${BUILDARCH}.tar.gz \
+ && mkdir -p /tmp/etcd-download-test \
+ && tar xzvf /tmp/etcd-${ETCD_VER}-linux-${BUILDARCH}.tar.gz -C
/tmp/etcd-download-test --strip-components=1 \
+ && mv /tmp/etcd-download-test/etcdctl /usr/bin \
+ && rm -rf /tmp/*
+
+ENTRYPOINT [ "tini", "--" ]
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 000000000..7151076d8
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,14 @@
+{
+ "name": "APISIX",
+ "dockerComposeFile": ["docker-compose.yml"],
+ "service": "apisix",
+ "workspaceFolder": "/workspace",
+ "privileged": true,
+ "postCreateCommand": "bash -c 'cd /workspace && rm -rf test-nginx && git
config --global --add safe.directory /workspace && git submodule update --init
--recursive && git clone https://github.com/openresty/test-nginx.git --depth 1
--single-branch -b master && make deps'",
+ "customizations": {
+ "vscode": {
+ "extensions": ["ms-vscode.makefile-tools",
"ms-azuretools.vscode-docker", "sumneko.lua"]
+ }
+ },
+ "forwardPorts": [9080, 9180, 2379]
+}
diff --git a/.devcontainer/docker-compose.yml b/.devcontainer/docker-compose.yml
new file mode 100644
index 000000000..f238f2320
--- /dev/null
+++ b/.devcontainer/docker-compose.yml
@@ -0,0 +1,37 @@
+#
+# 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.
+#
+
+services:
+ apisix:
+ build:
+ context: ..
+ dockerfile: .devcontainer/Dockerfile
+ command: sleep infinity
+ volumes:
+ - ..:/workspace:cached
+ network_mode: service:etcd
+ etcd:
+ image: bitnami/etcd:3.5
+ volumes:
+ - etcd_data:/bitnami/etcd
+ environment:
+ ALLOW_NONE_AUTHENTICATION: "yes"
+ ETCD_ADVERTISE_CLIENT_URLS: "http://127.0.0.1:2379";
+ ETCD_LISTEN_CLIENT_URLS: "http://0.0.0.0:2379";
+
+volumes:
+ etcd_data:
diff --git a/.gitignore b/.gitignore
index 94669c345..01455638f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -64,6 +64,7 @@ t/lib/dubbo*/**/target/
*.iml
\.*
!.github/
+!.devcontainer/
!.gitmodules
!.markdownlint.yml
!.licenserc.yaml
diff --git a/docs/assets/images/build-devcontainers-vscode-command.png
b/docs/assets/images/build-devcontainers-vscode-command.png
new file mode 100644
index 000000000..b7908d366
Binary files /dev/null and
b/docs/assets/images/build-devcontainers-vscode-command.png differ
diff --git a/docs/assets/images/build-devcontainers-vscode-progressbar.png
b/docs/assets/images/build-devcontainers-vscode-progressbar.png
new file mode 100644
index 000000000..05a51dfce
Binary files /dev/null and
b/docs/assets/images/build-devcontainers-vscode-progressbar.png differ
diff --git a/docs/en/latest/build-apisix-dev-environment-devcontainers.md
b/docs/en/latest/build-apisix-dev-environment-devcontainers.md
new file mode 100644
index 000000000..22c3d864f
--- /dev/null
+++ b/docs/en/latest/build-apisix-dev-environment-devcontainers.md
@@ -0,0 +1,119 @@
+---
+id: build-apisix-dev-environment-devcontainers
+title: Build development environment with Dev Containers
+description: This paper introduces how to quickly start the APISIX API Gateway
development environment using Dev Containers.
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+Previously, building and developing APISIX on Linux or macOS required
developers to install its runtime environment and toolchain themselves, and
developers might not be familiar with them.
+
+As it needs to support multiple operating systems and CPU ISAs, the process
has inherent complexities in how to find and install dependencies and
toolchains.
+
+:::note
+
+The tutorial can be used as an alternative to a [bare-metal
environment](building-apisix.md) or a [macOS container development
environment](build-apisix-dev-environment-on-mac.md).
+
+It only requires that you have an environment running Docker or a similar
alternative (the docker/docker compose command is required), and no other
dependent components need to be installed on your host machine.
+
+:::
+
+## Supported systems and CPU ISA
+
+- Linux
+ - AMD64
+ - ARM64
+- Windows (with WSL2 supported)
+ - AMD64
+- macOS
+ - ARM64
+ - AMD64
+
+## Quick Setup of Apache APISIX Development Environment
+
+### Implementation Idea
+
+We use Dev Containers to build development environment, and when we open an
APISIX project using the IDE, we have access to the container-driven runtime
environment.
+
+There the etcd is ready and we can start APISIX directly.
+
+### Steps
+
+:::note
+
+The following uses Visual Studio Code, which has built-in integration with Dev
Containers.
+
+In theory you could also use any other editor or IDE that integrates with Dev
Containers.
+
+:::
+
+First, clone the APISIX source code, open project in Visual Studio Code.
+
+```shell
+git clone https://github.com/apache/apisix.git
+cd apisix
+code . # VSCode needs to be in the PATH environment variable, you can also
open the project directory manually in the UI.
+```
+
+Next, switch to Dev Containers. Open the VSCode Command Palette, and execute
`Dev Containers: Reopen in Container`.
+
+
+
+VSCode will open the Dev Containers project in a new window, where it will
build the runtime and install the toolchain according to the Dockerfile before
starting the connection and finally installing the APISIX dependencies.
+
+:::note
+
+This process requires a reliable network connection, and it will access Docker
Hub, GitHub, and some other sites. You will need to ensure the network
connection yourself, otherwise the container build may fail.
+
+:::
+
+Wait some minutes, depending on the internet connection or computer
performance, it may take from a few minutes to tens of minutes, you can click
on the Progress Bar in the bottom right corner to view a live log where you
will be able to check unusual stuck.
+
+If you encounter any problems, you can search or ask questions in [GitHub
Issues](https://github.com/apache/apisix/issues) or [GitHub
Discussions](https://github.com/apache/apisix/discussions), and community
members will respond as promptly as possible.
+
+
+
+When the process in the terminal is complete, the development environment is
ready, and even etcd is ready.
+
+Start APISIX with the following command:
+
+```shell
+make run
+```
+
+Now you can start writing code and test cases, and testing tools are available:
+
+```shell
+export TEST_NGINX_BINARY=openresty
+
+# run all tests
+make test
+
+# or run a specify test case file
+FLUSH_ETCD=1 prove -Itest-nginx/lib -I. -r t/admin/api.t
+```
+
+## FAQ
+
+### Where's the code? When I delete the container, are the changes lost?
+
+It will be on your host, which is where you cloned the APISIX source code, and
the container uses the volume to mount the code into the container. Containers
contain only the runtime environment, not the source code, so no changes will
be lost whether you close or delete the container.
+
+And, the `git` is already installed in the container, so you can commit a
change directly there.
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 9531d908e..cae7cee33 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -263,6 +263,10 @@
"type": "category",
"label": "Development",
"items": [
+ {
+ "type": "doc",
+ "id": "build-apisix-dev-environment-devcontainers"
+ },
{
"type": "doc",
"id": "building-apisix"
