This guide walks you through how you can build and get Apache APISIX running on your environment. Please refer the Getting Started guide for a quick walkthrough on running Apache APISIX.
Apache APISIX can be installed via the RPM package, Docker image, Helm Chart or the source release package. You can install via any one of these options.
This installation method is suitable for CentOS 7.
If the official OpenResty repository is not installed yet, the following command will help you automatically install both OpenResty and Apache APISIX repositories.
sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
If the official OpenResty repository is installed, the following command will help you automatically install the repositories of Apache APISIX.
sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo
Run the following commands to install the repository and Apache APISIX.
# View the information of the latest apisix package sudo yum info -y apisix # Will show the existing apisix packages sudo yum --showduplicates list apisix # Will install the latest apisix package sudo yum install apisix # Will install a specified version (2.10.3 in this example) apisix package sudo yum install apisix-2.10.3-0.el7
First, download Apache APISIX offline RPM package to ./apisix
folder.
sudo mkdir -p apisix sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm sudo yum clean all && yum makecache sudo yum install -y --downloadonly --downloaddir=./apisix apisix
Then copy ./apisix
folder to the target host and run the following command to install.
sudo yum install ./apisix/*.rpm
Please refer to Installing Apache APISIX with Docker.
Please refer to Installing Apache APISIX with Helm Chart.
Note: if you want to package Apache APISIX for a specific platform, please refer to https://github.com/api7/apisix-build-tools and add the support there. The instruction here is only for people who want to setup their Apache APISIX development environment.
Follow the steps below to install Apache APISIX via the source release package.
curl https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh -sL | bash -
apisix-2.13.0
.APISIX_VERSION='2.13.0' mkdir apisix-${APISIX_VERSION}
wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-src.tgz
You can also download the Apache APISIX source release package from the Apache APISIX website. The website also provides source packages for Apache APISIX, APISIX Dashboard, and APISIX Ingress Controller.
tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}
# Switch to the apisix-${APISIX_VERSION} directory cd apisix-${APISIX_VERSION} # Create dependencies make deps # Install apisix command make install
Note: If you fail to install dependency packages using make deps
and get an error message like Could not find header file for LDAP/PCRE/openssl
, you can use this general method to solve problems.
The general solution: luarocks
supports custom compile-time dependency directories(from this link). Use a third-party tool to install the missing package and add its installation directory to the luarocks
's variables table. This a general method which can be applied to macOS, Ubuntu, CentOS or other usual operating systems, and the specific solution for macOS are given here for reference only.
The following is the solution of macOS, which is similar to that of other operating systems:
1. Install `openldap` with `brew install openldap`; 2. Locate installation directory with `brew --prefix openldap`; 3. Add the path to the project configuration file(choose one of the following two methods): 1. Solution A: You can set `LDAP_DIR` with `luarocks config` manually, for example `luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1`; 2. Solution B: Of course, you can also choose to change the default configuration file of luarocks directly, execute the 'cat ~/.luarocks/config-5.1.lua' command, and then add the installation directory of 'openldap' to the file; 3. Example as follows: 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 path to install openldap on macOS(Apple Silicon) using brew. `/usr/local/opt/openldap/` is default path to install openldap on macOS(Intel) using brew.
To uninstall the Apache APISIX runtime, run:
# Uninstall apisix command make uninstall # Purge dependencies make undeps
Note: This operation will remove the files completely.
The current LTS version of Apache APISIX is 2.13.0
.
To install this version, set APISIX_VERSION
in Installation via Source Release Package to this version and continue with the other steps.
This step is required only if you haven't installed etcd.
Run the command below to install etcd via the binary in Linux:
ETCD_VERSION='3.4.13' 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 &
Run the command below to install etcd in Mac:
brew install etcd # start etcd server brew services start etcd
In the Apache APISIX directory, you can initialize dependencies, start service and stop service with commands. Run apisix help
to get a full list of available commands.
Run the following command to initialize the NGINX configuration file and etcd.
# initialize NGINX config file and etcd apisix init
Run the following command to test the configuration file. APISIX will generate nginx.conf
from config.yaml
and check whether the syntax of nginx.conf
is correct.
# generate `nginx.conf` from `config.yaml` and test it apisix test
Run the following command to start Apache APISIX.
# start Apache APISIX server apisix start
Both apisix quit
and apisix stop
can stop Apache APISIX. The main difference is that apisix quit
stops Apache APISIX gracefully, while apisix stop
stops Apache APISIX immediately.
It is recommended to use the “gracefully stop” command apisix quit
because it ensures that Apache APISIX will complete all the requests it has received before stopping. On the other hand, apisix stop
will trigger a forced shutdown and will stop Apache APISIX immediately. This will cause the pending incoming requests to not be processed before shutdown.
To perform a graceful shutdown, run:
# stop Apache APISIX server gracefully apisix quit
To perform a forced shutdown, run:
# stop Apache APISIX server immediately apisix stop
You can get help and learn more about all the available operations in Apache APISIX by running the help
command as shown below.
# show a list of available operations apisix help
To run the test cases, run the steps outlined below.
Install cpanminus
, the package manager for perl
.
Install the test-nginx dependencies via cpanm
as shown below.
sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
git clone https://github.com/openresty/test-nginx.git
There are two ways to run the tests.
Append the current directory to the perl module directory: export PERL5LIB=.:$PERL5LIB
and then run make test
command.
Specify the NGINX binary path by running TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t
.
:::note Note Some of the tests rely on external services and system configuration modification. For a complete test environment build, you can refer to ci/linux_openresty_common_runner.sh
. :::
The solution to the Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf
error is as shown below.
Ensure that OpenResty is set to the default NGINX, and export the path as follows:
export PATH=/usr/local/openresty/nginx/sbin:$PATH
export PATH=/usr/local/openresty/nginx/sbin:$PATH
export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
To run a specific test case, use the command below.
prove -Itest-nginx/lib -r t/plugin/openid-connect.t
For more details on the test cases, see the testing framework document.
You can modify the Admin API key to secure your Apache APISIX deployment.
This can be done by modifying the apisix.admin_key
in conf/config.yaml
and restarting the service.
apisix: # ... ... admin_key - name: "admin" key: abcdefghabcdefgh # Modify the original key to abcdefghabcdefgh role: admin
Then to access the Admin API, you can use the above key.
curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
A status code of 200 in the returned result will indicate that the access was successful.
HTTP/1.1 200 OK Date: Fri, 28 Feb 2020 07:48:04 GMT Content-Type: text/plain ... ... {"node":{...},"action":"get"}
If the key you entered does not match the value of apisix.admin_key
in conf/config.yaml
, a response with a status code 401 will indicate that the access failed.
curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
HTTP/1.1 401 Unauthorized Date: Fri, 28 Feb 2020 08:17:58 GMT Content-Type: text/html ... ... {"node":{...},"action":"get"}
Some features require additional NGINX modules to be introduced into OpenResty.
If you need these features, you can build APISIX OpenResty. You can refer to the source of api7/apisix-build-tools for setting up your build environment and building APISIX OpenResty.
If you are using CentOS 7 and you installed Apache APISIX via the RPM package, the configuration file will already be in place and you can run the following command directly.
systemctl start apisix
systemctl stop apisix
If you installed Apache APISIX by other methods, please refer to the configuration file template for a modification guide and copy it to the /usr/lib/systemd/system/apisix.service
path.