hf400159 commented on code in PR #6964: URL: https://github.com/apache/apisix/pull/6964#discussion_r861901455
########## docs/en/latest/how-to-build.md: ########## @@ -21,351 +25,218 @@ 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](./getting-started.md) guide for a quick walkthrough on running Apache APISIX. +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -## Step 1: Install Apache APISIX +This guide walks you through how you can install and run Apache APISIX in your environment. -Apache APISIX can be installed via the [RPM package](#installation-via-rpm-repository-centos), [Docker image](#installation-via-docker), [Helm Chart](#installation-via-helm-chart) or the [source release package](#installation-via-source-release-package). You can install via any one of these options. +Refer to the [Getting Started](./getting-started.md) guide for a quick walk-through on running Apache APISIX. -### Installation via RPM Repository (CentOS) +## Installing etcd -> This installation method is suitable for CentOS 7 and CentOS 8. +APISIX uses [etcd](https://github.com/etcd-io/etcd) to save and synchronize configuration. Before installing APISIX, you need to install etcd on your machine. -If the official OpenResty repository is **not installed yet**, the following command will help you automatically install both OpenResty and Apache APISIX repositories. +It would be installed automatically if you choose the Docker or Helm install method while installing APISIX. If you choose a different method or you need to install it manually, follow the steps shown below: -```shell -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. +<Tabs + groupId="os" + defaultValue="linux" + values={[ + {label: 'Linux', value: 'linux'}, + {label: 'macOS', value: 'mac'}, + ]}> +<TabItem value="linux"> ```shell -sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo +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 & ``` -Run the following commands to install the repository and Apache APISIX. +</TabItem> + +<TabItem value="mac"> ```shell -# View the information of the latest apisix package -sudo yum info -y apisix +brew install etcd +brew services start etcd +``` -# Will show the existing apisix packages -sudo yum --showduplicates list apisix +</TabItem> +</Tabs> -# Will install the latest apisix package -sudo yum install apisix +## Installing APISIX -# Will install a specified version (2.10.3 in this example) apisix package -sudo yum install apisix-2.10.3-0.el7 -``` +APISIX can be installed by the different methods listed below: -### Installation via RPM Offline Package (CentOS) +<Tabs + groupId="install-method" + defaultValue="docker" + values={[ + {label: 'Docker', value: 'docker'}, + {label: 'Helm', value: 'helm'}, + {label: 'RPM', value: 'rpm'}, + ]}> +<TabItem value="docker"> -First, download Apache APISIX offline RPM package to `./apisix` folder. +First clone the [apisix-docker](https://github.com/apache/apisix-docker) repository: ```shell -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 +git clone https://github.com/apache/apisix-docker.git +cd apisix-docker/example ``` -Then copy `./apisix` folder to the target host and run the following command to install. +Now, you can use `docker-compose` to start APISIX. + +<Tabs + groupId="cpu-arch" + defaultValue="x86" + values={[ + {label: 'x86', value: 'x86'}, + {label: 'ARM/M1', value: 'arm'}, + ]}> +<TabItem value="x86"> ```shell -sudo yum install ./apisix/*.rpm +docker-compose -p docker-apisix up -d ``` -### Installation via Docker - -Please refer to [Installing Apache APISIX with Docker](https://hub.docker.com/r/apache/apisix). - -### Installation via Helm Chart - -Please refer to [Installing Apache APISIX with Helm Chart](https://github.com/apache/apisix-helm-chart). - -### Installation via Source Release Package +</TabItem> -Note: if you want to package Apache APISIX for a specific platform, please refer to https://github.com/api7/apisix-build-tools and add the support there. -The instruction here is only for people who want to setup their Apache APISIX development environment. +<TabItem value="arm"> -Follow the steps below to install Apache APISIX via the source release package. - -1. Install dependencies - - ```shell - curl https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh -sL | bash - - ``` - -2. Create a directory named `apisix-2.13.0`. - - ```shell - APISIX_VERSION='2.13.0' - mkdir apisix-${APISIX_VERSION} - ``` - -3. Download the Apache APISIX source release package. - - ```shell - 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](https://apisix.apache.org/downloads/). The website also provides source packages for Apache APISIX, APISIX Dashboard, and APISIX Ingress Controller. - -4. Uncompress the Apache APISIX source release package. - - ```shell - tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION} - ``` - -5. Install the runtime dependent Lua libraries. - - ```shell - # Switch to the apisix-${APISIX_VERSION} directory - cd apisix-${APISIX_VERSION} - # Create dependencies - make deps - ``` - - **Note**: If you fail to install dependency packages using `make deps` and get an error message like `Could not find header file for LDAP/PCRE/openssl`, you can use this general method to solve problems. - - The general solution: `luarocks` supports custom compile-time dependency directories(from this [link](https://github.com/luarocks/luarocks/wiki/Config-file-format)). Use a third-party tool to install the missing package and add its installation directory to the `luarocks`'s variables table. This a general method which can be applied to macOS, Ubuntu, CentOS or other usual operating systems, and the specific solution for macOS are given here for reference only. - - The following is the solution of macOS, which is similar to that of other operating systems: +```shell +docker-compose -p docker-apisix -f docker-compose-arm64.yml up -d +``` - 1. Install `openldap` with `brew install openldap`; - 2. Locate installation directory with `brew --prefix openldap`; - 3. Add the path to the project configuration file(choose one of the following two methods): - 1. Solution A: You can set `LDAP_DIR` with `luarocks config` manually, for example `luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1`; - 2. Solution B: Of course, you can also choose to change the default configuration file of luarocks directly, execute the 'cat ~/.luarocks/config-5.1.lua' command, and then add the installation directory of 'openldap' to the file; - 3. Example as follows: - variables = { - LDAP_DIR = "/opt/homebrew/cellar/openldap/2.6.1", - LDAP_INCDIR = "/opt/homebrew/cellar/openldap/2.6.1/include", - } +</TabItem> +</Tabs> - `/opt/homebrew/cellar/openldap/` is default path to install openldap on macOS(Apple Silicon) using brew. - `/usr/local/opt/openldap/` is default path to install openldap on macOS(Intel) using brew. +</TabItem> -6. To uninstall the Apache APISIX runtime, run: +<TabItem value="helm"> - ```shell - # Purge dependencies - make undeps - ``` +To install APISIX via Helm, run: - **Note**: This operation will remove the files completely. +```shell +helm repo add apisix https://charts.apiseven.com +helm repo update +helm install apisix apisix/apisix --create-namespace --namespace apisix +``` -#### LTS version installation via Source Release Package +You can find other Helm charts on the [apisix-helm-chart](https://github.com/apache/apisix-helm-chart) repository. -The [current LTS version](https://apisix.apache.org/downloads/) of Apache APISIX is `2.13.0`. +</TabItem> -To install this version, set `APISIX_VERSION` in [Installation via Source Release Package](#installation-via-source-release-package) to this version and continue with the other steps. +<TabItem value="rpm"> -## Step 2: Install etcd +This installation method is suitable for CentOS 7 and Centos 8. -This step is required only if you haven't installed [etcd](https://github.com/etcd-io/etcd). +### Installation via RPM repository -Run the command below to install etcd via the binary in Linux: +If OpenResty is **not** installed, you can run the command below to install both OpenResty and APISIX repositories: ```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 & -``` - -Run the command below to install etcd in Mac: - -```shell -brew install etcd -# start etcd server -brew services start etcd +sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm ``` -## 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. +If OpenResty is installed, the command below will install the APISIX repositories: ```shell -# initialize NGINX config file and etcd -apisix init +sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo ``` -### 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. +Then, to install APISIX, run: ```shell -# generate `nginx.conf` from `config.yaml` and test it -apisix test +sudo yum install apisix ``` -### Start Apache APISIX +:::tip -Run the following command to start Apache APISIX. +You can also install a specific version of APISIX by specifying it: Review Comment: ```suggestion You can also install a specific version of APISIX by specifying it, The following example is to install the APISIX v2.13.1 LTS maintenance release: ``` Maybe we need to tell users that 2.13.1 is an LTS maintenance release. -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
