Building APISIX from source
If you are looking to setup a development environment or contribute to APISIX, this guide is for you.
If you are looking to quickly get started with APISIX, check out the other installation methods.
note
If you want to build and package APISIX for a specific platform, see apisix-build-tools.
#
Building APISIX from sourceInstall dependencies using the script provided by APISIX:
curl https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh -sL | bash -
Save the APISIX version to an environment variable to be used next:
APISIX_VERSION='3.4.1'
Clone the APISIX source code of this version into a new directory apisix-APISIX_VERSION
:
git clone --depth 1 --branch ${APISIX_VERSION} https://github.com/apache/apisix.git apisix-${APISIX_VERSION}
Alternatively, you can also download the source package from the Downloads page. Note that source packages here are not distributed with test cases.
Next, navigate to the directory, install dependencies, and build APISIX. You should have Rust installed in your environment first before running make deps
:
cd apisix-${APISIX_VERSION}
make deps
make install
This will install the runtime-dependent Lua libraries and the apisix
CLI tool.
note
If you get an error message like Could not find header file for LDAP/PCRE/openssl
while running make deps
, use this solution.
luarocks
supports custom compile-time dependencies (See: Config file format). You can use a third-party tool to install the missing packages and add its installation directory to the luarocks
' variables table. This method works on macOS, Ubuntu, CentOS, and other similar operating systems.
The solution below is for macOS but it works similarly for other operating systems:
Install
openldap
by running:brew install openldap
Locate the installation directory by running:
brew --prefix openldap
Add this path to the project configuration file by any of the two methods shown below:
You can use the
luarocks config
command to setLDAP_DIR
:luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1
You can also change the default configuration file of
luarocks
. Open the file~/.luaorcks/config-5.1.lua
and add the following:variables = { LDAP_DIR = "/opt/homebrew/cellar/openldap/2.6.1", LDAP_INCDIR = "/opt/homebrew/cellar/openldap/2.6.1/include", }
/opt/homebrew/cellar/openldap/
is default pathopenldap
is installed on Apple Silicon macOS machines. For Intel machines, the default path is/usr/local/opt/openldap/
.
To uninstall the APISIX runtime, run:
make uninstall
make undeps
danger
This operation will remove the files completely.
#
Installing etcdAPISIX uses etcd to save and synchronize configuration. Before running APISIX, you need to install etcd on your machine. Installation methods based on your operating system are mentioned below.
- Linux
- macOS
ETCD_VERSION='3.4.18'
wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz
tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && \
cd etcd-v${ETCD_VERSION}-linux-amd64 && \
sudo cp -a etcd etcdctl /usr/bin/
nohup etcd >/tmp/etcd.log 2>&1 &
brew install etcd
brew services start etcd
#
Running and managing APISIX serverTo initialize the configuration file, within the APISIX directory, run:
apisix init
tip
You can run apisix help
to see a list of available commands.
You can then test the created configuration file by running:
apisix test
Finally, you can run the command below to start APISIX:
apisix start
To stop APISIX, you can use either the quit
or the stop
subcommand.
apisix quit
will gracefully shutdown APISIX. It will ensure that all received requests are completed before stopping.
apisix quit
Where as, the apisix stop
command does a force shutdown and discards all pending requests.
apisix stop
#
Building runtime for APISIXSome features of APISIX requires additional Nginx modules to be introduced into OpenResty.
To use these features, you need to build a custom distribution of OpenResty (apisix-base). See apisix-build-tools for setting up your build environment and building it.
#
Running testsThe steps below show how to run the test cases for APISIX:
Install cpanminus, the package manager for Perl.
Install the test-nginx dependencies with
cpanm
:sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
Clone the test-nginx source code locally:
git clone https://github.com/openresty/test-nginx.git
Append the current directory to Perl's module directory by running:
export PERL5LIB=.:$PERL5LIB
You can specify the Nginx binary path by running:
TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t
Run the tests by running:
make test
note
Some tests rely on external services and system configuration modification. See ci/linux_openresty_common_runner.sh for a complete test environment build.
#
TroubleshootingThese are some common troubleshooting steps for running APISIX test cases.
#
Configuring Nginx pathFor the error Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf
, ensure that OpenResty is set to the default Nginx and export the path as follows:
Linux default installation path:
export PATH=/usr/local/openresty/nginx/sbin:$PATH
macOS default installation path (view homebrew):
export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
#
Running a specific test caseTo run a specific test case, use the command below:
prove -Itest-nginx/lib -r t/plugin/openid-connect.t
See testing framework for more details.