Configure an RPM Data Plane from the Docker Parameters

Configure an RPM data plane by hand when you cannot run the generated script on the host — for example a machine where running a downloaded shell script is not permitted, or one where a configuration management system owns /usr/local/apisix/conf/config.yaml and would revert anything the script writes.

The parameters are the same either way. This page takes them from the Docker tab, which presents each one as a separate environment variable and is therefore easier to read off, and shows where each lands in the RPM config.yaml. See Deploy with the Offline RPM Bundle for the installation workflow itself.

Get the Docker Script from the Dashboard

In the Dashboard, go to your gateway group, click Add Instance, select Docker, and copy the generated docker run command. It carries every connection parameter as environment variables:

docker run -d \
  -e API7_DP_MANAGER_ENDPOINTS='["https://<CP_HOST>:7943"]' \
  -e API7_GATEWAY_GROUP_SHORT_ID=default \
  -e API7_DP_MANAGER_CERT="-----BEGIN CERTIFICATE-----
  ...client certificate...
  -----END CERTIFICATE-----" \
  -e API7_DP_MANAGER_KEY="-----BEGIN PRIVATE KEY-----
  ...client private key...
  -----END PRIVATE KEY-----" \
  -e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
  ...CA certificate...
  -----END CERTIFICATE-----" \
  -p 9080:9080 -p 9443:9443 \
  api7/api7-ee-3-gateway:<version>

You only need the five API7_* environment-variable values.

Map Environment Variables to RPM Configuration

Write the Certificate Files

Write the three PEM blocks to the gateway's cert directory. Strip any extra leading whitespace that the Docker command may have added per line:

sudo install -d -m 0755 /usr/local/apisix/conf/cert

sudo tee /usr/local/apisix/conf/cert/api7ee.crt > /dev/null <<'EOF'
-----BEGIN CERTIFICATE-----
...API7_DP_MANAGER_CERT content...
-----END CERTIFICATE-----
EOF

sudo tee /usr/local/apisix/conf/cert/api7ee.key > /dev/null <<'EOF'
-----BEGIN PRIVATE KEY-----
...API7_DP_MANAGER_KEY content...
-----END PRIVATE KEY-----
EOF

sudo tee /usr/local/apisix/conf/cert/api7ee_ca.crt > /dev/null <<'EOF'
-----BEGIN CERTIFICATE-----
...API7_CONTROL_PLANE_CA content...
-----END CERTIFICATE-----
EOF

Edit the Gateway Configuration

Edit the gateway configuration file at /usr/local/apisix/conf/config.yaml. Apply the values from the generated Docker command:

deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  etcd:
    host:
      - https://<CP_HOST>:7943
    tls:
      cert: /usr/local/apisix/conf/cert/api7ee.crt
      key: /usr/local/apisix/conf/cert/api7ee.key
      # sni: <API7_DP_MANAGER_SNI>
apisix:
  ssl:
    ssl_trusted_certificate: /usr/local/apisix/conf/cert/api7ee_ca.crt

If the Docker script includes API7_DP_MANAGER_SNI, remove the comment marker from sni and set that value.

Start and Verify the Gateway

Start the gateway service and confirm that it is active:

sudo systemctl enable --now api7-gateway
systemctl is-active api7-gateway

Confirm the data-plane ports are listening:

ss -ltn | grep -E ':9080|:9443'

Back in the Dashboard, open the Instances list of the gateway group. The instance should appear shortly and turn Healthy.

Troubleshooting

If the instance never appears and the log shows requires a sufficient license, the control plane has no License uploaded yet (Dashboard → Settings → License). This is a control-plane prerequisite, not a data-plane configuration problem.

Dashboard metrics require a Prometheus service, which is not included in the bundle. Install it and point the dp-manager at it. See Install Prometheus in the offline RPM guide. Until then a connected gateway logs agent.lua:544: upload metrics block failed, status: 500; this is expected when Prometheus is absent, and the instance is still Healthy with traffic unaffected.

To troubleshoot mTLS, check /usr/local/apisix/logs/error.log. certificate verify failed or handshake failed usually means a CA or SNI mismatch. If the endpoint uses a hostname, make sure it is in the dp-manager server certificate's SAN, or set the sni from API7_DP_MANAGER_SNI.