Skip to main content
Version: 2.6

How to build Apache APISIX

1. Install dependencies#

The runtime environment for Apache APISIX requires Nginx and etcd.

So before installation, please follow the different operating systems install Dependencies.

2. Install Apache APISIX#

You can install Apache APISIX in a variety of ways, including source code packages, Docker, and Luarocks.

Installation via RPM package (CentOS 7)#

sudo yum install -y https://github.com/apache/apisix/releases/download/2.6/apisix-2.6-0.x86_64.rpm

Installation via Docker#

See https://hub.docker.com/r/apache/apisix

Installation via Helm Chart#

See https://github.com/apache/apisix-helm-chart

Installation via source release#

You need to download the Apache source release first:

$ mkdir apisix-2.6$ wget https://downloads.apache.org/apisix/2.6/apache-apisix-2.6-src.tgz$ tar zxvf apache-apisix-2.6-src.tgz -C apisix-2.6

Install the Lua libraries that the runtime depends on:

cd apisix-2.6make deps

3. Manage (start/stop) APISIX Server#

We can start the APISIX server by command make run in APISIX home folder, or we can stop APISIX server by command make stop.

# init nginx config file and etcd$ make init
# start APISIX server$ make run
# stop APISIX server$ make stop
# more actions find by `help`$ make helpMakefile rules:
    help:             Show Makefile rules    deps:             Installation dependencies    utils:            Installation tools    lint:             Lint Lua source code    init:             Initialize the runtime environment    run:              Start the apisix server    stop:             Stop the apisix server    verify:           Verify the configuration of apisix server    clean:            Remove generated files    reload:           Reload the apisix server    install:          Install the apisix (only for luarocks)    test:             Run the test case    license-check:    Check Lua source code for Apache License

Environment variable can be used to configure APISIX. Please take a look at conf/config.yaml to see how to do it.

4. Test#

  1. Install perl's package manager cpanminus first
  2. Then install test-nginx's dependencies via cpanm:：sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
  3. Clone source code：git clone https://github.com/iresty/test-nginx.git. Note that we should use our fork.
  4. Load the test-nginx library with perl's prove command and run the test cases in the /t directory:
    • Set PERL5LIB for perl module: export PERL5LIB=.:$PERL5LIB
    • Run the test cases: make test
    • To set the path of nginx to run the test cases: TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t
    • Some tests depend on external services and modified system configuration. If you want to setup a local CI environment, you can refer to ci/linux_openresty_common_runner.sh.

Troubleshoot Testing#

Set Nginx Path

  • If you run in to an issue Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf make sure to set openresty as default nginx. And export the path as below.
  • export PATH=/usr/local/openresty/nginx/sbin:$PATH
    • Linux default installation path:
      • export PATH=/usr/local/openresty/nginx/sbin:$PATH
    • OSx default installation path via homebrew:
      • export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH

Run Individual Test Cases

  • Use the following command to run test cases constrained to a file:
    • prove -Itest-nginx/lib -r t/plugin/openid-connect.t

5. Update Admin API token to protect Apache APISIX#

Changes the apisix.admin_key in the file conf/config.yaml and restart the service. Here is an example:

apisix:  # ... ...  admin_key    -      name: "admin"      key: abcdefghabcdefgh      role: admin

When calling the Admin API, key can be used as a token.

$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -iHTTP/1.1 200 OKDate: Fri, 28 Feb 2020 07:48:04 GMTContent-Type: text/plain... ...{"node":{...},"action":"get"}
$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh-invalid -iHTTP/1.1 401 UnauthorizedDate: Fri, 28 Feb 2020 08:17:58 GMTContent-Type: text/html... ...{"node":{...},"action":"get"}

6. Build OpenResty for APISIX#

Some features require you to build OpenResty with extra Nginx modules. If you need those features, you can build OpenResty with this build script.

7. Add systemd unit file for APISIX#

If you install APISIX with rpm package, the unit file is installed automatically, and you could directly do

$ systemctl start apisix$ systemctl stop apisix$ systemctl enable apisix

If installed in other methods, you could refer to the unit file template, modify if needed, and place it as /usr/lib/systemd/system/apisix.service.