Skip to main content
Version: Next

Build development environment on Mac

If you want to quickly build and develop APISIX on your Mac platform, you can refer to this tutorial.


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.

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.

git clone
cd apisix
docker build -t apisix-dev-env -f example/build-dev-image.dockerfile .

Next, start Etcd:

docker run -d --name etcd-apisix --net=host pachyderm/etcd:v3.5.2

Mount the APISIX directory and start the development environment container:

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:

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#

docker exec -it apisix-dev-env make run
docker exec -it apisix-dev-env make stop

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#

docker exec -it apisix-dev-env prove t/admin/routes.t