Skip to main content
Version: Next

Installation

This guide lists the supported installation paths for Apache APISIX and the checks to run before you configure routes. For a short local walkthrough, start with Getting Started.

Choose an installation method#

MethodAppropriate starting point
Docker ComposeLocal evaluation or a reproducible container-based environment
HelmKubernetes deployment managed with the official APISIX chart
RPM or DEBA supported Linux distribution managed by system packages
Source buildDevelopment or a build that requires reviewed compile-time changes

APISIX supports Linux for production. Confirm the supported architecture, distribution, and component versions for the release you intend to deploy. Do not copy a package filename or image tag from an older guide into production without verifying that release.

Install APISIX#

Clone the apisix-docker repository:

git clone https://github.com/apache/apisix-docker.git
cd apisix-docker/example
Local example only

The example configuration is not safe to expose on a shared or untrusted network. Before starting it, bind the published Admin API (9180) and Control API (9092) ports to 127.0.0.1 or remove those host-port mappings. Never expose the Control API to public traffic. Restrict the metrics port (9091) to the intended monitoring path. If host access to etcd is required, bind 2379 to 127.0.0.1; otherwise remove its host-port mapping. Also restrict allow_admin to the intended operator address and replace the example Admin API keys. The bundled etcd is configured for an isolated example, not as a secured production configuration store.

Start the Compose file that matches the host architecture:

x86_64
docker compose -p docker-apisix up -d
ARM64
docker compose -p docker-apisix -f docker-compose-arm64.yml up -d

The example starts APISIX and its required configuration store. Review the Compose file, image tags, exposed ports, credentials, volumes, and network settings before every use and before adapting it to another environment.

Select the configuration source#

Choose the deployment mode before starting a production node:

  • Traditional and decoupled modes use etcd as the configuration store. Secure a networked etcd deployment with authentication, TLS, and network isolation.
  • Standalone file-driven mode loads a full YAML or JSON configuration from the local filesystem and does not use etcd as its configuration center.
  • Standalone API-driven mode stores full configuration in memory and is intended for defined integrations such as the APISIX Ingress Controller and ADC. Review its full-replacement and versioning behavior before use.

Docker Compose and Helm examples can provision an example etcd instance for you; do not treat that as a production etcd design. For a production deployment or a package or source installation in an etcd-backed mode, install a supported etcd release by following the official etcd installation documentation. Confirm connectivity and version compatibility before starting APISIX.

Configure APISIX#

APISIX reads conf/config.yaml by default. Edit that file before running the configuration test:

apisix test

To start APISIX with a different configuration file, pass --config or -c to apisix start. The apisix test command does not accept this option:

apisix start -c /path/to/config.yaml

Only include values you need to override. APISIX uses its packaged defaults for other settings. Do not edit the generated conf/nginx.conf directly.

For example, an etcd-backed traditional node can set its listener and etcd endpoint as follows:

conf/config.yaml
apisix:
  node_listen: 9080

deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  etcd:
    host:
      - "https://etcd.example:2379"

Configure etcd authentication and TLS fields for the selected environment. A URL beginning with https:// alone is not sufficient proof that peer verification and credentials are correct.

Protect the Admin API#

Replace the documented development key, restrict allow_admin to operator networks, and deliver the key through the secret mechanism used by your deployment. The environment variable below must exist in the APISIX process environment; defining it only in an interactive shell does not configure a service managed by systemd or another supervisor.

For a local package evaluation, generate a key before writing the configuration:

export ADMIN_KEY="$(openssl rand -hex 32)"

Then reference that variable in conf/config.yaml:

conf/config.yaml
deployment:
  admin:
    allow_admin:
      - 127.0.0.0/24
    admin_key:
      - name: admin
        key: ${{ADMIN_KEY}}
        role: admin

The data-plane rate-limiting plugins do not protect the Admin API. Keep the Admin API off untrusted networks and apply the operational controls described in the Admin API documentation.

After configuring the selected mode and its actual configuration source, preserve the key across the first privileged APISIX commands:

sudo --preserve-env=ADMIN_KEY apisix init
sudo --preserve-env=ADMIN_KEY apisix test
sudo --preserve-env=ADMIN_KEY apisix start

For a managed installation, inject the same value through a restricted service environment file or secret manager instead of relying on a shell export. Configure and verify etcd first when using an etcd-backed mode. After any configuration change, run apisix test and then reload or restart APISIX in the same controlled environment.

Do not put an Admin API key in a URL. Once APISIX is running, send it in the required header:

curl "http://127.0.0.1:9180/apisix/admin/routes" \
  -H "X-API-KEY: ${ADMIN_KEY}"

Verify the installation#

For a package or source installation, validate the generated NGINX configuration before start or reload:

apisix version
apisix test
curl -i "http://127.0.0.1:9080/"

Before a Route is configured, the data-plane request can return 404; the purpose of this check is to confirm that the intended listener responds. Use the Admin API check above to confirm control-plane access.

For a container or Kubernetes installation, use the corresponding container and workload status commands, then inspect the APISIX logs. Verify all of the following before configuring production traffic:

  • the expected APISIX version and image or package digest are running;
  • the data-plane and Admin API ports are exposed only where intended;
  • the selected configuration source is reachable and updates are applied;
  • the Admin API rejects missing or invalid credentials; and
  • a test Route reaches its intended upstream and fails safely when that upstream is unavailable.

Continue with Getting Started to create and verify a Route.