On-Premises Installation
Install the AISIX Cloud control plane in infrastructure you operate using Docker Compose, Helm, or an offline package. This guide helps you choose an installation method, configure the control-plane endpoints, and verify a persistent environment.
The installation provides the same AISIX Cloud control-plane workflows as Hybrid Cloud, including resource management, gateway certificate issuance, usage reporting, and budget enforcement. The control-plane services and data remain in your infrastructure, including in a fully air-gapped environment.
For a local evaluation that continues through creating gateway resources and sending a first AI request, use the AISIX Cloud Quickstart instead.
Production use of the AISIX Cloud control plane and dashboard requires a commercial license. Before deploying the control plane in production, contact API7 or email support@api7.ai.
Plan the Installation
Choose an installation method based on the target infrastructure and its network access:
| Installation method | Target | Requirements |
|---|---|---|
| Docker Compose | Internet-connected host | Docker with Docker Compose V2, cURL, tar, OpenSSL, and access to Docker Hub |
| Helm | Internet-connected Kubernetes cluster | A working cluster, Helm, kubectl, OpenSSL, and access to Docker Hub |
| Offline package | Air-gapped host | Docker with Docker Compose V2, tar, OpenSSL, and a separate machine with cURL that can download the package |
Before installing with Helm, decide whether to use the bundled PostgreSQL database or an external database. Docker Compose and offline package installations use the bundled database. Also choose the public dashboard origin and the data-plane manager endpoint that gateways will reach. You can start with local endpoints, but configure externally reachable endpoints before exposing the dashboard or attaching gateways on other hosts.
Docker Compose installations use host ports 5432, 8080, and 7944 by default. Make sure they are available or configure different host bindings. See the Port Reference for each component, traffic direction, and recommended exposure.
Control Plane Components
Every installation method uses these components:
| Service | Role |
|---|---|
cp-api | Manages organizations, environments, resources, and billing |
dp-manager | Issues mTLS certificates and delivers configuration to data planes |
dashboard | Web console |
| PostgreSQL database | Shared datastore. Docker Compose packages include it; Helm can deploy it or connect to an external database. |
The online and offline Docker Compose packages require the bundled PostgreSQL 16 service. The Helm chart can deploy a bundled PostgreSQL instance or connect to an external database.
AISIX gateways run separately as data planes. They connect outbound to dp-manager over mTLS, so the control plane does not need inbound network access to gateway hosts.
Production Resource Baseline
The following specifications are deployment-planning starting points, not Helm chart defaults, benchmark-derived capacity guarantees, or fixed minimums for every workload. Benchmark and adjust them for your request rate, request size, enabled traffic controls, number of gateways, and data retention periods.
Docker Compose or Offline Package on Hosts
The online and offline Docker Compose packages provide a single-host topology with one instance of each control-plane service and a bundled PostgreSQL database. They do not support an external database or expose the multi-host service configuration required for control-plane high availability.
For an HA production topology, use Helm and the instance counts below. For a package-based evaluation or non-HA deployment, use the CPU, memory, and storage columns to assess host capacity.
CPU, memory, and host storage are per component instance. Host storage is a capacity allowance for the operating system, container images, platform-managed logs, and local component state; it is not equivalent to an application persistent-volume requirement in Kubernetes.
| Component | CPU | Memory | Host storage | Starting instances | Sizing guidance |
|---|---|---|---|---|---|
| AISIX gateway | 4 cores | 8–16 GB | ≥100 GB | 3 minimum; 4 recommended per gateway deployment | Scale horizontally with traffic. Start with 16 GB for high concurrency or guardrail workloads. Increase host storage for longer local log retention. |
cp-api | 2 cores | 4 GB | ≥32 GB | 2 | Stateless; place instances in separate failure domains. |
dp-manager | 2–4 cores | 4–8 GB | ≥32 GB | 2 | Delivers configuration and processes gateway heartbeats and usage telemetry. Place instances in separate failure domains. |
dashboard | 1–2 cores | 2 GB | ≥20 GB | 2 | Stateless; place instances in separate failure domains. |
| PostgreSQL | 4–8 cores | 16 GB | ≥500 GB NVMe SSD | 3 | Critical stateful component. For production HA, use Helm with an external PostgreSQL deployment, such as a primary, synchronous standby, and asynchronous standby. Adjust storage for the usage-event retention period. |
| Prometheus (optional) | 4 cores | 8–16 GB | ≥200 GB | 1–2 | Stores monitoring metrics. Reuse an existing Prometheus deployment when available, and size storage for metric cardinality and retention. |
For smaller deployments, cp-api, dp-manager, dashboard, and Prometheus can share hosts if you reserve CPU and memory for each component and provide enough shared host capacity for container images and logs. Keep redundant instances in separate failure domains.
Helm on Kubernetes
For Kubernetes, plan compute per replica and scale the AISIX gateway independently using Performance and Sizing. The following values are planning recommendations rather than chart defaults:
| Component | CPU per replica | Memory per replica | Starting replicas | Sizing guidance |
|---|---|---|---|---|
| AISIX gateway | 4 cores | 8–16 GB | 3 minimum; 4 recommended per gateway deployment | Scale horizontally with traffic. Start with 16 GB for high concurrency or guardrail workloads. |
cp-api | 2 cores | 4 GB | 2 | Stateless; place replicas in separate failure domains. |
dp-manager | 2–4 cores | 4–8 GB | 2 | Place replicas in separate failure domains. |
dashboard | 1–2 cores | 2 GB | 2 | Stateless; place replicas in separate failure domains. |
| PostgreSQL | 4–8 cores | 16 GB | 3 for production HA | Use an external HA deployment rather than the bundled single-instance database. |
| Prometheus (optional) | 4 cores | 8–16 GB | 1–2 | Reuse an existing Prometheus deployment when available. |
The default control-plane Helm chart does not assign application persistent volumes to cp-api, dp-manager, or dashboard. Account for container images and platform-managed logs as Kubernetes node capacity instead of per-pod storage. If you operate PostgreSQL or Prometheus in the cluster, provision persistent storage separately and size it for usage-event or metric retention. As starting points, allocate at least 500 GB of NVMe SSD storage per PostgreSQL instance and 200 GB per Prometheus instance.
Do not place PostgreSQL replicas in the same failure domain or on shared storage. The bundled PostgreSQL chart does not provide a replicated database by default; see High Availability and External Database.
These specifications cover AISIX components only, not the compute resources required by upstream model inference. AISIX itself does not require a GPU.
Install Online
Use an online installation when the host or Kubernetes cluster can pull container images from Docker Hub.
Docker Compose on a Host
Use Docker Compose for an internet-connected host with Docker and Docker Compose. The installation URL resolves to the current release.
curl -sL "https://run.api7.ai/aisix-self-hosted/quickstart" | bash
The script downloads the package into ./aisix-self-hosted, generates a .env file with fresh secrets, pulls images from Docker Hub, and starts the stack.
The package uses its bundled PostgreSQL service and does not support an external database. Use the Helm installation when an external PostgreSQL database is required.
When startup finishes, the script prints the dashboard URL. The default URL is http://localhost:8080. Open the dashboard and create the first admin account.
Manage the stack from ./aisix-self-hosted:
./aisix-self-hosted/run.sh logs # tail logs
./aisix-self-hosted/run.sh stop # stop containers
./aisix-self-hosted/run.sh down # remove containers (keeps the data volume)
Helm on Kubernetes
For Kubernetes, install the chart from the API7 Helm repository:
helm repo add api7 https://charts.api7.ai
helm repo update
helm install aisix-cp api7/aisix-cp \
--set secrets.masterKey="$(openssl rand -base64 32)" \
--set secrets.betterAuthSecret="$(openssl rand -base64 48)" \
--set postgresql.auth.password="$(openssl rand -hex 24)" \
--set postgresql.auth.postgresPassword="$(openssl rand -hex 24)"
The chart deploys the core API, data-plane manager, dashboard, and a bundled PostgreSQL instance by default.
To reach the dashboard before configuring external access, forward the cp-api service:
kubectl port-forward svc/aisix-cp-api 8080:8080
Open http://localhost:8080 while the port-forward is running.
To use an existing database, first provision the external database and role. Then disable the bundled PostgreSQL chart with postgresql.builtin=false and configure the top-level externalDatabase.* values.
To inspect the default chart values locally, run:
helm show values api7/aisix-cp
The chart source and values are published in the api7/api7-helm-chart repository.
Use URL-safe database passwords, such as values generated with openssl rand -hex 24. The database password is embedded in a postgres:// connection URL, so characters such as +, /, and = from openssl rand -base64 can break the URL.
Install in an Air-Gapped Environment
For a host with no registry access, use the offline package. It includes every required container image.
The offline package URL resolves to the current release.
On a machine with internet access, download the package:
curl -fSL "https://run.api7.ai/aisix-self-hosted/aisix-self-hosted-offline-latest.tar.gz" \
-o aisix-self-hosted-offline-latest.tar.gz
Transfer the package to the air-gapped host, then start the stack:
tar -xzf aisix-self-hosted-offline-latest.tar.gz
cd aisix-self-hosted
./run.sh
The startup script:
- loads the bundled container images
- generates a
.envfile with fresh secrets - starts the stack without internet access
- prints the dashboard URL when startup finishes
The default dashboard URL is http://localhost:8080.
The cp-api image included in the package contains a model-pricing snapshot so usage and budget calculations can initialize without reaching models.dev. On first boot, the control plane seeds the model-pricing catalog from that snapshot. To use online pricing instead, remove AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH from the api service and recreate the stack. See On-Premises Configuration for the pricing catalog settings.
Configure External Access
Before exposing the control plane outside the local host or cluster, configure the public dashboard origin and the data-plane manager endpoint.
For Docker Compose, edit .env. For Kubernetes, update your Helm values:
| Docker Compose setting | Helm value | Purpose |
|---|---|---|
AISIX_CLOUD_PUBLIC_BASE_URL | api.publicBaseURL | Browser-facing origin, such as https://aisix.example.com. Login validates the session issuer against this value. |
AISIX_CLOUD_DPMGR_BASE_URL | api.dpmgrBaseURL | dp-manager mTLS endpoint that data-plane hosts connect to. A DNS name or an IP address. |
The Helm chart exposes the cp-api, dp-manager, and dashboard services as ClusterIP by default. Expose the cp-api and dp-manager services through network endpoints appropriate for your cluster, then set the two public values above to those endpoints.
dp-manager receives the data-plane manager endpoint too, and issues its TLS server certificate for that host. Data planes verify the certificate against the address they dial, so the value must match the endpoint in the generated gateway install command — whether that is a DNS name or an IP address.
After updating these settings, recreate the affected services with docker compose up -d or apply the changes with helm upgrade.
Trusted Sign-In Origins
Sign-in accepts requests only from trusted browser origins. The public base URL origin is trusted automatically, along with its loopback twin. The twin is the same origin with the hostname swapped between localhost and 127.0.0.1, keeping the same scheme and port as the base URL. For example, a base URL of http://localhost:8080 also trusts http://127.0.0.1:8080 — but not a different port or scheme — so a local install works from either address. You do not need to list the base URL again anywhere.
Set additional origins only when the console is reached through more than one hostname, such as a second domain or a reverse proxy. Provide them as a comma-separated list:
| Docker Compose setting | Helm value | Purpose |
|---|---|---|
AISIX_TRUSTED_ORIGINS | ui.extraEnvVars (add AISIX_TRUSTED_ORIGINS) | Extra sign-in origins, comma-separated, such as https://console.example.com,https://admin.example.com. |
A sign-in attempt from an untrusted origin fails with a message stating that the address is not allowed. Add the origin here to resolve it.
For more Docker Compose environment variables and Helm values, see On-Premises Configuration.
Verify the Installation
Open the dashboard at its configured public base URL. For a new installation, create the first admin account, then sign in. The version of the running control plane appears at the bottom of the dashboard's left navigation, in one of two forms:
v0.5.0— a released version. Quote this number when you check the release notes or report an issue.dev · 2f9c1ab— a build from a development commit rather than a release, identified by the abbreviated commit it was built from.
The same identity is available without signing in, which is useful in scripts and support bundles. Replace the base URL below with your own public base URL if the control plane is not reached at the default local address:
AISIX_CP_URL="http://localhost:8080"
curl -sS "${AISIX_CP_URL}/api/config/public" | jq '{cp_version, cp_commit}'
{
"cp_version": "0.5.0",
"cp_commit": "2f9c1ab"
}
The API reports the released version without the v prefix the dashboard displays. cp_version is empty on a build that was not cut from a release; cp_commit identifies the commit in either case.
Gateway versions are reported separately, per instance, in the environment's Data planes view — the control plane and your gateways are upgraded independently.
Next Steps
Create or select the target organization and environment, then connect an AISIX gateway to issue a gateway certificate and attach the runtime that will serve traffic.
Use the On-Premises Configuration Reference to review Docker Compose environment variables and Helm values.