This is an automated email from the ASF dual-hosted git repository.
sylviasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-docker.git
The following commit(s) were added to refs/heads/master by this push:
new 34b0596 Add doc for docker-compose, makefile commands, and images in
README.md (#305)
34b0596 is described below
commit 34b05966fb2e167aadaf58cf7a2bdd7ea57e7ddb
Author: Violet (Xinyi) Zhou <[email protected]>
AuthorDate: Tue May 24 21:59:44 2022 -0400
Add doc for docker-compose, makefile commands, and images in README.md
(#305)
* Update README.md
---
README.md | 199 +++++++++++++++++++++++++++++++++++---------------------------
1 file changed, 114 insertions(+), 85 deletions(-)
diff --git a/README.md b/README.md
index 47b0c57..069d144 100644
--- a/README.md
+++ b/README.md
@@ -1,123 +1,130 @@
-**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
+## How to run APISIX
-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`
+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).
-export APISIX_VERSION=2.9
+### Run APISIX with docker-compose
-# build alpine based image
-make build-on-alpine
+[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.
-# build centos based image
-make build-on-centos
-```
+To try out this example:
-2. Build from master branch version, which has latest code(ONLY for the
developer's convenience):
-```sh
-export APISIX_VERSION=master
+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
+ ```
+
+1. Start APISIX.
+ ```
+ cd example
-# build alpine based image
-make build-on-alpine
+ docker-compose -p docker-apisix up -d
+ ```
-# build centos based image
-make build-on-centos
-```
+2. 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
+ }
+ }
+ ```
-3. Build from local code:
-```sh
-# To copy apisix into image, we need to include it in build context
-cp -r <APISIX-PATH> ./apisix
+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, and 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.
-export APISIX_PATH=./apisix
-make build-on-alpine-local
-
-# Might need root privilege if encounter "error checking context: 'can't
start'"
-```
-
-**Note:** For Chinese, the following command is always recommended. The
additional build argument `ENABLE_PROXY=true` will enable proxy to definitely
accelerate the progress.
+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/b
[...]
-```sh
-$ make build-on-alpine-cn
-```
+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.
-4. Build apisix-dashboard from release version:
+### Run APISIX with all-in-one command
-```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`
+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.
-export APISIX_DASHBOARD_VERSION=2.10
+To try out this example:
-# build alpine based image
-make build-dashboard-alpine
-
-# build centos based image
-make build-dashboard-centos
-```
+1. Make sure that you are in the root folder of apisix-docker.
-### Manual deploy apisix via docker
+2. `make build-all-in-one` to build the `all-in-one` image.
-[Manual
deploy](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/manual.md)
+3. Launch the APISIX container:
-### QuickStart via docker-compose
+ ```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
+ ```
-**start all modules with docker-compose**
+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
+ }
+ }
+ ```
-```sh
-cd example
-docker-compose -p docker-apisix up -d
-```
+The configuration file for the service is located at
[/all-in-one/apisix/config.yaml](https://github.com/apache/apisix-docker/blob/master/all-in-one/apisix/config.yaml).
It is mounted onto the container at runtime.
-You can refer to [the docker-compose
example](https://github.com/apache/apisix-docker/blob/master/docs/en/latest/example.md)
for more try.
+## How To Build this Image
-### Quick test with all dependencies in one Docker container
+The apisix-docker repo contains a list of makefile commands which makes it
easy to build images. To use these commands, clone [the
repo](https://github.com/apache/apisix-docker) and cd into its root folder.
-* All in one Docker container for Apache APISIX
+There are two build arguments that can be set:
+`APISIX_VERSION`: To build the APISIX image, specify the version of APISIX by
setting `APISIX_VERSION`. The latest. release version can be found here
[apisix/releases](https://github.com/apache/apisix/releases).
+`ENABLE_PROXY`: Set `ENABLE_PROXY=true` to enable the proxy to accelerate the
build process.
```sh
-make build-all-in-one
-
-# 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
-```
+# make sure that you are in the root folder of
https://github.com/apache/apisix-docker
+# The latest release version can be find at
`https://github.com/apache/apisix/releases`, for example: 2.9
+export APISIX_VERSION=2.9
-* All in one Docker container for Apache apisix-dashboard
+# build alpine based image
+make build-on-alpine
-**The latest version of `apisix-dashboard` is 2.10 and can be used with APISIX
2.11.**
+# build centos based image
+make build-on-centos
+```
+Alternatively, you can build APISIX from your local code.
```sh
-make build-dashboard-all-in-one
-
-# launch APISIX-dashboard container
-docker run -d \
--p 9080:9080 -p 9091:9091 -p 2379:2379 -p 9000:9000 \
--v `pwd`/all-in-one/apisix/config.yaml:/usr/local/apisix/conf/config.yaml \
--v
`pwd`/all-in-one/apisix-dashboard/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml
\
-apache/apisix-dashboard:whole
-```
+# To copy the local apisix into image, we need to include it in build context
+cp -r <APISIX-PATH> ./apisix
-Tips: If there is a port conflict, please modify the host port through `docker
run -p`, e.g.
+export APISIX_PATH=./apisix
+make build-on-alpine-local
-```sh
-# launch APISIX-AIO container
-docker run -d \
--p 19080:9080 -p 19091:9091 -p 12379:2379 -p 19000:9000 \
--v `pwd`/all-in-one/apisix/config.yaml:/usr/local/apisix/conf/config.yaml \
--v
`pwd`/all-in-one/apisix-dashboard/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml
\
-apache/apisix-dashboard:whole
+# Might need root privilege if encounter "error checking context: 'can't
start'"
```
+**Note:** For Chinese, the following command is always recommended. The
additional build argument `ENABLE_PROXY=true` will enable proxy to definitely
accelerate the progress.
+
### Note
**Prometheus**
@@ -139,3 +146,25 @@ At `0:00 UTC` every day, the APISIX `master` code will be
automatically built an
```bash
docker pull apache/apisix:dev
```
+
+## Image variants
+
+The APISIX image comes in many flavors, each designed for a specific use case.
+
+`apisix:<version>`
+
+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.
+
+`apisix:<version>-alpine`
+
+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.
+
+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](https://news.ycombinator.com/item?id=10782897) for more discussion of
the issues that might arise and some advantages and disadvantages comparisons
of using Alpine-based images.
+
+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](https://hub.docker.com/_/alpine/)).
+
+`apisix:<version>-centos`
+
+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.
+
+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.
