navendu-pottekkat commented on code in PR #7219: URL: https://github.com/apache/apisix/pull/7219#discussion_r897588156
########## docs/en/latest/building-apisix.md: ########## @@ -0,0 +1,276 @@ +--- +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. 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 and etcd, 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 +``` + +Whereas, the `apisix stop` command does a force shutdown and discards all pending requests. + +```shell +apisix stop +``` + +## Building OpenResty for APISIX + +Some features of APISIX requires additional Nginx modules to be introduced into OpenResty. + +To use these features, you need to build OpenResty. See [apisix-build-tools](https://github.com/api7/apisix-build-tools) for setting up your build environment and building OpenResty. + +## Running tests + +The steps below show how you can 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: Review Comment: Doesn't `make test` run all the tests? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@apisix.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
