# Install APISIX with Docker

APISIX Docker images provide a consistent, portable way to run APISIX in standalone or decoupled [deployment modes](https://docs.api7.ai/apisix/production/deployment-modes.md). 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)[​](#prerequisites "Direct link to Prerequisite(s)")

* Install [Docker](https://docs.docker.com/get-docker/).
* Install [cURL](https://curl.se/) to send requests to the services for validation.
* Some steps below require administrator privileges.

## Standalone Mode[​](#standalone-mode "Direct link to Standalone Mode")

The following steps cover how to install APISIX in [file-driven standalone mode](https://docs.api7.ai/apisix/production/deployment-modes.md#file-driven) 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](https://docs.docker.com/storage/volumes). Adjust the approach accordingly to integrate with your infrastructure.

### Create Configuration Files on Host[​](#create-configuration-files-on-host "Direct link to Create Configuration Files on Host")

To achieve data persistence, create a directory for configuration file and create [configuration files](https://docs.api7.ai/apisix/reference/configuration-files.md) `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[​](#create-apisix-user-on-host "Direct link to 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[​](#install-apisix "Direct link to Install APISIX")

Specify the [Docker image tag](https://hub.docker.com/r/apache/apisix/tags) 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[​](#verify-installation "Direct link to 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[​](#verify-data-persistence "Direct link to 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](https://docs.api7.ai/apisix/reference/configuration-files.md) for more details.

## Decoupled Mode[​](#decoupled-mode "Direct link to 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](https://docs.docker.com/storage/volumes). 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[​](#create-configuration-files-on-host-1 "Direct link to 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](https://docs.api7.ai/apisix/reference/configuration-files.md) `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](https://docs.api7.ai/apisix/reference/configuration-files.md) `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[​](#create-apisix-user-on-host-1 "Direct link to create-apisix-user-on-host-1")

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-network "Direct link to 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[​](#install-etcd "Direct link to 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[​](#install-apisix-1 "Direct link to Install APISIX")

Specify the APISIX [Docker image tag](https://hub.docker.com/r/apache/apisix/tags) 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[​](#verify-installation-1 "Direct link to 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[​](#verify-data-persistence-1 "Direct link to 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[​](#verify-persistence-across-etcd-container-replacement "Direct link to 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](#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](https://docs.api7.ai/apisix/reference/configuration-files.md) for more details.

## Production Considerations[​](#production-considerations "Direct link to 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](https://docs.api7.ai/apisix/production/deployment-modes.md) you deploy:

| Area                       | Production consideration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Availability               | Run 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.                                                                                                                                                                                                                                                                                                                                                              |
| Security                   | Protect 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](https://docs.api7.ai/apisix/production/security/mtls/configure-mtls-between-apisix-and-etcd.md), [Admin API Key](https://docs.api7.ai/apisix/production/security/admin-api-key.md), and [IP Restriction](https://docs.api7.ai/apisix/production/security/ip-restriction.md#restrict-admin-api-access-by-ip). |
| Capacity and health        | Set 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 recovery | For file-driven standalone mode, version, validate, and consistently distribute configuration files. For decoupled mode, follow [Operate etcd in Production](https://docs.api7.ai/apisix/production/etcd/operations.md), retain encrypted etcd snapshots outside the host's failure domain, and rehearse restores. See [Back Up and Restore etcd](https://docs.api7.ai/apisix/production/recovery/etcd-backup-restore.md).                                                                                                                                 |
| Lifecycle                  | Validate container and image updates, rollbacks, and configuration compatibility before production rollout.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
