You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/05/11 00:13:32 UTC

[GitHub] [apisix-docker] VioletZhouECE opened a new pull request, #305: Add doc for docker-compose, makefile commands, and images in README.md

VioletZhouECE opened a new pull request, #305:
URL: https://github.com/apache/apisix-docker/pull/305

   Update README.md:
   - add a **Summary** section, which briefly what this repo contains
   - add doc for images in the beginning in **How to Build Images**
   - add **Run With Docker-compose**
   - add **Useful Commands**
   
   Need info for: 
   
   - supported platforms for each command
   
   Any suggestion or fix is appreciated :)


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] VioletZhouECE commented on pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
VioletZhouECE commented on PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#issuecomment-1134913160

   Thank you all for the review and the comments!
   Sorry for being unresponsive recently. I moved to a new city and didn't set up the wifi till yesterday...I will implement the suggested change by Yilin and open up another issue for license and additional reference.
   


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] VioletZhouECE commented on pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
VioletZhouECE commented on PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#issuecomment-1131178735

   Inspired by other docker hub docs (i.e.https://hub.docker.com/_/httpd), I restructured the doc. Now it contains 5 sections:
   
   - What is APISIX
   - Image variants
   - How to run APISIX
   - How to build this Image
   - Notes
   
   I also removed everything related to the dashboard as we now decided to put it in a separate doc.


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] yzeng25 commented on pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
yzeng25 commented on PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#issuecomment-1132607232

   > I think we can also add these sections to the doc. They are present in other docker hub docs (i.e. [centos](https://hub.docker.com/_/centos), [httpd](https://hub.docker.com/_/httpd)):
   > 
   > * Quick reference (Maintained by, Where to get help, Where to file issues, Supported architectures, Source repo)
   > * Supported tags and respective Dockerfile links
   > * License
   
   These are good-to-haves indeed. But they are too much to have in this pull request.
   
   Why don't you open up an issue for them? Discussing them with other contributors and committers can clarify you thoughts and generate a detailed outline which everyone agrees on.


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] VioletZhouECE commented on pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
VioletZhouECE commented on PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#issuecomment-1136104593

   Hi @SylviaBABY , @yzeng25. I implement the changes suggested by Yilin. Can I have some review on the updated doc? 


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] SylviaBABY commented on pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#issuecomment-1134144816

   > I think we can also add these sections to the doc. They are present in other docker hub docs (i.e. [centos](https://hub.docker.com/_/centos), [httpd](https://hub.docker.com/_/httpd)):
   > 
   > * Quick reference (Maintained by, Where to get help, Where to file issues, Supported architectures, Source repo)
   > * Supported tags and respective Dockerfile links
   > * License
   
   @VioletZhouECE  Hi, I think this part we could refer to Pulsar(https://hub.docker.com/r/apachepulsar/pulsar), add `Quick reference` at the beginning, and the end part is done with `License` like this(because Apache Projects use the same license).
   
   <img width="824" alt="image" src="https://user-images.githubusercontent.com/39793568/169739142-f9f77143-bc55-4a09-88f4-9e16f3bbc543.png">
   
   And `Quick Reference` you can replace directly with this:
   
   - Documentation: 
   [the APISIX Docs](https://apisix.apache.org/docs/apisix/next/getting-started)
   
   - Where to file issues: 
   https://github.com/apache/apisix/issues
   
   - Where to get help related to Apache APISIX: 
   Mailing List: Mail to dev-subscribe@apisix.apache.org, follow the reply to subscribe to the mailing list.
   Slack Workspace - join [`#apisix` channel](https://apisix.apache.org/docs/general/join/#join-the-slack-channel)
   
   - Blog: 
   [the APISIX Blog](https://apisix.apache.org/blog/)
   
   


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] VioletZhouECE commented on a diff in pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
VioletZhouECE commented on code in PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#discussion_r871797098


##########
README.md:
##########
@@ -1,8 +1,23 @@
-**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.**
+## Summary
+This repo includes:
+1. docker images for APISIX and APISIX dashboard (on alpine and centos). 
+2. examples that show how to get APISIX and APISIX dashboard up and running. 
+3. a list of commands that allow users to easily build, save, and tar the docker images.
 
-## How To Build Image
+## How To Build Images
 
-**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.**
+**Note**: Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source. \

Review Comment:
   They were originally in different places. I moved them to the same place because I think they are both related to images/building images. I agree that it's confusing to have two Notes side by side. I will move them elsewhere.



-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] VioletZhouECE commented on a diff in pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
VioletZhouECE commented on code in PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#discussion_r880681478


##########
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:
   Okay. I changed this to  "1. Make sure that you are in the root folder of 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: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] Chever-John commented on a diff in pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
Chever-John commented on code in PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#discussion_r871177432


##########
README.md:
##########
@@ -1,8 +1,23 @@
-**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.**
+## Summary
+This repo includes:
+1. docker images for APISIX and APISIX dashboard (on alpine and centos). 
+2. examples that show how to get APISIX and APISIX dashboard up and running. 
+3. a list of commands that allow users to easily build, save, and tar the docker images.
 
-## How To Build Image
+## How To Build Images
 
-**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.**
+**Note**: Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source. \

Review Comment:
   Why are there two Notes?
   And a `\` at the end?



##########
README.md:
##########
@@ -1,8 +1,23 @@
-**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.**
+## Summary
+This repo includes:
+1. docker images for APISIX and APISIX dashboard (on alpine and centos). 

Review Comment:
   No indent at the end
   



##########
README.md:
##########
@@ -117,6 +154,18 @@ docker run -d \
 -v `pwd`/all-in-one/apisix-dashboard/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml \
 apache/apisix-dashboard:whole
 ```
+## Useful commands
+
+Below are some useful commands which build, push, and tar your updated images.
+As an example, these are the commands for apisix-centos images:
+
+-   ```make build-on-centos``` : Build apache/apisix:xx-centos image. 
+
+-   ```make push-on-centos```: Build and push apache/apisix:xx-centos image.
+
+-  ```make save-centos-tar```:  Save apache/apisix:xx-centos image to a tar archive located at ```./package``` . 

Review Comment:
   Some questions here?
   Please note that the indentation remains consistent
   



-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] VioletZhouECE commented on pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
VioletZhouECE commented on PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#issuecomment-1131711928

   I think we can also add these sections to the doc. They are present in other docker hub docs (i.e. [centos](https://hub.docker.com/_/centos), [httpd](https://hub.docker.com/_/httpd)):
   - Quick reference (Maintained by, Where to get help, Where to file issues, Supported architectures, Source repo)
   - Supported tags and respective Dockerfile links
   - License


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] VioletZhouECE commented on pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
VioletZhouECE commented on PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#issuecomment-1136117295

   Also moved **Image variants** after **Notes** as suggested by @SylviaBABY. 


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] navendu-pottekkat commented on pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#issuecomment-1131641766

   @VioletZhouECE I think you can mark this PR for review. @yzeng25 can help us approve the workflows as well which will catch any lint issues.


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] SylviaBABY commented on pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#issuecomment-1135309564

   > Thank you all for the review and the comments! Sorry for being unresponsive recently. I moved to a new city and didn't set up the wifi till yesterday...I will implement the suggested change by Yilin and open up another issue for license and additional reference.
   
   @VioletZhouECE Wish you have a good time in the new city! After implementing the suggested changes by Yilin, you can cue me and Yilin to approve this PR. Then focus on the other changes in another issue^^


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] VioletZhouECE commented on a diff in pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
VioletZhouECE commented on code in PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#discussion_r871793344


##########
README.md:
##########
@@ -1,8 +1,23 @@
-**Docker images are not official ASF releases but provided for convenience. Recommended usage is always to build the source.**
+## Summary
+This repo includes:
+1. docker images for APISIX and APISIX dashboard (on alpine and centos). 

Review Comment:
   I don't think indentation is required for an ordered list: https://www.markdownguide.org/basic-syntax/#ordered-lists
   It's indented automatically.



-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] yzeng25 commented on a diff in pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
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: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] SylviaBABY merged pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
SylviaBABY merged PR #305:
URL: https://github.com/apache/apisix-docker/pull/305


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] VioletZhouECE closed pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
VioletZhouECE closed pull request #305: Add doc for docker-compose, makefile commands, and images in README.md
URL: https://github.com/apache/apisix-docker/pull/305


-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-docker] VioletZhouECE commented on a diff in pull request #305: Add doc for docker-compose, makefile commands, and images in README.md

Posted by GitBox <gi...@apache.org>.
VioletZhouECE commented on code in PR #305:
URL: https://github.com/apache/apisix-docker/pull/305#discussion_r871793531


##########
README.md:
##########
@@ -117,6 +154,18 @@ docker run -d \
 -v `pwd`/all-in-one/apisix-dashboard/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml \
 apache/apisix-dashboard:whole
 ```
+## Useful commands
+
+Below are some useful commands which build, push, and tar your updated images.
+As an example, these are the commands for apisix-centos images:
+
+-   ```make build-on-centos``` : Build apache/apisix:xx-centos image. 
+
+-   ```make push-on-centos```: Build and push apache/apisix:xx-centos image.
+
+-  ```make save-centos-tar```:  Save apache/apisix:xx-centos image to a tar archive located at ```./package``` . 

Review Comment:
   Thanks! Will double check my indentations



-- 
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-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org