Due to issues such aMac M1 make run error differences in local source code installation methods for various development environments (Windows, Ubuntu, macOS, Mac M1, etc.), and the lack of a straightforward way for step-by-step debugging, setting up a development environment for APISIX with debugging capabilities requires a lot of scattered information. To address this, a fast way to establish a local development environment for APISIX is provided in the APISIX Docker repository based on debian-dev. The following guide demonstrates setting up an APISIX development environment using VS Code.
In the docker-compose.yaml file in the debian-emmy folder, you can use the pre-built image directly. However, if you have specific requirements, you can follow the steps below to build a custom apisix-emmy image for local debugging.
services:
apisix:
# [Debian Emmy]: This is a built emmy debug image that includes /usr/local/emmy.so.
# [Debian Emmy]: If there is no special version available, you can use this version directly.
# [Debian Emmy]: If there is a need for customization.
# [Debian Emmy]: TAG: arm or amd https://hub.docker.com/r/coderjia/apisix-emmy/tags
image: "coderjia/apisix-emmy:${TAG}"In the Dockerfile under the image directory in the debian-emmy folder, add the following lines to generate the emmy_core.so file directly into the /usr/local/emmy/ directory within the container. This is useful if you want to upgrade the debug version of Emmy later. Then build the new image.
Place your customized version of the APISIX source code into this directory. If you wish to use the official codebase for learning purposes, you can directly clone the official repository. Remember that this should be the source code directory, excluding the build files.
Copy the
./emmy/emmy-debugger.luaplugin to the ./apisix/plugins directory. This plugin is responsible for loading the Emmy debugger within the container.
a.Modify the ./apisix_conf/config.yamlinfix_path，to the absolute path of your local source code directory.
# [Debian Emmy]: It is only recommended to start one worker in the debug environment.
nginx_config:
worker_processes: 1
# [Debian Emmy]: Loading emmy debugger.lua during the startup of Apisix is the key to emmy dbg listening and hooking(fix path).
plugins:
- emmy-debugger # priority: 50000
# [Debian Emmy]: The fixPath function retrieves the path of the file and "fixes" it to the path expected by VS Code.
plugin_attr:
emmy-debugger:
fix_path: ${prefix}/apisix
port: 9966b. If you need to mount additional directories, adjust the mount paths in the docker-compose.yaml file.
volumes:
- ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro
# [Debian Emmy]: Customized version of Apisix source code
- ./apisix:/usr/local/apisix/apisix:ro
# [Debian Emmy]: When customizing code, you can volume it in more directories.a. Start the APISIX-related containers.
# Version needs to be adjusted independently arm or amd
TAG=amd docker-compose up -d
Check the logs to ensure that the Emmy debugger is listening.
b. Install the Emmy Lua plugin in VS Code.
c. Configure the EmmyLua plugin.
Select the EmmyLua New Debugger.
Add a preLaunchTask line.
Create a tasks.json in the .vscode directory. This is primarily done to restart the container before debugging, preventing code caching from causing the debugger to miss newly added code. Another approach is to disable Lua code cache. Additionally, note that the command in the task is an example for Unix-like systems, and on Windows systems, it can be adjusted to PowerShell.
// unix
{
"version": "2.0.0",
"tasks": [
{
"label": "restartAndDelay",
"type": "shell",
"command": "sh",
"args": [
"-c",
"docker restart ${apisix_container_name} && sleep 3"
]
}
]
}
// windows
{
"version": "2.0.0",
"tasks": [
{
"label": "restartAndDelay",
"type": "shell",
"command": "powershell",
"args": [
"-NoProfile",
"-ExecutionPolicy", "Bypass",
"-Command", "docker restart ${apisix_container_name}; Start-Sleep -Seconds 3"
]
}
]
}d. Start debugging by adding breakpoints in the source code. Use the VS Code debugger to initiate the debugging process.
Start listening in VS Code.
Create a test route and invoke the route.
# create a new route
curl -X PUT \
http://localhost:9180/apisix/admin/routes/1 \
-H 'Content-Type: application/json' \
-H 'x-api-key: edd1c9f034335f136f87ad84b625c8f1' \
-d '{
"uri": "/get",
"plugins": {},
"upstream": {
"pass_host": "node",
"type": "roundrobin",
"nodes": {
"httpbin.org": 1
}
}
}'
# call route
curl --location 'http://localhost:9080/get'After invoking the route, you will observe a successful debugging session.