how-to-build.md

title	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 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.

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

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 Docker

Please refer to Installing Apache APISIX with Docker.

Installation via Helm Chart

Please refer to Installing Apache APISIX with Helm Chart.

Installation via Source Release Package

Follow the steps below to install Apache APISIX via the source release package.

1. Create a directory named apisix-2.12.0.

APISIX_VERSION='2.12.0'
mkdir apisix-${APISIX_VERSION}

2. 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.

3. Unzip the Apache APISIX source release package.

tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}

4. 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 install

Note: If make deps fails with "install lualdap failed" with an error like Could not find header file for LDAP try the solution below.

Solution: Set LDAP_DIR with luarocks config manually. For example luarocks config variables.LDAP_DIR /usr/local/opt/openldap/.

5. To uninstall the Apache APISIX runtime, run:

   # Uninstall apisix command
   make uninstall
   # Purge dependencies
   make undeps

   Note: This operation will remove the files completely.

LTS version installation via Source Release Package

The current LTS version of Apache APISIX is 2.10.4.

To install this version, set APISIX_VERSION

Set APISIX_VERSION in Installation via Source Release Package to 2.10.4 and continue with the other steps.

Step 2: Install etcd

This step is required only if you haven't installed etcd.

Run the command below to install etcd via the binary.

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 &

Step 3: Manage Apache APISIX Server

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.

Initializing dependencies

Run the following command to initialize the NGINX configuration file and etcd.

# initialize NGINX config file and etcd
apisix init

Test the configuration file

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

Start Apache APISIX

Run the following command to start Apache APISIX.

# start Apache APISIX server
apisix start

Stop Apache APISIX

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

Other operations

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

Step 4: Run Test Cases

To run the test cases, run the steps outlined below.

1. Install cpanminus, the package manager for perl.

2. 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)

3. Clone the latest source code locally by using the forked out version.

git clone https://github.com/iresty/test-nginx.git

4. There are two ways to run the tests.

5. Append the current directory to the perl module directory: export PERL5LIB=.:$PERL5LIB and then run make test command.

6. 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. :::

Troubleshoot testing

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:$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

Running a single test case

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.

Step 5: Update Admin API token to Secure Apache APISIX

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"}

Step 6: Build OpenResty for Apache APISIX

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.

Step 7: Add Systemd unit file for Apache APISIX

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.