Project: APISIX (Orchestration & Management / API Gateway)
File: building-apisix.md

id: building-apisix title: Building APISIX from source keywords: API Gateway Apache APISIX Code Contribution Building APISIX description: Guide for building and running APISIX locally for development. <!-- --> import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; 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 . :::note To build an APISIX docker image from source code, see . To build and package APISIX for a specific platform, see instead. ::: First of all, we need to specify the version `APISIX_VERSION` to be installed: ```shell APISIX_VERSION='3.9.0' ``` Then, you can run the following command to clone the APISIX source code from Github: ```shell git clone --depth 1 --branch ${APISIXVERSION} https://github.com/apache/apisix.git apisix-${APISIXVERSION} ``` Alternatively, you can also download the source package from the page. Note that source packages here are not distributed with test cases. Next, navigate to the directory, install dependencies, and build APISIX. ```shell cd apisix-${APISIX_VERSION} make deps make install ``` This will install the runtime-dependent Lua libraries and `apisix-runtime` 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: ). 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: ```shell brew install openldap ``` Locate the installation directory by running: ```shell 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 set `LDAP_DIR`: ```shell 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: ```shell variables = { LDAPDIR = "/opt/homebrew/cellar/openldap/2.6.1", LDAPINCDIR = "/opt/homebrew/cellar/openldap/2.6.1/include", } ``` `/opt/homebrew/cellar/openldap/` is default path `openldap` is installed on Apple Silicon macOS machines. For Intel machines, the default path is `/usr/local/opt/openldap/`. ::: To uninstall the APISIX runtime, run: ```shell make uninstall make undeps ``` :::danger This operation will remove the files completely. ::: APISIX uses to save and synchronize

Before running APISIX, you need to install etcd on your machine. Installation methods based on your operating system are mentioned below. <Tabs groupId="os" defaultValue="linux" values={[ {label: 'Linux', value: 'linux'}, {label: 'macOS', value: 'mac'}, ]}> <TabItem value="linux"> ```shell ETCD_VERSION='3.4.18' wget https://github.com/etcd-io/etcd/releases/download/v${ETCDVERSION}/etcd-v${ETCDVERSION}-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 & ``` </TabItem> <TabItem value="mac"> ```shell brew install etcd brew services start etcd ``` </TabItem> </Tabs> To initialize the configuration file, within the APISIX directory, run: ```shell 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: ```shell apisix test ``` Finally, you can run the command below to start APISIX: ```shell 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. ```shell apisix quit ``` Where as, the `apisix stop` command does a force shutdown and discards all pending requests. ```shell apisix stop ``` Some 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-runtime). See for setting up your build environment and building it. The steps below show how to run the test cases for APISIX: Install , the package manager for Perl. Install the dependencies with `cpanm`: ```shell sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1) ``` Clone the test-nginx source code locally: ```shell git clone https://github.com/openresty/test-nginx.git ``` Append the current directory to Perl's module directory by running: ```shell export PERL5LIB=.:$PERL5LIB ``` You can specify the Nginx binary path by running: ```shell TESTNGINXBINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t ``` Run the tests by running: ```shell make test ``` :::note Some tests rely on external services and system configuration modification. See for a complete test environment build. ::: These are some common troubleshooting steps for running APISIX test cases. For the error `Error unknown directive "luapackagepath" 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: ```shell export PATH=/usr/local/openresty/nginx/sbin:$PATH ``` To run a specific test case, use the command below: ```shell prove -Itest-nginx/lib -r t/plugin/openid-connect.t ``` See for more details.