Installing Apache APISIX
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.
#
Step 1: Install Apache APISIXApache 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.
#
Installation via RPM Repository (CentOS 7)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
#
Installation via RPM Offline Package (CentOS 7)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
#
Installation via DockerPlease refer to Installing Apache APISIX with Docker.
#
Installation via Helm ChartPlease refer to Installing Apache APISIX with Helm Chart.
#
Installation via Source Release PackageNote: 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.
Install dependencies
curl https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh -sL | bash -
Create a directory named
apisix-2.13.3
.APISIX_VERSION='2.13.3'
mkdir apisix-${APISIX_VERSION}Download the Apache APISIX source release package.
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.
Uncompress the Apache APISIX source release package.
tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}
Install the runtime dependent Lua libraries.
# Switch to the apisix-${APISIX_VERSION} directory
cd apisix-${APISIX_VERSION}
# Create dependencies
make deps
# Install apisix command
make installNote: If you fail to install dependency packages using
make deps
and get an error message likeCould 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 theluarocks
'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:
Install
openldap
withbrew install openldap
;Locate installation directory with
brew --prefix openldap
;Add the path to the project configuration file(choose one of the following two methods):
- Solution A: You can set
LDAP_DIR
withluarocks config
manually, for exampleluarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1
; - 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;
- 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.- Solution A: You can set
To uninstall the Apache APISIX runtime, run:
# Uninstall apisix command
make uninstall
# Purge dependencies
make undepsNote: This operation will remove the files completely.
#
LTS version installation via Source Release PackageThe current LTS version of Apache APISIX is 2.13.3
.
To install this version, set APISIX_VERSION
in Installation via Source Release Package to this version and continue with the other steps.
#
Step 2: Install etcdThis 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
#
Step 3: Manage Apache APISIX ServerIn 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.
#
Initializing dependenciesRun the following command to initialize the NGINX configuration file and etcd.
# initialize NGINX config file and etcd
apisix init
#
Test the configuration fileRun 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
#
Start Apache APISIXRun the following command to start Apache APISIX.
# start Apache APISIX server
apisix start
#
Stop Apache APISIXBoth 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
#
Other operationsYou 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
#
Step 4: Run Test CasesTo run the test cases, run the steps outlined below.
Install
cpanminus
, the package manager forperl
.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)
Clone the latest source code locally by using the forked out version.
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 runmake test
command.Specify the NGINX binary path by running
TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t
.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
.
#
Troubleshoot testing#
Configuring NGINX pathThe 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
- Linux default installation path:
export PATH=/usr/local/openresty/nginx/sbin:$PATH
- MacOS default installation path via homebrew:
export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
- Linux default installation path:
#
Running a single test caseTo 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.
#
Step 5: Update Admin API token to Secure Apache APISIXYou 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"}
#
Step 6: Build OpenResty for Apache APISIXSome 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.
#
Step 7: Add Systemd unit file for Apache APISIXIf 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.