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.

Licensing

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, handles console sign-in, and serves the dashboard
dp-manager	Issues mTLS certificates and delivers configuration to data planes
PostgreSQL database	Shared datastore. Docker Compose packages include it; Helm can deploy it or connect to an external database.

The dashboard is not a separate service: its files are part of the cp-api image, and cp-api serves them on the same port as the Admin API.

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.
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, 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.
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 or dp-manager. 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 and, on the first installation, the first administrator's email address and password. The default URL is http://localhost:8080. Open the dashboard and sign in as the first administrator.

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 postgresql.auth.password="$(openssl rand -hex 24)" \
  --set postgresql.auth.postgresPassword="$(openssl rand -hex 24)"

The chart deploys cp-api, which also serves the dashboard, the data-plane manager, 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, and sign in as the first administrator.

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.

Install on OpenShift

The control-plane chart installs on OpenShift under the default restricted-v2 security context constraint. No custom SCC, no anyuid, and no service-account changes are needed.

The chart pins no UID. The default pod security context for cp-api and dp-manager — the api and dpm values keys — is exactly:

podSecurityContext:
  runAsNonRoot: true
  seccompProfile:
    type: RuntimeDefault

restricted-v2 supplies the runAsUser and fsGroup from the namespace's allocated range, and the pods accept whatever it assigns. The container images declare the numeric user 10001, and every file each process reads is world-readable, so an arbitrary UID with GID 0 works. The only paths written at runtime are emptyDir volumes.

The container security context is unchanged and already satisfies restricted-v2: all capabilities dropped, a read-only root filesystem, and no privilege escalation.

To pin a fixed UID instead — on a cluster that does not assign one, or to match existing volume ownership — set the values back:

helm install aisix-cp api7/aisix-cp \
  --set api.podSecurityContext.runAsUser=10001 \
  --set api.podSecurityContext.runAsGroup=101 \
  --set api.podSecurityContext.fsGroup=101 \
  --set secrets.masterKey="$(openssl rand -base64 32)" \
  --set postgresql.auth.password="$(openssl rand -hex 24)" \
  --set postgresql.auth.postgresPassword="$(openssl rand -hex 24)"

Bundled PostgreSQL on OpenShift

The bundled PostgreSQL chart is a dependency of the control-plane chart, and it still pins its own UID. A dependency chart cannot have its values made conditional from the parent chart. Turn its two security contexts off at install time so restricted-v2 assigns the UID:

helm install aisix-cp api7/aisix-cp \
  --set postgresql.primary.podSecurityContext.enabled=false \
  --set postgresql.primary.containerSecurityContext.enabled=false \
  --set secrets.masterKey="$(openssl rand -base64 32)" \
  --set postgresql.auth.password="$(openssl rand -hex 24)" \
  --set postgresql.auth.postgresPassword="$(openssl rand -hex 24)"

Nothing else needs disabling. In particular, do not turn off postgresql.shmVolume — PostgreSQL then falls back to the 64 MB /dev/shm the container runtime provides, and parallel queries fail with could not resize shared memory segment.

Using an external database avoids the question entirely, and is the recommended production choice regardless of platform.

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 is published per CPU architecture, and the latest URL of each resolves to the current release. Pick the one matching the air-gapped host:

Host architecture	Download URL
linux/amd64 (x86-64)	https://run.api7.ai/aisix-self-hosted/aisix-self-hosted-offline-latest-linux-amd64.tar.gz
linux/arm64 (AArch64)	https://run.api7.ai/aisix-self-hosted/aisix-self-hosted-offline-latest-linux-arm64.tar.gz

Version-pinned URLs of the form aisix-self-hosted-offline-<version>-linux-<arch>.tar.gz are published in the same directory.

On a machine with internet access, download the package for the target host's architecture:

curl -fSL "https://run.api7.ai/aisix-self-hosted/aisix-self-hosted-offline-latest-linux-amd64.tar.gz" \
  -o aisix-self-hosted-offline-latest-linux-amd64.tar.gz

The URLs without an architecture suffix — aisix-self-hosted-offline-latest.tar.gz and aisix-self-hosted-offline-<version>.tar.gz — keep working and are the linux/amd64 package, so existing automation does not need to change. The linux/arm64 package is published only under its own suffix.

Transfer the package to the air-gapped host, then start the stack:

