Install APISIX with Docker
APISIX offers Docker images that make it easy to deploy and manage APISIX in a containerized environment, providing the benefits of consistency, portability, and flexibility.
This document provides the installation steps for deploying APISIX with Docker in standalone and decoupled deployment modes.
Prerequisite(s)
You will need administrator privileges for some of the following steps.
Standalone Mode
The following steps cover how to install APISIX in standalone mode using Docker and provide one approach to achieve data persistency with Docker volume. Adjust the approach accordingly to integrate with your infrastructure.
Create Configuration Files on Host
To achieve data persistency, create a directory for configuration file and create configuration files config.yaml
and apisix.yaml
within:
mkdir ~/conf
touch ~/conf/config.yaml
echo '
routes:
-
id: example-route-to-httpbin
uri: /anything/test
upstream:
nodes:
httpbin.org: 1
type: roundrobin
#END
' > ~/conf/apisix.yaml
❶ config.yaml
: this file will be initialized in container at startup. It is created on host as an empty file to mount to the container and synchronize with the file content in the container.
❷ apisix.yaml
: this file does not exist in container at startup. It is created on host with an example route to mount to the container and avoid any configuration error that may occur.
Create apisix
User on Host
If you use a Debian-based APISIX Docker image, to volume mount files created in the previous step with the appropriate permissions, you should create an apisix
user with the same gid and uid as the apisix
user in the container and change the owner of the configuration files to apisix
.
Create an user apisix
with uid and gid 636:
groupadd --system --gid 636 apisix
useradd --system --gid apisix --no-create-home --shell /usr/sbin/nologin --uid 636 apisix
Change the ownership of the directory with configuration files to apisix
:
chown -R apisix:apisix ~/conf
Install APISIX
Specify the Docker image tag in an environment variable:
TAG=3.5.0-debian
Start APISIX in the standalone mode with configuration files mounted to the container:
docker run -d \
--name apisix-standalone \
-p9080:9080 -p9443:9443 -p9090:9092 \
-e APISIX_STAND_ALONE=true \
--mount type=bind,source="$(pwd)"/conf/apisix.yaml,target=/usr/local/apisix/conf/apisix.yaml \
--mount type=bind,source="$(pwd)"/conf/config.yaml,target=/usr/local/apisix/conf/config.yaml \
apache/apisix:${TAG}
Verify Installation
Send a request to APISIX to see if it is running:
curl -Is "http://127.0.0.1:9080" | grep Server
If everything is ok, you should see the server version number, such as the following:
Server: APISIX/3.5.0
Verify Data Persistency
In the previous steps, you have mounted apisix.yaml
and config.yaml
on the host to the corresponding files in the container.
Send a request to the pre-configured route in apisix.yaml
:
curl -i http://127.0.0.1:9080/anything/test
You should see an HTTP/1.1 201 OK
response similar to the following:
{
...
"headers": {
...
},
"json": null,
"method": "GET",
"origin": "172.17.0.1, 34.xx.xx.xx",
"url": "http://127.0.0.1/anything/test"
}
You can modify configurations in apisix.yaml
and config.yaml
on host, which update the configurations in the container.
Changes to apisix.yaml
will be loaded automatically to APISIX, whereas changes to config.yaml
will require a reload of APISIX to take effect. See configuration files for more details.
Decoupled Mode
Coming soon.