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)

• Install Docker.
• Install cURL to send requests to the services for validation.

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.