tar -xzf aisix-self-hosted-offline-latest-linux-amd64.tar.gz
cd aisix-self-hosted
./run.sh

Each package bundles images for one architecture only. If the package does not match the host, run.sh stops before loading anything and prints the URL of the right one — rather than letting docker load succeed and every container fail later with exec format error.

The startup script:

• loads the bundled container images
• generates a .env file with fresh secrets
• starts the stack without internet access
• prints the dashboard URL when startup finishes, and on the first installation the first administrator's email address and password

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. At startup, the control plane loads the model-pricing catalog from that snapshot. To use online pricing instead, set AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH= in .env and recreate the api service. See On-Premises Configuration for the pricing catalog settings.

Sign In as the First Administrator

An On-Premises control plane has no open sign-up, and nobody can create an organization in it. Instead, cp-api creates the first administrator on its first start: on a start where the database has no users yet, it creates the organization Default with that account as its owner. The administrator then invites everyone else. See Deployment Mode for what else an On-Premises control plane does differently.

The first administrator comes from two settings, the email address and the initial password:

• Docker Compose. When run.sh generates .env on the first start, it writes AISIX_CLOUD_BOOTSTRAP_ADMIN_EMAIL=admin@example.com and a random AISIX_CLOUD_BOOTSTRAP_ADMIN_PASSWORD, and prints both once after the stack is up. It never changes an existing .env. To administer the deployment under your own address, invite that address from this account and give it the owner role.

• Helm. api.bootstrapAdmin.email defaults to admin@example.com. Unless you set api.bootstrapAdmin.password or api.bootstrapAdmin.existingSecret, the chart generates a random password into its own Secret, under the key bootstrap-admin-password, and the installation notes print the command that reads it:

  kubectl get secret <secret-name> -n <namespace> \
    -o jsonpath='{.data.bootstrap-admin-password}' | base64 -d; echo

  helm template and GitOps tools that render charts themselves, such as Argo CD, cannot read the generated Secret back and would generate a new password on every render. For those deployments, set api.bootstrapAdmin.password or api.bootstrapAdmin.existingSecret explicitly.

Sign in with that email address and password. The first sign-in asks for a new password before anything else, and the new password must differ from the initial one. Until it is changed, the account can do nothing else in the dashboard or the API.

The first administrator is created at most once in the life of a database. Changing the settings afterwards, restarting, or adding replicas changes nothing, and a database that already has users, such as an upgraded installation, never gets one. With both settings empty, cp-api starts, logs a warning, and nobody can sign in. Set both, or neither: cp-api refuses to start with only one. See First Administrator and Deployment Mode and First Administrator for the 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. Sign-in always trusts this origin, and invitation and password reset links point to it. Single sign-on builds its service provider URLs from it, so it must be the URL browsers actually use.
AISIX_CLOUD_DPMGR_BASE_URL	api.dpmgrBaseURL	dp-manager mTLS endpoint that data-plane hosts connect to. An https:// URL such as https://dpm.example.com:7944, whose host may be a DNS name or an IP address.

The Helm chart exposes the cp-api and dp-manager services as ClusterIP by default. Expose them 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 dashboard is reached through more than one hostname, such as a second domain or a reverse proxy:

Docker Compose setting	Helm value	Purpose
AISIX_TRUSTED_ORIGINS	api.trustedOrigins	Extra sign-in origins. Docker Compose takes a comma-separated list, such as https://console.example.com,https://admin.example.com. Helm takes a YAML list of the same origins.

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.

Reverse Proxies

When cp-api sits behind an ingress controller, load balancer, or other reverse proxy, list the proxy address ranges so sign-in and password reset rate limits apply per user rather than to all users together:

Docker Compose setting	Helm value	Purpose
AISIX_TRUSTED_PROXIES	api.trustedProxies	Proxies in front of cp-api, as CIDRs such as 10.0.0.0/8. Docker Compose takes a comma-separated list; Helm takes a YAML list.

See Rate Limits Behind a Reverse Proxy.

Email

To send invitation, password reset, and set-password emails, connect cp-api to an SMTP relay. See Configure Email (SMTP).

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, sign in as the first administrator and change the initial password. The version of the running control plane appears at the bottom of the dashboard's left navigation, in one of two forms:

• v1.0.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": "1.0.0",
  "cp_commit": "a22f131"
}

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.