Skip to main content
Version: 3.21.0

Install APISIX with Docker

APISIX Docker images provide a consistent, portable way to run APISIX in standalone or decoupled deployment modes. These examples use one Docker host, persist configuration outside APISIX containers, and add process health checks and restart policies. The host remains a single point of failure.

The unless-stopped policy restarts a container when its main process exits or the Docker daemon restarts, unless an operator stopped the container. An unhealthy status alone does not trigger a restart.

Prerequisite(s)​

  • Install Docker.
  • Install cURL to send requests to the services for validation.
  • Some steps below require administrator privileges.

Standalone Mode​

The following steps cover how to install APISIX in file-driven standalone mode using Docker, while using the YAML config provider and apisix.yaml for gateway configuration.

The section provides one approach to achieve data persistence with Docker volume. Adjust the approach accordingly to integrate with your infrastructure.

Create Configuration Files on Host​

To achieve data persistence, create a directory for configuration file and create configuration files config.yaml and apisix.yaml within:

mkdir ~/conf
cat <<'EOF' > ~/conf/config.yaml
deployment:
role: data_plane
role_data_plane:
config_provider: yaml
#END
EOF
cat <<'EOF' > ~/conf/apisix.yaml
routes:
-
id: example-route-to-httpbin
uri: /anything/test
upstream:
nodes:
httpbin.org: 1
type: roundrobin
#END
EOF

❶ config.yaml: this file configures APISIX to run in file-driven standalone mode with the YAML config provider.

❷ 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 or Ubuntu-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 a 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.21.0-ubuntu

Start APISIX in the standalone mode with configuration files mounted from ~/conf to the container:

docker run -d \
--name apisix-standalone \
--restart unless-stopped \
--health-cmd 'test -s /usr/local/apisix/logs/nginx.pid && kill -0 "$(cat /usr/local/apisix/logs/nginx.pid)"' \
--health-interval 10s \
--health-timeout 5s \
--health-retries 5 \
--health-start-period 30s \
-p9080:9080 -p9443:9443 \
-e APISIX_STAND_ALONE=true \
--mount type=bind,source="$HOME"/conf/apisix.yaml,target=/usr/local/apisix/conf/apisix.yaml \
--mount type=bind,source="$HOME"/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.21.0

Verify Data Persistence​

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 200 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​

The following steps cover how to install APISIX in decoupled mode using Docker and provide one approach to achieve data persistence with Docker volume. Adjust the approach accordingly to integrate with your infrastructure.

In decoupled mode, two APISIX instances should be deployed: one being the data plane (DP) and the other one being the control plane (CP).

Create Configuration Files on Host​

To achieve data persistence, create separate directories for DP and CP configuration files:

for instance in {cp,dp}; do
mkdir -p ~/conf/"$instance"
touch ~/conf/"$instance"/config.yaml
done

Create the configuration files config.yaml for DP instance:

echo '
deployment:
role: data_plane
role_data_plane:
config_provider: etcd
#END
' > ~/conf/dp/config.yaml

The following configuration permits Admin API requests from any source that can reach the container so that the local example remains runnable. The Admin API port is published only on the host loopback interface below. Keep that binding for local management. If remote management is required, publish the port only on a restricted management interface, replace 0.0.0.0/0 with trusted operator CIDRs, and use a securely managed Admin API key.

Create the configuration files config.yaml for CP instance:

echo '
deployment:
role: control_plane
role_control_plane:
config_provider: etcd
admin:
admin_key_required: true
allow_admin:
- 0.0.0.0/0
admin_key:
-
name: admin
key: Sup3rs3cretWr1teK3y # replace with your write key
role: admin
-
name: viewer
key: Sup3rs3cretR3adK3y # replace with your read key
role: viewer
#END
' > ~/conf/cp/config.yaml

Create apisix User on Host​

If you use a Debian or Ubuntu-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 a 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

Create a Docker Network​

Create a Docker bridge network for APISIX and etcd containers:

DOCKER_NETWORK_NAME="apisix-net"
docker network create -d bridge ${DOCKER_NETWORK_NAME}

Install etcd​

Start the etcd container in the Docker network:

ETCD_IMAGE_TAG="v3.5.32"
ETCD_CONTAINER_NAME="etcd"
ETCD_PORT=2379
ETCD_DATA_VOLUME="apisix-etcd-data"

docker volume create "${ETCD_DATA_VOLUME}"

docker run -d \
--name ${ETCD_CONTAINER_NAME} \
--restart unless-stopped \
--network=${DOCKER_NETWORK_NAME} \
--mount type=volume,source="${ETCD_DATA_VOLUME}",target=/etcd-data \
gcr.io/etcd-development/etcd:${ETCD_IMAGE_TAG} \
/usr/local/bin/etcd \
--name ${ETCD_CONTAINER_NAME} \
--data-dir /etcd-data \
--listen-client-urls http://0.0.0.0:${ETCD_PORT} \
--advertise-client-urls http://${ETCD_CONTAINER_NAME}:${ETCD_PORT} \
--listen-peer-urls http://0.0.0.0:2380 \
--initial-advertise-peer-urls http://${ETCD_CONTAINER_NAME}:2380 \
--initial-cluster ${ETCD_CONTAINER_NAME}=http://${ETCD_CONTAINER_NAME}:2380

