The Apache APISIX runtime environment requires dependencies on NGINX and etcd.
Before installing Apache APISIX, please install dependencies according to the operating system you are using. We provide the dependencies installation instructions for CentOS7, Fedora 31 & 32, Ubuntu 16.04 & 18.04, Debian 9 & 10, and MacOS, please refer to Install Dependencies for more details.
You can install Apache APISIX via RPM package, Docker, Helm Chart, and source release package. Please choose one from the following options.
This installation method is suitable for CentOS 7, please run the following command to install Apache APISIX.
sudo yum install -y https://github.com/apache/apisix/releases/download/2.8/apisix-2.8-0.x86_64.rpm
Please refer to: Installing Apache APISIX with Docker.
Please refer to: Installing Apache APISIX with Helm Chart.
apisix-2.8.mkdir apisix-2.8
wget https://downloads.apache.org/apisix/2.8/apache-apisix-2.8-src.tgz
You can also download the Apache APISIX Release source package from the Apache APISIX website. The Apache APISIX Official Website - Download Page also provides source packages for Apache APISIX, APISIX Dashboard and APISIX Ingress Controller.
tar zxvf apache-apisix-2.8-src.tgz -C apisix-2.8
# Switch to the apisix-2.8 directory cd apisix-2.8 # Create dependencies make deps
We can initialize dependencies, start service, and stop service with commands in the Apache APISIX directory, we can also view all commands and their corresponding functions with the make help command.
Run the following command to initialize the NGINX configuration file and etcd.
# initialize NGINX config file and etcd make init
Run the following command to start Apache APISIX.
# start Apache APISIX server make run
Both make quit and make stop can stop Apache APISIX. The main difference is that make quit stops Apache APISIX gracefully, while make stop stops Apache APISIX immediately.
It is recommended to use gracefully stop command make quit because it ensures that Apache APISIX will complete all the requests it has received before stopping down. In contrast, make stop will trigger a forced shutdown, it stops Apache APISIX immediately, in which case the incoming requests will not be processed before the shutdown.
The command to perform a graceful shutdown is shown below.
# stop Apache APISIX server gracefully make quit
The command to perform a forced shutdown is shown below.
# stop Apache APISIX server immediately make stop
Run the make help command to see the returned results and get commands and descriptions of other operations.
# more actions find by `help` make help
Install cpanminus, the package manager for perl.
Then install the test-nginx dependencies via cpanm:
sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
git clone command to clone the latest source code locally, please use the version we forked out：git clone https://github.com/iresty/test-nginx.git
prove command in perl and run the test case set in the /t directory.Append the current directory to the perl module directory: export PERL5LIB=.:$PERL5LIB, then run make test command.
Or you can specify the NGINX binary path by running this command: 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. :::
Configuring NGINX Path
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:$PATHexport PATH=/usr/local/openresty/nginx/sbin:$PATHexport PATH=/usr/local/opt/openresty/nginx/sbin:$PATHRun a Single Test Case
Run the specified test case using the following command.
prove -Itest-nginx/lib -r t/plugin/openid-connect.t
You need to modify the Admin API key to protect Apache APISIX.
Please modify apisix.admin_key in conf/config.yaml and restart the service as shown below.
apisix: # ... ... admin_key - name: "admin" key: abcdefghabcdefgh # Modify the original key to abcdefghabcdefgh role: admin
When we need to access the Admin API, we can use the key above, as shown below.
curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
The status code 200 in the returned result indicates that the access was successful, as shown below.
HTTP/1.1 200 OK Date: Fri, 28 Feb 2020 07:48:04 GMT Content-Type: text/plain ... ... {"node":{...},"action":"get"}
At this point, if the key you enter does not match the value of apisix.admin_key in conf/config.yaml, for example, we know that the correct key is abcdefghabcdefgh, but we enter an incorrect key, such as wrong-key, as shown below.
curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
The status code 401 in the returned result indicates that the access failed because the key entered was incorrect and did not pass authentication, triggering an Unauthorized error, as shown below.
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 OpenResty with this script.
If you are using CentOS 7 and you installed Apache APISIX via the RPM package in step 2, the configuration file is already in place automatically and you can run the following command directly.
systemctl start apisix
systemctl stop apisix
If you installed Apache APISIX by other methods, you can refer to the configuration file template for modification and put it in the /usr/lib/systemd/system/apisix.service path.