Building APISIX from source | Apache APISIX® -- Cloud-Native API Gateway
Skip to main content🤔 Have queries regarding API Gateway? Join Slack channel to discuss join #apisix channel! ⭐️Apache APISIX®DocsApache APISIX®️Apache APISIX®️ DashboardApache APISIX®️ Ingress ControllerApache APISIX®️ Helm ChartsApache APISIX®️ DockerApache APISIX®️ Java Plugin RunnerApache APISIX®️ Go Plugin RunnerApache APISIX®️ Python Plugin RunnerGeneralBlogCase StudiesDownloadsHelpTeamResourcesShowcasePluginHubCommunityEventsEnglishEnglish简体中文🌜🌞SearchApache APISIX®Version:3.1Next3.1Latest3.02.15LTS2.142.132.122.112.102.92.82.72.62.52.4Getting startedInstallationArchitectureTutorialsTerminologyPluginsAPIDevelopmentBuilding APISIX from sourceSupport FIPS in APISIXExternal PluginWasmCODE_STYLEinternalPlugin DevelopDebug modeFAQOthersCHANGELOGUpgrade GuideVersion: 3.1On this pageBuilding APISIX from sourceIf you are looking to contribute to APISIX or setup a development environment, this guide is for you.If you are looking to install and run APISIX, check out the Installation docs.noteIf you want to build and package APISIX for a specific platform, see apisix-build-tools.Building APISIX from source#To start, you have to install some dependencies. APISIX provides a handy script to get these installed:curl https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh -sL | bash -CopyThen, create a directory and set the environment variable APISIX_VERSION:APISIX_VERSION='3.1.0'mkdir apisix-${APISIX_VERSION}CopyYou can now clone the APISIX source code from Github by running the command below:git clone --depth 1 --branch ${APISIX_VERSION} https://github.com/apache/apisix.git apisix-${APISIX_VERSION}CopyYou can also download the source package from the Downloads page. But the source package missing the test case. This may affect subsequent operations.And you will also find source packages for APISIX Dashboard and APISIX Ingress Controller from Downloads page.Now, navigate to the directory, create dependencies, and install APISIX as shown below:cd apisix-${APISIX_VERSION}make depsmake installCopyThis will install the runtime dependent Lua libraries and the apisix command.noteIf 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 openldapCopyLocate the installation directory by running:brew --prefix openldapCopyAdd 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:luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1CopyYou 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", }Copy/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:make uninstallmake undepsCopydangerThis operation will remove the files completely.Installing etcd#APISIX 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.LinuxmacOSETCD_VERSION='3.4.18'wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gztar -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 &Copybrew install etcdbrew services start etcdCopyRunning and managing APISIX server#To initialize the configuration file, within the APISIX directory, run:apisix initCopytipYou can run apisix help to see a list of available commands.You can then test the created configuration file by running:apisix testCopyFinally, you can run the command below to start APISIX:apisix startCopyTo 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 quitCopyWhere as, the apisix stop command does a force shutdown and discards all pending requests.apisix stopCopyBuilding runtime for APISIX#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-base). See apisix-build-tools for setting up your build environment and building it.Running tests#The 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)CopyClone the test-nginx source code locally:git clone https://github.com/openresty/test-nginx.gitCopyAppend the current directory to Perl's module directory by running:export PERL5LIB=.:$PERL5LIBCopyYou can specify the Nginx binary path by running:TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r tCopyRun the tests by running:make testCopynoteSome tests rely on external services and system configuration modification. See ci/linux_openresty_common_runner.sh for a complete test environment build.Troubleshooting#These are some common troubleshooting steps for running APISIX test cases.Configuring Nginx path#For 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:$PATHCopymacOS default installation path (view homebrew):export PATH=/usr/local/opt/openresty/nginx/sbin:$PATHCopyRunning a specific test case#To run a specific test case, use the command below:prove -Itest-nginx/lib -r t/plugin/openid-connect.tCopySee testing framework for more details.Edit this pagePrevious« Control APINextSupport FIPS in APISIX »Building APISIX from sourceInstalling etcdRunning and managing APISIX serverBuilding runtime for APISIXRunning testsTroubleshootingASFFoundationLicenseEventsSecuritySponsorshipThanksCommunityGitHubSlackTwitterYouTubeMoreBlogShowcasePlugin HubCopyright © 2019-2023 The Apache Software Foundation. Apache APISIX, APISIX®, Apache, the Apache feather logo, and the Apache APISIX project logo are either registered trademarks or trademarks of the Apache Software Foundation.