Install APISIX​

Specify the APISIX Docker image tag in an environment variable:

TAG=3.21.0-ubuntu

Start an APISIX container as the data plane with configuration files mounted from ~/conf/dp to the container. Map port 9080 for HTTP traffic and port 9443 for HTTPS traffic:

docker run -d \
--name apisix-decoupled-dp \
--restart unless-stopped \
--health-cmd 'test -s /usr/local/apisix/logs/nginx.pid && kill -0 "$(cat /usr/local/apisix/logs/nginx.pid)"' \
--health-interval 10s \
--health-timeout 5s \
--health-retries 5 \
--health-start-period 30s \
-p9080:9080 -p9443:9443 \
--network=${DOCKER_NETWORK_NAME} \
--mount type=bind,source="$HOME"/conf/dp/config.yaml,target=/usr/local/apisix/conf/config.yaml \
-e APISIX_DEPLOYMENT_ETCD_HOST="[\"http://${ETCD_CONTAINER_NAME}:${ETCD_PORT}\"]" \
apache/apisix:${TAG}

Start an APISIX container as the control plane with configuration files mounted from ~/conf/cp to the container. Bind the published Admin API port to the host loopback address for local validation:

docker run -d \
--name apisix-decoupled-cp \
--restart unless-stopped \
--health-cmd 'test -s /usr/local/apisix/logs/nginx.pid && kill -0 "$(cat /usr/local/apisix/logs/nginx.pid)"' \
--health-interval 10s \
--health-timeout 5s \
--health-retries 5 \
--health-start-period 30s \
-p 127.0.0.1:9180:9180 \
--network=${DOCKER_NETWORK_NAME} \
--mount type=bind,source="$HOME"/conf/cp/config.yaml,target=/usr/local/apisix/conf/config.yaml \
-e APISIX_DEPLOYMENT_ETCD_HOST="[\"http://${ETCD_CONTAINER_NAME}:${ETCD_PORT}\"]" \
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.21.0

Verify Data Persistence​

Each APISIX container mounts config.yaml from the host. Routes and other gateway configuration persist in the named etcd volume.

Create a sample route by sending a request to the CP APISIX instance:

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: Sup3rs3cretWr1teK3y" \
-d '{
"id": "decoupled-test",
"uri": "/anything/test",
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'

Send a request to the route to verify:

curl -i "http://127.0.0.1:9080/anything/test"

You should see an HTTP/1.1 200 OK response.

Verify Persistence Across etcd Container Replacement​

This optional test stops the single-member etcd service. Run it only in the single-host test environment before serving production traffic.

Remove the etcd container to verify that the route's persistent record survives container replacement:

docker rm -f "${ETCD_CONTAINER_NAME}"

Run the Install etcd commands again to reuse the apisix-etcd-data volume, then check the recreated endpoint:

docker exec "${ETCD_CONTAINER_NAME}" \
etcdctl --endpoints="http://127.0.0.1:${ETCD_PORT}" endpoint health

After the endpoint reports that it is healthy, restart both APISIX containers to force them to load configuration from the recreated etcd container:

docker restart apisix-decoupled-cp apisix-decoupled-dp

Send another request to http://127.0.0.1:9080/anything/test. An HTTP/1.1 200 OK response confirms that the route was loaded from the persistent etcd data.

You can modify configurations in config.yaml on host, which update the configurations in the container. Changes to config.yaml will require a reload of APISIX to take effect. See configuration files for more details.

Production Considerations​

Production Docker deployments require availability, security, capacity, monitoring, rollout, and recovery controls in addition to starting the containers. Apply the following controls to the standalone or decoupled topology you deploy:

AreaProduction consideration
AvailabilityRun multiple APISIX instances across failure domains. In decoupled mode, distribute control-plane and data-plane instances and replace the single etcd container with a three-member cluster.
SecurityProtect secrets in mounted configuration files. In decoupled mode, protect etcd with authentication and TLS, and keep the Admin API on a restricted management network with managed credentials. See Configure mTLS between APISIX and etcd, Admin API Key, and IP Restriction.
Capacity and healthSet CPU and memory limits and provision storage capacity from measured workloads. Monitor container health and APISIX traffic. In decoupled mode, also monitor configuration propagation and etcd quorum, latency, capacity, and alarms.
Configuration and recoveryFor file-driven standalone mode, version, validate, and consistently distribute configuration files. For decoupled mode, follow Operate etcd in Production, retain encrypted etcd snapshots outside the host's failure domain, and rehearse restores. See Back Up and Restore etcd.
LifecycleValidate container and image updates, rollbacks, and configuration compatibility before production rollout.