Apache APISIX Docker Deployment Guide

You can configure APISIX using its Admin API. The following examples demonstrate how to create services with round-robin upstreams, map routes to those services based on hostnames, and configure SSL certificates for subdomains.

Note: All requests require the X-API-KEY header. In this example, the key is edd1c9f034335f136f87ad84b625c8f1.

# Create service 1 with web1 upstream
curl http://127.0.0.1:9180/apisix/admin/services/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "web1:80": 1
        }
    }
}'

# Create route 12 for host web1.lvh.me linked to service 1
curl http://127.0.0.1:9180/apisix/admin/routes/12 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{
    "uri": "/*",
    "host": "web1.lvh.me",
    "service_id": "1"
}'

# Configure SSL for lvh.me
curl http://127.0.0.1:9180/apisix/admin/ssl/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d "{\n    \"cert\": \"$( cat './mkcert/lvh.me+1.pem')\",\n    \"key\": \"$( cat './mkcert/lvh.me+1-key.pem')\",\n    \"sni\": \"lvh.me\"\n}"

This solution uses a dedicated Docker bridge network to isolate etcd and APISIX. You must create a configuration file (config.yaml) that specifies the etcd host and sets admin.allow_admin to the subnet address of the Docker network to allow administrative access.

# 1. Create a network and start etcd
docker network create apisix-network --driver bridge && \
docker network inspect -v apisix-network && \
docker run -d --name etcd \
  --network apisix-network \
  -p 2379:2379 \
  -p 2380:2380 \
  -e ALLOW_NONE_AUTHENTICATION=yes \
  -e ETCD_ADVERTISE_CLIENT_URLS=http://127.0.0.1:2379 \
  bitnamilegacy/etcd:3.5.11

# 2. Create config.yaml (Note: replace 0.0.0.0/0 with your subnet address for security)
cat << EOF > $(pwd)/config.yaml
deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  admin:
    allow_admin:
      - 0.0.0.0/0
  etcd:
    host:
      - "http://etcd:2379"
    prefix: "/apisix"
    timeout: 30
EOF

# 3. Start APISIX referencing the config file
docker run -d --name apache-apisix \
  --network apisix-network \
  -p 9080:9080 \
  -p 9180:9180 \
  -v $(pwd)/config.yaml:/usr/local/apisix/conf/config.yaml \
  apache/apisix

To deploy Apache APISIX manually using Docker, you must first create a dedicated bridge network, then run an etcd server to act as the configuration center, and finally run the APISIX server container.

Prerequisites:

• Ensure you have a configuration file for etcd located at example/etcd_conf/etcd.conf.yml.
• Ensure you have an APISIX configuration file located at example/apisix_conf/config.yaml. You must verify or modify the etcd address in this file to match the IP assigned to the etcd container (e.g., http://172.18.5.10:2379).

Windows Note: When using Windows, you must use absolute paths for volume mounts (e.g., -v /e/github/docker-apisix/example/apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml).

# 1. Create the network
docker network create \
  --driver=bridge \
  --subnet=172.18.0.0/16 \
  --ip-range=172.18.5.0/24 \
  --gateway=172.18.5.254 \
  apisix

# 2. Run etcd server
docker run -it --name etcd-server \
-v `pwd`/example/etcd_conf/etcd.conf.yml:/opt/bitnami/etcd/conf/etcd.conf.yml \
-p 2379:2379 \
-p 2380:2380  \
--network apisix \
--ip 172.18.5.10 \
--env ALLOW_NONE_AUTHENTICATION=yes bitnami/etcd:3.4.9

# 3. Run Apache APISIX server
docker run --name test-api-gateway \
 -v `pwd`/example/apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml \
 -v `pwd`/example/apisix_log:/usr/local/apisix/logs  \
 -p 9080:9080 \
 -p 9091:9091  \
 -p 9443:9443 \
 --network apisix \
 --ip 172.18.5.11 \
 -d apache/apisix