[apisix] branch master updated: docs: create page for "Building APISIX" (#7219)

[sp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git


The following commit(s) were added to refs/heads/master by this push:
     new fdd1cac73 docs: create page for "Building APISIX" (#7219)
fdd1cac73 is described below

commit fdd1cac7328879cb848f93bba4d3bb37c50dcdc7
Author: Navendu Pottekkat <na...@gmail.com>
AuthorDate: Tue Jun 21 07:30:48 2022 +0530

    docs: create page for "Building APISIX" (#7219)
---
 docs/en/latest/building-apisix.md | 282 ++++++++++++++++++++++++++++++++++++++
 docs/en/latest/config.json        |  10 ++
 2 files changed, 292 insertions(+)

diff --git a/docs/en/latest/building-apisix.md b/docs/en/latest/building-apisix.md
new file mode 100644
index 000000000..fa08d72b5
--- /dev/null
+++ b/docs/en/latest/building-apisix.md
@@ -0,0 +1,282 @@
+---
+id: building-apisix
+title: Building APISIX from source
+keywords:
+  - API gateway
+  - Apache APISIX
+  - Code Contribution
+  - Building APISIX
+description: Guide for building and running APISIX locally for development.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+If you are looking to contribute to APISIX or setup a development environment, this guide is for you.
+
+If you are looking to install and run APISIX, check out the [Installation](/docs/apisix/how-to-build) docs.
+
+:::note
+
+If you want to build and package APISIX for a specific platform, see [apisix-build-tools](https://github.com/api7/apisix-build-tools).
+
+:::
+
+## Building APISIX from source
+
+To start, you have to install some dependencies. APISIX provides a handy script to get these installed:
+
+```shell
+curl https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh -sL | bash -
+```
+
+Then, create a directory and set the environment variable `APISIX_VERSION`:
+
+```shell
+APISIX_VERSION='2.14.1'
+mkdir apisix-${APISIX_VERSION}
+```
+
+You can now download the APISIX source code by running the command below:
+
+```shell
+wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-src.tgz
+```
+
+You can also download the source package from the [Downloads page](https://apisix.apache.org/downloads/). You will also find source packages for APISIX Dashboard and APISIX Ingress Controller.
+
+After you have downloaded the package, you can extract the files to the folder created previously:
+
+```shell
+tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}
+```
+
+Now, navigate to the directory, create dependencies, and install APISIX as shown below:
+
+```shell
+cd apisix-${APISIX_VERSION}
+make deps
+make install
+```
+
+This will install the runtime dependent Lua libraries and the `apisix` command.
+
+:::note
+
+If you get an error message like `Could not find header file for LDAP/PCRE/openssl` while running `make deps`, use this solution.
+
+`luarocks` supports custom compile-time dependencies (See: [Config file format](https://github.com/luarocks/luarocks/wiki/Config-file-format)). You can use a third-party tool to install the missing packages and add its installation directory to the `luarocks`' variables table. This method works on macOS, Ubuntu, CentOS, and other similar operating systems.
+
+The solution below is for macOS but it works similarly for other operating systems:
+
+1. Install `openldap` by running:
+
+   ```shell
+   brew install openldap
+   ```
+
+2. Locate the installation directory by running:
+
+   ```shell
+   brew --prefix openldap
+   ```
+
+3. Add this path to the project configuration file by any of the two methods shown below:
+   1. You can use the `luarocks config` command to set `LDAP_DIR`:
+
+      ```shell
+      luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1
+      ```
+
+   2. You can also change the default configuration file of `luarocks`. Open the file `~/.luaorcks/config-5.1.lua` and add the following:
+
+      ```shell
+      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 `openldap` is installed on Apple Silicon macOS machines. For Intel machines, the default path is  `/usr/local/opt/openldap/`.
+
+:::
+
+To uninstall the APISIX runtime, run:
+
+```shell
+make uninstall
+make undeps
+```
+
+:::danger
+
+This operation will remove the files completely.
+
+:::
+
+## Installing etcd
+
+APISIX uses [etcd](https://github.com/etcd-io/etcd) to save and synchronize configuration. Before running APISIX, you need to install etcd on your machine. Installation methods based on your operating system are mentioned below.
+
+<Tabs
+  groupId="os"
+  defaultValue="linux"
+  values={[
+    {label: 'Linux', value: 'linux'},
+    {label: 'macOS', value: 'mac'},
+  ]}>
+<TabItem value="linux">
+
+```shell
+ETCD_VERSION='3.4.18'
+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 &
+```
+
+</TabItem>
+
+<TabItem value="mac">
+
+```shell
+brew install etcd
+brew services start etcd
+```
+
+</TabItem>
+</Tabs>
+
+## Running and managing APISIX server
+
+To initialize the configuration file, within the APISIX directory, run:
+
+```shell
+apisix init
+```
+
+:::tip
+
+You can run `apisix help` to see a list of available commands.
+
+:::
+
+You can then test the created configuration file by running:
+
+```shell
+apisix test
+```
+
+Finally, you can run the command below to start APISIX:
+
+```shell
+apisix start
+```
+
+To stop APISIX, you can use either the `quit` or the `stop` subcommand.
+
+`apisix quit` will gracefully shutdown APISIX. It will ensure that all received requests are completed before stopping.
+
+```shell
+apisix quit
+```
+
+Where as, the `apisix stop` command does a force shutdown and discards all pending requests.
+
+```shell
+apisix stop
+```
+
+## Building runtime for APISIX
+
+Some features of APISIX requires additional Nginx modules to be introduced into OpenResty.
+
+To use these features, you need to build a custom distribution of OpenResty (apisix-base). See [apisix-build-tools](https://github.com/api7/apisix-build-tools) for setting up your build environment and building it.
+
+## Running tests
+
+The steps below show how to run the test cases for APISIX:
+
+1. Install [cpanminus](https://metacpan.org/pod/App::cpanminus#INSTALLATION), the package manager for Perl.
+2. Install the [test-nginx](https://github.com/openresty/test-nginx) dependencies with `cpanm`:
+
+   ```shell
+   sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+   ```
+
+3. Clone the test-nginx source code locally:
+
+   ```shell
+   git clone https://github.com/openresty/test-nginx.git
+   ```
+
+4. Append the current directory to Perl's module directory by running:
+
+   ```shell
+   export PERL5LIB=.:$PERL5LIB
+   ```
+
+   You can specify the Nginx binary path by running:
+
+   ```shell
+   TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t
+   ```
+
+5. Run the tests by running:
+
+   ```shell
+   make test
+   ```
+
+:::note
+
+Some tests rely on external services and system configuration modification. See [ci/linux_openresty_common_runner.sh](https://github.com/apache/apisix/blob/master/ci/linux_openresty_common_runner.sh) for a complete test environment build.
+
+:::
+
+### Troubleshooting
+
+These are some common troubleshooting steps for running APISIX test cases.
+
+#### Configuring Nginx path
+
+For the error `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`, ensure that OpenResty is set to the default Nginx and export the path as follows:
+
+- Linux default installation path:
+
+  ```shell
+  export PATH=/usr/local/openresty/nginx/sbin:$PATH
+  ```
+
+- macOS default installation path (view homebrew):
+
+  ```shell
+  export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
+  ```
+
+#### Running a specific test case
+
+To run a specific test case, use the command below:
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+See [testing framework](https://github.com/apache/apisix/blob/master/docs/en/latest/internal/testing-framework.md) for more details.
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 517fc0f1a..081ba7ec0 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -193,6 +193,16 @@
         }
       ]
     },
+    {
+      "type": "category",
+      "label": "Development",
+      "items": [
+        {
+          "type": "doc",
+          "id": "building-apisix"
+        }
+      ]
+    },
     {
       "type": "doc",
       "id": "FAQ"