yzeng25 commented on code in PR #305: URL: https://github.com/apache/apisix-docker/pull/305#discussion_r877869106
########## README.md: ########## @@ -1,123 +1,147 @@ -**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.** +## What is APISIX -## How To Build Image +Apache APISIX is a dynamic, real-time, high-performance API gateway. APISIX provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more. -**The master branch is for the version of Apache APISIX 2.x. If you need a previous version, please build from the [v1.x](https://github.com/apache/apisix-docker/releases/tag/v1.x) tag.** +See [the APISIX website](https://apisix.apache.org/) for more info. -### Build an image from source +## Image variants -1. Build from release version: -```sh -# Assign Apache release version to variable `APISIX_VERSION`, for example: 2.9. -# The latest release version can be find at `https://github.com/apache/apisix/releases` +The APISIX image comes in many flavors, each designed for a specific use case. -export APISIX_VERSION=2.9 +`apisix:<version>` -# build alpine based image -make build-on-alpine +This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. -# build centos based image -make build-on-centos -``` +`apisix:<version>-alpine` -2. Build from master branch version, which has latest code(ONLY for the developer's convenience): -```sh -export APISIX_VERSION=master +This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general. -# build alpine based image -make build-on-alpine +This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use musl libc instead of glibc and friends, so software will often run into issues depending on the depth of their libc requirements/assumptions. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images. Review Comment: ```suggestion This variant is useful when storage compatibility is your primary concern. The main caveat to note is that it does use `musl libc` instead of `glibc` and friends, so software will often run into issues depending on the depth of their `libc requirements/assumptions`. See this Hacker News comment thread for more discussion of the issues that might arise and some advantages and disadvantagess comparisons of using Alpine-based images. ``` ########## README.md: ########## @@ -1,123 +1,147 @@ -**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.** +## What is APISIX -## How To Build Image +Apache APISIX is a dynamic, real-time, high-performance API gateway. APISIX provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more. -**The master branch is for the version of Apache APISIX 2.x. If you need a previous version, please build from the [v1.x](https://github.com/apache/apisix-docker/releases/tag/v1.x) tag.** +See [the APISIX website](https://apisix.apache.org/) for more info. -### Build an image from source +## Image variants -1. Build from release version: -```sh -# Assign Apache release version to variable `APISIX_VERSION`, for example: 2.9. -# The latest release version can be find at `https://github.com/apache/apisix/releases` +The APISIX image comes in many flavors, each designed for a specific use case. -export APISIX_VERSION=2.9 +`apisix:<version>` -# build alpine based image -make build-on-alpine +This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. -# build centos based image -make build-on-centos -``` +`apisix:<version>-alpine` -2. Build from master branch version, which has latest code(ONLY for the developer's convenience): -```sh -export APISIX_VERSION=master +This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general. Review Comment: ```suggestion This image is based on the popular Alpine Linux project. Since Alpine Linux is much smaller than most distribution Linux images (~5MB), you can build smaller images with it. ``` ########## README.md: ########## @@ -1,123 +1,147 @@ -**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.** +## What is APISIX -## How To Build Image +Apache APISIX is a dynamic, real-time, high-performance API gateway. APISIX provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more. -**The master branch is for the version of Apache APISIX 2.x. If you need a previous version, please build from the [v1.x](https://github.com/apache/apisix-docker/releases/tag/v1.x) tag.** +See [the APISIX website](https://apisix.apache.org/) for more info. -### Build an image from source +## Image variants -1. Build from release version: -```sh -# Assign Apache release version to variable `APISIX_VERSION`, for example: 2.9. -# The latest release version can be find at `https://github.com/apache/apisix/releases` +The APISIX image comes in many flavors, each designed for a specific use case. -export APISIX_VERSION=2.9 +`apisix:<version>` -# build alpine based image -make build-on-alpine +This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. Review Comment: ```suggestion This is the default image. If you are unsure about what your needs are, this is your go-to option.you can use it as a throw away container (mount your source code and start the container to start your applications), as well as the base to build other images of. ``` ########## README.md: ########## @@ -1,123 +1,147 @@ -**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.** +## What is APISIX -## How To Build Image +Apache APISIX is a dynamic, real-time, high-performance API gateway. APISIX provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more. -**The master branch is for the version of Apache APISIX 2.x. If you need a previous version, please build from the [v1.x](https://github.com/apache/apisix-docker/releases/tag/v1.x) tag.** +See [the APISIX website](https://apisix.apache.org/) for more info. -### Build an image from source +## Image variants -1. Build from release version: -```sh -# Assign Apache release version to variable `APISIX_VERSION`, for example: 2.9. -# The latest release version can be find at `https://github.com/apache/apisix/releases` +The APISIX image comes in many flavors, each designed for a specific use case. -export APISIX_VERSION=2.9 +`apisix:<version>` -# build alpine based image -make build-on-alpine +This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. -# build centos based image -make build-on-centos -``` +`apisix:<version>-alpine` -2. Build from master branch version, which has latest code(ONLY for the developer's convenience): -```sh -export APISIX_VERSION=master +This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general. -# build alpine based image -make build-on-alpine +This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use musl libc instead of glibc and friends, so software will often run into issues depending on the depth of their libc requirements/assumptions. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images. -# build centos based image -make build-on-centos -``` +To minimize image size, it's uncommon for additional related tools (such as git or bash) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the alpine image description for examples of how to install packages if you are unfamiliar). -3. Build from local code: -```sh -# To copy apisix into image, we need to include it in build context -cp -r <APISIX-PATH> ./apisix +`apisix:<version>-centos` -export APISIX_PATH=./apisix -make build-on-alpine-local +This image is based on the CentOS Linux project, available in the centos official image. CentOS is derived from the sources of Red Hat Enterprise Linux (RHEL). It is considered to be a more stable distribution compared to Ubuntu, mainly because package updates are less frequent. -# Might need root privilege if encounter "error checking context: 'can't start'" -``` +The variant is useful when your primary concern is stability and want to minimize the number of image updates. The applications running on CentOS don't need to be updated as often owing to the lesser frequency of its updates, and the cost is also very less than compared with other Linux essentials. -**Note:** For Chinese, the following command is always recommended. The additional build argument `ENABLE_PROXY=true` will enable proxy to definitely accelerate the progress. +## How to run APISIX -```sh -$ make build-on-alpine-cn -``` +APISIX can be run using docker compose or using the `all-in-one` image. It is recommended to use docker compose to run APISIX, as `all-in-one` deploys all dependencies in a single container and should be used for quick testing. +If you want to manually deploy services, please refer to [this guide](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/manual.md). -4. Build apisix-dashboard from release version: +### Run APISIX with docker-compose -```sh -# Assign the release version of Apache APISIX Dashboard to variable `APISIX_DASHBOARD_VERSION`, for example: 2.10. -# The latest release version can be found at `https://github.com/apache/apisix-dashboard/releases` +[The apisix-docker repo](https://github.com/apache/apisix-docker/blob/master/example) contains an example docker-compose file and config files that show how to start APISIX using docker compose. For the sake of completeness, this docker-compose file also starts [APISIX dashboard](https://hub.docker.com/r/apache/apisix-dashboard), which is a frontend interface that makes it easy for users to interact with APISIX, along with Prometheus and Grafana. -export APISIX_DASHBOARD_VERSION=2.10 +To try out this example: -# build alpine based image -make build-dashboard-alpine +1. Clone the [repo](https://github.com/apache/apisix-docker) and cd into the root folder. + +2. Start APISIX. + ``` + cd example -# build centos based image -make build-dashboard-centos -``` + docker-compose -p docker-apisix up -d + ``` -### Manual deploy apisix via docker +3. Check if APISIX is running properly by running this command and checking the response. + ``` + curl "http://127.0.0.1:9080/apisix/admin/services/"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' + ``` + The response indicates that apisix is running successfully: + ``` + { + "count":0, + "action":"get", + "node":{ + "key":"/apisix/services", + "nodes":[], + "dir":true + } + } + ``` -[Manual deploy](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/manual.md) +The [example docker compose file](https://github.com/apache/apisix-docker/blob/master/example/docker-compose.yml) defines several services: `apisix-dashboard, apisix, etcd, web1, web2, prometheus, and grafana`: +- `apisix-dashboard, apisix, etcd` are the essential services required for starting apisix-dashboard, apisix, etcd. Review Comment: ```suggestion - `apisix-dashboard, apisix, etcd` are the essential services required for starting apisix-dashboard, apisix, and etcd. ``` ########## README.md: ########## @@ -1,123 +1,147 @@ -**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.** +## What is APISIX -## How To Build Image +Apache APISIX is a dynamic, real-time, high-performance API gateway. APISIX provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more. -**The master branch is for the version of Apache APISIX 2.x. If you need a previous version, please build from the [v1.x](https://github.com/apache/apisix-docker/releases/tag/v1.x) tag.** +See [the APISIX website](https://apisix.apache.org/) for more info. -### Build an image from source +## Image variants -1. Build from release version: -```sh -# Assign Apache release version to variable `APISIX_VERSION`, for example: 2.9. -# The latest release version can be find at `https://github.com/apache/apisix/releases` +The APISIX image comes in many flavors, each designed for a specific use case. -export APISIX_VERSION=2.9 +`apisix:<version>` -# build alpine based image -make build-on-alpine +This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. -# build centos based image -make build-on-centos -``` +`apisix:<version>-alpine` -2. Build from master branch version, which has latest code(ONLY for the developer's convenience): -```sh -export APISIX_VERSION=master +This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general. -# build alpine based image -make build-on-alpine +This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use musl libc instead of glibc and friends, so software will often run into issues depending on the depth of their libc requirements/assumptions. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images. Review Comment: would be nice to have a "Hacker News" hyperlink here. ########## README.md: ########## @@ -1,123 +1,147 @@ -**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.** +## What is APISIX -## How To Build Image +Apache APISIX is a dynamic, real-time, high-performance API gateway. APISIX provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more. -**The master branch is for the version of Apache APISIX 2.x. If you need a previous version, please build from the [v1.x](https://github.com/apache/apisix-docker/releases/tag/v1.x) tag.** +See [the APISIX website](https://apisix.apache.org/) for more info. -### Build an image from source +## Image variants -1. Build from release version: -```sh -# Assign Apache release version to variable `APISIX_VERSION`, for example: 2.9. -# The latest release version can be find at `https://github.com/apache/apisix/releases` +The APISIX image comes in many flavors, each designed for a specific use case. -export APISIX_VERSION=2.9 +`apisix:<version>` -# build alpine based image -make build-on-alpine +This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. -# build centos based image -make build-on-centos -``` +`apisix:<version>-alpine` -2. Build from master branch version, which has latest code(ONLY for the developer's convenience): -```sh -export APISIX_VERSION=master +This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general. -# build alpine based image -make build-on-alpine +This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use musl libc instead of glibc and friends, so software will often run into issues depending on the depth of their libc requirements/assumptions. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images. -# build centos based image -make build-on-centos -``` +To minimize image size, it's uncommon for additional related tools (such as git or bash) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the alpine image description for examples of how to install packages if you are unfamiliar). -3. Build from local code: -```sh -# To copy apisix into image, we need to include it in build context -cp -r <APISIX-PATH> ./apisix +`apisix:<version>-centos` -export APISIX_PATH=./apisix -make build-on-alpine-local +This image is based on the CentOS Linux project, available in the centos official image. CentOS is derived from the sources of Red Hat Enterprise Linux (RHEL). It is considered to be a more stable distribution compared to Ubuntu, mainly because package updates are less frequent. -# Might need root privilege if encounter "error checking context: 'can't start'" -``` +The variant is useful when your primary concern is stability and want to minimize the number of image updates. The applications running on CentOS don't need to be updated as often owing to the lesser frequency of its updates, and the cost is also very less than compared with other Linux essentials. -**Note:** For Chinese, the following command is always recommended. The additional build argument `ENABLE_PROXY=true` will enable proxy to definitely accelerate the progress. +## How to run APISIX -```sh -$ make build-on-alpine-cn -``` +APISIX can be run using docker compose or using the `all-in-one` image. It is recommended to use docker compose to run APISIX, as `all-in-one` deploys all dependencies in a single container and should be used for quick testing. +If you want to manually deploy services, please refer to [this guide](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/manual.md). -4. Build apisix-dashboard from release version: +### Run APISIX with docker-compose -```sh -# Assign the release version of Apache APISIX Dashboard to variable `APISIX_DASHBOARD_VERSION`, for example: 2.10. -# The latest release version can be found at `https://github.com/apache/apisix-dashboard/releases` +[The apisix-docker repo](https://github.com/apache/apisix-docker/blob/master/example) contains an example docker-compose file and config files that show how to start APISIX using docker compose. For the sake of completeness, this docker-compose file also starts [APISIX dashboard](https://hub.docker.com/r/apache/apisix-dashboard), which is a frontend interface that makes it easy for users to interact with APISIX, along with Prometheus and Grafana. -export APISIX_DASHBOARD_VERSION=2.10 +To try out this example: -# build alpine based image -make build-dashboard-alpine +1. Clone the [repo](https://github.com/apache/apisix-docker) and cd into the root folder. + +2. Start APISIX. + ``` + cd example -# build centos based image -make build-dashboard-centos -``` + docker-compose -p docker-apisix up -d + ``` -### Manual deploy apisix via docker +3. Check if APISIX is running properly by running this command and checking the response. + ``` + curl "http://127.0.0.1:9080/apisix/admin/services/"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' + ``` + The response indicates that apisix is running successfully: + ``` + { + "count":0, + "action":"get", + "node":{ + "key":"/apisix/services", + "nodes":[], + "dir":true + } + } + ``` -[Manual deploy](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/manual.md) +The [example docker compose file](https://github.com/apache/apisix-docker/blob/master/example/docker-compose.yml) defines several services: `apisix-dashboard, apisix, etcd, web1, web2, prometheus, and grafana`: +- `apisix-dashboard, apisix, etcd` are the essential services required for starting apisix-dashboard, apisix, etcd. +- `web1, web2` are sample backend services used for testing purposes. They use nginx-alpine image. +- `prometheus, grafana` are services used for exposing metrics of the running services. -### QuickStart via docker-compose +All the services are configured by mounting external configuration files onto the containers: [/apisix_conf/conf.yaml](https://github.com/apache/apisix-docker/blob/master/example/apisix_conf/config.yaml) defines the configs for apisix. Similarly, configs for etcd, prometheus, and grafana are located in [/etcd_conf/etcd.conf.yml](https://github.com/apache/apisix-docker/blob/master/example/etcd_conf/etcd.conf.yml), [/prometheus_conf/prometheus.yml](https://github.com/apache/apisix-docker/blob/master/example/prometheus_conf/prometheus.yml), and [/grafana_conf/config](https://github.com/apache/apisix-docker/tree/master/example/grafana_conf/config) respectively. -**start all modules with docker-compose** +If you want to use a config file located at a different path, you need to modify the local config file path in the `volumes` entry under the corresponding service. -```sh -cd example -docker-compose -p docker-apisix up -d -``` +### Run APISIX with all-in-one command -You can refer to [the docker-compose example](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/example.md) for more try. +A quick way to get APISIX running on alpine is to use the `all-in-one` docker image, which deploys all dependencies in one Docker container. You can find the dockerfile [here](https://github.com/apache/apisix-docker/blob/master/all-in-one/apisix/Dockerfile). The image utilizes [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/), building APISIX layer and etcd layer first, then copying the nesessary artifacts to the alpine layer. -### Quick test with all dependencies in one Docker container +To try out this example: -* All in one Docker container for Apache APISIX +1. Clone the [apisix-docker repo](https://github.com/apache/apisix-docker/blob/master) and cd into the root folder. -```sh -make build-all-in-one +2. `make build-all-in-one` to build the `all-in-one` image. -# launch APISIX container -docker run -d \ --p 9080:9080 -p 9091:9091 -p 2379:2379 \ --v `pwd`/all-in-one/apisix/config.yaml:/usr/local/apisix/conf/config.yaml \ -apache/apisix:whole -``` +3. Launch the APISIX container: + + ```sh + docker run -d \ + -p 9080:9080 -p 9091:9091 -p 2379:2379 \ + -v `pwd`/all-in-one/apisix/config.yaml:/usr/local/apisix/conf/config.yaml \ + apache/apisix:whole + ``` + +4. Check if APISIX is running properly by running this command and checking the response. + ``` + curl "http://127.0.0.1:9080/apisix/admin/services/"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' + ``` + The response indicates that apisix is running successfully: + ``` + { + "count":0, + "action":"get", + "node":{ + "key":"/apisix/services", + "nodes":[], + "dir":true + } + } Review Comment: add ``` after line 108 to surround the end of code block. ########## README.md: ########## @@ -1,123 +1,147 @@ -**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.** +## What is APISIX -## How To Build Image +Apache APISIX is a dynamic, real-time, high-performance API gateway. APISIX provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more. -**The master branch is for the version of Apache APISIX 2.x. If you need a previous version, please build from the [v1.x](https://github.com/apache/apisix-docker/releases/tag/v1.x) tag.** +See [the APISIX website](https://apisix.apache.org/) for more info. -### Build an image from source +## Image variants -1. Build from release version: -```sh -# Assign Apache release version to variable `APISIX_VERSION`, for example: 2.9. -# The latest release version can be find at `https://github.com/apache/apisix/releases` +The APISIX image comes in many flavors, each designed for a specific use case. -export APISIX_VERSION=2.9 +`apisix:<version>` -# build alpine based image -make build-on-alpine +This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. -# build centos based image -make build-on-centos -``` +`apisix:<version>-alpine` -2. Build from master branch version, which has latest code(ONLY for the developer's convenience): -```sh -export APISIX_VERSION=master +This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general. -# build alpine based image -make build-on-alpine +This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use musl libc instead of glibc and friends, so software will often run into issues depending on the depth of their libc requirements/assumptions. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images. -# build centos based image -make build-on-centos -``` +To minimize image size, it's uncommon for additional related tools (such as git or bash) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the alpine image description for examples of how to install packages if you are unfamiliar). -3. Build from local code: -```sh -# To copy apisix into image, we need to include it in build context -cp -r <APISIX-PATH> ./apisix +`apisix:<version>-centos` -export APISIX_PATH=./apisix -make build-on-alpine-local +This image is based on the CentOS Linux project, available in the centos official image. CentOS is derived from the sources of Red Hat Enterprise Linux (RHEL). It is considered to be a more stable distribution compared to Ubuntu, mainly because package updates are less frequent. -# Might need root privilege if encounter "error checking context: 'can't start'" -``` +The variant is useful when your primary concern is stability and want to minimize the number of image updates. The applications running on CentOS don't need to be updated as often owing to the lesser frequency of its updates, and the cost is also very less than compared with other Linux essentials. -**Note:** For Chinese, the following command is always recommended. The additional build argument `ENABLE_PROXY=true` will enable proxy to definitely accelerate the progress. +## How to run APISIX -```sh -$ make build-on-alpine-cn -``` +APISIX can be run using docker compose or using the `all-in-one` image. It is recommended to use docker compose to run APISIX, as `all-in-one` deploys all dependencies in a single container and should be used for quick testing. +If you want to manually deploy services, please refer to [this guide](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/manual.md). -4. Build apisix-dashboard from release version: +### Run APISIX with docker-compose -```sh -# Assign the release version of Apache APISIX Dashboard to variable `APISIX_DASHBOARD_VERSION`, for example: 2.10. -# The latest release version can be found at `https://github.com/apache/apisix-dashboard/releases` +[The apisix-docker repo](https://github.com/apache/apisix-docker/blob/master/example) contains an example docker-compose file and config files that show how to start APISIX using docker compose. For the sake of completeness, this docker-compose file also starts [APISIX dashboard](https://hub.docker.com/r/apache/apisix-dashboard), which is a frontend interface that makes it easy for users to interact with APISIX, along with Prometheus and Grafana. -export APISIX_DASHBOARD_VERSION=2.10 +To try out this example: -# build alpine based image -make build-dashboard-alpine +1. Clone the [repo](https://github.com/apache/apisix-docker) and cd into the root folder. + +2. Start APISIX. + ``` + cd example -# build centos based image -make build-dashboard-centos -``` + docker-compose -p docker-apisix up -d + ``` -### Manual deploy apisix via docker +3. Check if APISIX is running properly by running this command and checking the response. + ``` + curl "http://127.0.0.1:9080/apisix/admin/services/"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' + ``` + The response indicates that apisix is running successfully: + ``` + { + "count":0, + "action":"get", + "node":{ + "key":"/apisix/services", + "nodes":[], + "dir":true + } + } + ``` -[Manual deploy](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/manual.md) +The [example docker compose file](https://github.com/apache/apisix-docker/blob/master/example/docker-compose.yml) defines several services: `apisix-dashboard, apisix, etcd, web1, web2, prometheus, and grafana`: +- `apisix-dashboard, apisix, etcd` are the essential services required for starting apisix-dashboard, apisix, etcd. +- `web1, web2` are sample backend services used for testing purposes. They use nginx-alpine image. +- `prometheus, grafana` are services used for exposing metrics of the running services. -### QuickStart via docker-compose +All the services are configured by mounting external configuration files onto the containers: [/apisix_conf/conf.yaml](https://github.com/apache/apisix-docker/blob/master/example/apisix_conf/config.yaml) defines the configs for apisix. Similarly, configs for etcd, prometheus, and grafana are located in [/etcd_conf/etcd.conf.yml](https://github.com/apache/apisix-docker/blob/master/example/etcd_conf/etcd.conf.yml), [/prometheus_conf/prometheus.yml](https://github.com/apache/apisix-docker/blob/master/example/prometheus_conf/prometheus.yml), and [/grafana_conf/config](https://github.com/apache/apisix-docker/tree/master/example/grafana_conf/config) respectively. -**start all modules with docker-compose** +If you want to use a config file located at a different path, you need to modify the local config file path in the `volumes` entry under the corresponding service. -```sh -cd example -docker-compose -p docker-apisix up -d -``` +### Run APISIX with all-in-one command -You can refer to [the docker-compose example](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/example.md) for more try. +A quick way to get APISIX running on alpine is to use the `all-in-one` docker image, which deploys all dependencies in one Docker container. You can find the dockerfile [here](https://github.com/apache/apisix-docker/blob/master/all-in-one/apisix/Dockerfile). The image utilizes [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/), building APISIX layer and etcd layer first, then copying the nesessary artifacts to the alpine layer. -### Quick test with all dependencies in one Docker container +To try out this example: -* All in one Docker container for Apache APISIX +1. Clone the [apisix-docker repo](https://github.com/apache/apisix-docker/blob/master) and cd into the root folder. -```sh -make build-all-in-one +2. `make build-all-in-one` to build the `all-in-one` image. -# launch APISIX container -docker run -d \ --p 9080:9080 -p 9091:9091 -p 2379:2379 \ --v `pwd`/all-in-one/apisix/config.yaml:/usr/local/apisix/conf/config.yaml \ -apache/apisix:whole -``` +3. Launch the APISIX container: + + ```sh + docker run -d \ + -p 9080:9080 -p 9091:9091 -p 2379:2379 \ + -v `pwd`/all-in-one/apisix/config.yaml:/usr/local/apisix/conf/config.yaml \ + apache/apisix:whole + ``` + +4. Check if APISIX is running properly by running this command and checking the response. + ``` + curl "http://127.0.0.1:9080/apisix/admin/services/"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' + ``` + The response indicates that apisix is running successfully: + ``` + { + "count":0, + "action":"get", + "node":{ + "key":"/apisix/services", + "nodes":[], + "dir":true + } + } Review Comment: ```suggestion } "```" ``` ########## README.md: ########## @@ -1,123 +1,147 @@ -**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.** +## What is APISIX -## How To Build Image +Apache APISIX is a dynamic, real-time, high-performance API gateway. APISIX provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more. -**The master branch is for the version of Apache APISIX 2.x. If you need a previous version, please build from the [v1.x](https://github.com/apache/apisix-docker/releases/tag/v1.x) tag.** +See [the APISIX website](https://apisix.apache.org/) for more info. -### Build an image from source +## Image variants -1. Build from release version: -```sh -# Assign Apache release version to variable `APISIX_VERSION`, for example: 2.9. -# The latest release version can be find at `https://github.com/apache/apisix/releases` +The APISIX image comes in many flavors, each designed for a specific use case. -export APISIX_VERSION=2.9 +`apisix:<version>` -# build alpine based image -make build-on-alpine +This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. -# build centos based image -make build-on-centos -``` +`apisix:<version>-alpine` -2. Build from master branch version, which has latest code(ONLY for the developer's convenience): -```sh -export APISIX_VERSION=master +This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general. -# build alpine based image -make build-on-alpine +This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use musl libc instead of glibc and friends, so software will often run into issues depending on the depth of their libc requirements/assumptions. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images. -# build centos based image -make build-on-centos -``` +To minimize image size, it's uncommon for additional related tools (such as git or bash) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the alpine image description for examples of how to install packages if you are unfamiliar). Review Comment: ```suggestion To minimize the image size, additional tools, such as git and bash, are not included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the alpine image description). ``` ########## README.md: ########## @@ -1,123 +1,147 @@ -**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.** +## What is APISIX -## How To Build Image +Apache APISIX is a dynamic, real-time, high-performance API gateway. APISIX provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more. -**The master branch is for the version of Apache APISIX 2.x. If you need a previous version, please build from the [v1.x](https://github.com/apache/apisix-docker/releases/tag/v1.x) tag.** +See [the APISIX website](https://apisix.apache.org/) for more info. -### Build an image from source +## Image variants -1. Build from release version: -```sh -# Assign Apache release version to variable `APISIX_VERSION`, for example: 2.9. -# The latest release version can be find at `https://github.com/apache/apisix/releases` +The APISIX image comes in many flavors, each designed for a specific use case. -export APISIX_VERSION=2.9 +`apisix:<version>` -# build alpine based image -make build-on-alpine +This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. -# build centos based image -make build-on-centos -``` +`apisix:<version>-alpine` -2. Build from master branch version, which has latest code(ONLY for the developer's convenience): -```sh -export APISIX_VERSION=master +This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general. -# build alpine based image -make build-on-alpine +This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use musl libc instead of glibc and friends, so software will often run into issues depending on the depth of their libc requirements/assumptions. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images. -# build centos based image -make build-on-centos -``` +To minimize image size, it's uncommon for additional related tools (such as git or bash) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the alpine image description for examples of how to install packages if you are unfamiliar). -3. Build from local code: -```sh -# To copy apisix into image, we need to include it in build context -cp -r <APISIX-PATH> ./apisix +`apisix:<version>-centos` -export APISIX_PATH=./apisix -make build-on-alpine-local +This image is based on the CentOS Linux project, available in the centos official image. CentOS is derived from the sources of Red Hat Enterprise Linux (RHEL). It is considered to be a more stable distribution compared to Ubuntu, mainly because package updates are less frequent. -# Might need root privilege if encounter "error checking context: 'can't start'" -``` +The variant is useful when your primary concern is stability and want to minimize the number of image updates. The applications running on CentOS don't need to be updated as often owing to the lesser frequency of its updates, and the cost is also very less than compared with other Linux essentials. -**Note:** For Chinese, the following command is always recommended. The additional build argument `ENABLE_PROXY=true` will enable proxy to definitely accelerate the progress. +## How to run APISIX -```sh -$ make build-on-alpine-cn -``` +APISIX can be run using docker compose or using the `all-in-one` image. It is recommended to use docker compose to run APISIX, as `all-in-one` deploys all dependencies in a single container and should be used for quick testing. +If you want to manually deploy services, please refer to [this guide](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/manual.md). -4. Build apisix-dashboard from release version: +### Run APISIX with docker-compose -```sh -# Assign the release version of Apache APISIX Dashboard to variable `APISIX_DASHBOARD_VERSION`, for example: 2.10. -# The latest release version can be found at `https://github.com/apache/apisix-dashboard/releases` +[The apisix-docker repo](https://github.com/apache/apisix-docker/blob/master/example) contains an example docker-compose file and config files that show how to start APISIX using docker compose. For the sake of completeness, this docker-compose file also starts [APISIX dashboard](https://hub.docker.com/r/apache/apisix-dashboard), which is a frontend interface that makes it easy for users to interact with APISIX, along with Prometheus and Grafana. -export APISIX_DASHBOARD_VERSION=2.10 +To try out this example: -# build alpine based image -make build-dashboard-alpine +1. Clone the [repo](https://github.com/apache/apisix-docker) and cd into the root folder. + +2. Start APISIX. + ``` + cd example -# build centos based image -make build-dashboard-centos -``` + docker-compose -p docker-apisix up -d + ``` -### Manual deploy apisix via docker +3. Check if APISIX is running properly by running this command and checking the response. + ``` + curl "http://127.0.0.1:9080/apisix/admin/services/"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' + ``` + The response indicates that apisix is running successfully: + ``` + { + "count":0, + "action":"get", + "node":{ + "key":"/apisix/services", + "nodes":[], + "dir":true + } + } + ``` -[Manual deploy](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/manual.md) +The [example docker compose file](https://github.com/apache/apisix-docker/blob/master/example/docker-compose.yml) defines several services: `apisix-dashboard, apisix, etcd, web1, web2, prometheus, and grafana`: +- `apisix-dashboard, apisix, etcd` are the essential services required for starting apisix-dashboard, apisix, etcd. +- `web1, web2` are sample backend services used for testing purposes. They use nginx-alpine image. +- `prometheus, grafana` are services used for exposing metrics of the running services. -### QuickStart via docker-compose +All the services are configured by mounting external configuration files onto the containers: [/apisix_conf/conf.yaml](https://github.com/apache/apisix-docker/blob/master/example/apisix_conf/config.yaml) defines the configs for apisix. Similarly, configs for etcd, prometheus, and grafana are located in [/etcd_conf/etcd.conf.yml](https://github.com/apache/apisix-docker/blob/master/example/etcd_conf/etcd.conf.yml), [/prometheus_conf/prometheus.yml](https://github.com/apache/apisix-docker/blob/master/example/prometheus_conf/prometheus.yml), and [/grafana_conf/config](https://github.com/apache/apisix-docker/tree/master/example/grafana_conf/config) respectively. -**start all modules with docker-compose** +If you want to use a config file located at a different path, you need to modify the local config file path in the `volumes` entry under the corresponding service. -```sh -cd example -docker-compose -p docker-apisix up -d -``` +### Run APISIX with all-in-one command -You can refer to [the docker-compose example](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/example.md) for more try. +A quick way to get APISIX running on alpine is to use the `all-in-one` docker image, which deploys all dependencies in one Docker container. You can find the dockerfile [here](https://github.com/apache/apisix-docker/blob/master/all-in-one/apisix/Dockerfile). The image utilizes [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/), building APISIX layer and etcd layer first, then copying the nesessary artifacts to the alpine layer. -### Quick test with all dependencies in one Docker container +To try out this example: -* All in one Docker container for Apache APISIX +1. Clone the [apisix-docker repo](https://github.com/apache/apisix-docker/blob/master) and cd into the root folder. Review Comment: ditto ########## README.md: ########## @@ -1,123 +1,147 @@ -**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.** +## What is APISIX -## How To Build Image +Apache APISIX is a dynamic, real-time, high-performance API gateway. APISIX provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more. -**The master branch is for the version of Apache APISIX 2.x. If you need a previous version, please build from the [v1.x](https://github.com/apache/apisix-docker/releases/tag/v1.x) tag.** +See [the APISIX website](https://apisix.apache.org/) for more info. -### Build an image from source +## Image variants -1. Build from release version: -```sh -# Assign Apache release version to variable `APISIX_VERSION`, for example: 2.9. -# The latest release version can be find at `https://github.com/apache/apisix/releases` +The APISIX image comes in many flavors, each designed for a specific use case. -export APISIX_VERSION=2.9 +`apisix:<version>` -# build alpine based image -make build-on-alpine +This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. -# build centos based image -make build-on-centos -``` +`apisix:<version>-alpine` -2. Build from master branch version, which has latest code(ONLY for the developer's convenience): -```sh -export APISIX_VERSION=master +This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general. -# build alpine based image -make build-on-alpine +This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use musl libc instead of glibc and friends, so software will often run into issues depending on the depth of their libc requirements/assumptions. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images. -# build centos based image -make build-on-centos -``` +To minimize image size, it's uncommon for additional related tools (such as git or bash) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the alpine image description for examples of how to install packages if you are unfamiliar). -3. Build from local code: -```sh -# To copy apisix into image, we need to include it in build context -cp -r <APISIX-PATH> ./apisix +`apisix:<version>-centos` -export APISIX_PATH=./apisix -make build-on-alpine-local +This image is based on the CentOS Linux project, available in the centos official image. CentOS is derived from the sources of Red Hat Enterprise Linux (RHEL). It is considered to be a more stable distribution compared to Ubuntu, mainly because package updates are less frequent. -# Might need root privilege if encounter "error checking context: 'can't start'" -``` +The variant is useful when your primary concern is stability and want to minimize the number of image updates. The applications running on CentOS don't need to be updated as often owing to the lesser frequency of its updates, and the cost is also very less than compared with other Linux essentials. -**Note:** For Chinese, the following command is always recommended. The additional build argument `ENABLE_PROXY=true` will enable proxy to definitely accelerate the progress. +## How to run APISIX -```sh -$ make build-on-alpine-cn -``` +APISIX can be run using docker compose or using the `all-in-one` image. It is recommended to use docker compose to run APISIX, as `all-in-one` deploys all dependencies in a single container and should be used for quick testing. +If you want to manually deploy services, please refer to [this guide](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/manual.md). -4. Build apisix-dashboard from release version: +### Run APISIX with docker-compose -```sh -# Assign the release version of Apache APISIX Dashboard to variable `APISIX_DASHBOARD_VERSION`, for example: 2.10. -# The latest release version can be found at `https://github.com/apache/apisix-dashboard/releases` +[The apisix-docker repo](https://github.com/apache/apisix-docker/blob/master/example) contains an example docker-compose file and config files that show how to start APISIX using docker compose. For the sake of completeness, this docker-compose file also starts [APISIX dashboard](https://hub.docker.com/r/apache/apisix-dashboard), which is a frontend interface that makes it easy for users to interact with APISIX, along with Prometheus and Grafana. -export APISIX_DASHBOARD_VERSION=2.10 +To try out this example: -# build alpine based image -make build-dashboard-alpine +1. Clone the [repo](https://github.com/apache/apisix-docker) and cd into the root folder. + Review Comment: ```suggestion 1. Clone the [repo](https://github.com/apache/apisix-docker) and cd into the root folder. ``` git clone 'https://github.com/apache/apisix-docker' cd apisix-docker ``` ``` -- 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]
