On-Premises Configuration
Configure the On-Premises deployment through a Docker Compose .env file or Helm values, depending on how you install the control plane.
Use this reference with On-Premises Installation when you need to review or customize the generated deployment configuration.
These settings configure the on-premises control plane package. They are separate from AISIX gateway runtime environment variables. For gateway runtime variables, see Environment Variables.
Docker Compose Environment Variables
The Docker Compose package reads environment variables from ./aisix-self-hosted/.env. The quickstart and offline package generate this file on first start. Back it up with the database: it contains the database password and master key, and it is not included in later package archives.
During a normal in-place upgrade, run.sh updates AISIX_VERSION to match the extracted package. It preserves the other settings and secrets in .env.
Run the Docker Compose commands on this page from the ./aisix-self-hosted directory.
Images and Release Version
| Variable | Purpose |
|---|---|
AISIX_VERSION | Package-owned release tag used by the images unless you set an individual image override. run.sh updates it during an upgrade. |
AISIX_API_IMAGE | Optional image override for cp-api. |
AISIX_DPM_IMAGE | Optional image override for dp-manager. |
AISIX_UI_IMAGE | Optional image override for the dashboard. |
AISIX_CLOUD_DP_IMAGE | Optional AISIX gateway image override used in generated gateway install snippets. |
Individual image overrides remain in effect across package upgrades.
Database
| Variable | Purpose |
|---|---|
POSTGRES_USER | PostgreSQL user for the bundled database. |
POSTGRES_PASSWORD | PostgreSQL password for the bundled database. Use a strong URL-safe value because it is embedded in a postgres:// URL. |
POSTGRES_DB | PostgreSQL database name. |
These variables configure only the bundled PostgreSQL service. The package does not expose external database URL overrides in .env. Use the Helm installation when the control plane must connect to an external PostgreSQL database.
Secrets
| Variable | Purpose |
|---|---|
AISIX_CLOUD_MASTER_KEY | Base64-encoded 32-byte AES key used for envelope encryption. The same value is also used by dp-manager. |
AISIX_CLOUD_MASTER_KEY_ID | Identifier stored with encrypted rows so the control plane can identify the wrapping key. |
BETTER_AUTH_SECRET | Session-signing secret for dashboard authentication. |
Do not change AISIX_CLOUD_MASTER_KEY on an existing deployment unless you are following a master-key rotation procedure. Changing it without preserving the previous key can make encrypted data unreadable.
Recover a Missing CA Root
Use this recovery override only when cp-api or dp-manager refuses to start with ca_root row missing but dp_certificates has rows, and only after confirming that the control plane is connected to the intended database. Minting a new root CA invalidates every existing gateway mTLS chain. It does not recover the missing root.
If you cannot restore the missing root from a complete database backup and intend to replace it, add the following setting to .env:
AISIX_CLOUD_ALLOW_FRESH_BOOTSTRAP=1
Recreate both services so either process can bootstrap the replacement CA:
docker compose up -d --wait api dpm
After both services are healthy, remove AISIX_CLOUD_ALLOW_FRESH_BOOTSTRAP from .env and run the same command again to recreate them without the override. When both services are healthy again, re-enroll every AISIX gateway; certificates issued under the missing root no longer authenticate.
Runtime URLs
| Variable | Purpose |
|---|---|
AISIX_CLOUD_PUBLIC_BASE_URL | Browser-facing control-plane origin, such as https://aisix.example.com. Login validates the session issuer against this value. |
AISIX_CLOUD_DPMGR_BASE_URL | dp-manager mTLS endpoint that AISIX gateway hosts can reach. A DNS name or an IP address. |
AISIX_CLOUD_DASHBOARD_URL | Internal dashboard URL used by cp-api. The Compose default points to the dashboard service. |
AISIX_TRUSTED_ORIGINS | Additional browser origins allowed to sign in, provided as a comma-separated list. The public base URL and its loopback twin are trusted automatically. |
Set AISIX_CLOUD_PUBLIC_BASE_URL and AISIX_CLOUD_DPMGR_BASE_URL before exposing the deployment outside the local host or container network.
Compose passes AISIX_CLOUD_DPMGR_BASE_URL to the dpm service as well, because dp-manager issues its TLS server certificate for that host. Recreate both api and dpm after changing it.
Pricing Catalog
The packaged Docker Compose file runs cp-api in offline pricing mode by default. It sets AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH on the api service to a snapshot baked into the cp-api image, so the control plane can initialize model pricing without contacting models.dev.
The package exposes the pricing mode through .env:
| Variable | Purpose |
|---|---|
AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH | Select offline mode when it contains a snapshot path. When the variable is absent, Compose uses the in-image snapshot. An explicitly empty value selects online mode. |
AISIX_CLOUD_PRICESYNC_URL | Override the models.dev catalog URL in online mode, for example with an internal mirror. When it is empty, online mode uses https://models.dev/api.json. |
To use online pricing, add an empty snapshot-path assignment to .env. Add the URL only when you need to use a different catalog endpoint:
AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH=
Recreate cp-api after changing either setting:
docker compose up -d api
Keep these overrides in .env, not docker-compose.yaml, because extracting a later package replaces the Compose file.
Private Network Access
By default, cp-api refuses these outbound connections when the destination resolves to a private, internal, or loopback address. Enable only the access required for services on networks that you trust and that cp-api can reach.
| Variable | Purpose |
|---|---|
AISIX_PLAYGROUND_ALLOW_PRIVATE_IPS | Set to 1 to let the dashboard playground reach LLM endpoints on private, internal, or loopback addresses. Off by default as an SSRF protection; enable it only for self-hosted models on an internal network. See Playground. |
AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS | Set to true to let budget notifications reach a private webhook receiver or Slack proxy. |
AISIX_CLOUD_MCP_SPEC_ALLOW_PRIVATE_URLS | Set to true to let the control plane fetch an MCP server's OpenAPI document from a private spec_url. If the document is on a private URL and you leave this setting disabled, provide spec_content instead. |
Set the required variables in .env, then recreate cp-api:
docker compose up -d api
Dashboard and Ports
| Variable | Purpose |
|---|---|
AISIX_DASHBOARD_LOCALE | Dashboard language for the deployment. Supported values are en and zh. |
POSTGRES_HOST_PORT | Host port binding for bundled PostgreSQL. |
API_HOST_PORT | Host port binding for cp-api and the dashboard reverse proxy. |
DPM_HOST_PORT | Host port binding for dp-manager. |
Prefix a host port with 127.0.0.1: when the service should bind only to loopback.
Helm Values
The api7/aisix-cp chart uses Helm values instead of a Compose .env file. Add the API7 Helm repository before inspecting or installing the chart:
helm repo add api7 https://charts.api7.ai
helm repo update
To inspect every chart value, run:
helm show values api7/aisix-cp --version 1.2.0
The chart source and package are published in the aisix-cp-1.2.0 Helm chart release.
Images and Services
| Value | Purpose |
|---|---|
api.image.repository, api.image.tag | cp-api image. |
dpm.image.repository, dpm.image.tag | dp-manager image. |
ui.image.repository, ui.image.tag | Dashboard image. |
api.replicaCount, dpm.replicaCount, ui.replicaCount | Number of replicas for each control-plane component. |
api.affinity, dpm.affinity, ui.affinity | Kubernetes scheduling rules used to spread replicas across nodes or failure domains. |
api.nodeSelector, dpm.nodeSelector, ui.nodeSelector | Node label constraints for each control-plane component. |
api.tolerations, dpm.tolerations, ui.tolerations | Kubernetes taint exceptions for each control-plane component. |
api.service.type, api.service.port, api.service.nodePort | Kubernetes Service settings for cp-api. Direct NodePort connections use plain HTTP. |
dpm.service.type, dpm.service.port, dpm.service.nodePort | Kubernetes Service settings for the dp-manager mTLS endpoint. |
ui.service.type, ui.service.port, ui.service.nodePort | Kubernetes Service settings for the dashboard service behind cp-api. Direct NodePort connections use plain HTTP. |
The chart renders a configured nodePort only when the corresponding Service type is NodePort. Leave the value empty to let Kubernetes allocate a port dynamically. For other Service types, the chart ignores the value.
Operators normally reach the dashboard through cp-api, which proxies dashboard traffic to the UI service. Do not use the UI NodePort as a standalone dashboard entry point. If an external same-origin proxy uses it as an upstream, route dashboard pages to the UI service and /api/* requests to cp-api. Terminate TLS at the proxy unless it runs only on a trusted private network.
Control Plane URLs
| Value | Purpose |
|---|---|
api.publicBaseURL | Browser-facing control-plane origin. When cp-api uses a NodePort, set this to the externally reachable origin at that port or the origin of the TLS reverse proxy in front of it. |
api.dpmgrBaseURL | dp-manager mTLS endpoint that AISIX gateway hosts can reach. A DNS name or an IP address. When dp-manager uses a NodePort, set this to its externally reachable HTTPS endpoint. The chart also passes the value to the dp-manager deployment, which issues its TLS server certificate for that host. |
api.dpImage | AISIX gateway image shown in generated AISIX Cloud gateway install snippets. |
Playground
| Value | Purpose |
|---|---|
api.playgroundAllowPrivateIPs | Let the dashboard playground reach LLM endpoints on private, internal, or loopback addresses. false by default as an SSRF protection. |
Notification Destinations
| Value | Purpose |
|---|---|
api.notifyAllowPrivateURLs | Let cp-api send budget notifications to private, internal, or loopback addresses. false by default as an SSRF protection. |
Secrets
| Value | Purpose |
|---|---|
secrets.masterKey | Base64-encoded 32-byte AES key used for envelope encryption. |
secrets.masterKeyID | Identifier stored with encrypted rows so the control plane can identify the wrapping key. |
secrets.betterAuthSecret | Session-signing secret for dashboard authentication. |
Replace the chart's placeholder secrets before installing. The chart rejects placeholder secret values.
PostgreSQL
| Value | Purpose |
|---|---|
postgresql.builtin | Deploy the bundled PostgreSQL chart when set to true. |
postgresql.auth.password | Password for the bundled chart's configured PostgreSQL user. The chart requires a non-placeholder value even when applications connect as the postgres user. |
postgresql.auth.postgresPassword | PostgreSQL superuser password. The chart uses this for control-plane connections by default. |
postgresql.auth.usePostgresUserForAppConnections | Use the postgres user for control-plane connections. The default is true. |
postgresql.auth.existingSecret | Existing Kubernetes Secret for bundled PostgreSQL credentials. |
externalDatabase.* | Top-level values for an existing PostgreSQL database when postgresql.builtin=false. |
Use URL-safe PostgreSQL passwords, such as values generated with openssl rand -hex 24, because the chart builds a postgres:// connection URL from the configured credentials.
Private PostgreSQL CA for the Dashboard
Starting with aisix-cp chart 1.2.1 (application version 1.2.0), ui.extraVolumes and ui.extraVolumeMounts let the dashboard mount a private database CA. Both default to empty lists. They append to the built-in Next.js cache volume and mount.
If external PostgreSQL uses a private CA, the dashboard's Node.js client must trust it. Otherwise registration and login can fail with SELF_SIGNED_CERT_IN_CHAIN even while dashboard pages load.
Create a ConfigMap containing the public PEM CA certificate in the dashboard namespace. This example uses release and namespace aisix-cp; replace them with your deployment's names:
kubectl create configmap aisix-postgres-ca \
--namespace aisix-cp --from-file=ca.crt=./ca.crt
Add these settings to your existing Helm values file. Keep your database settings and any existing entries in the three ui lists:
ui:
extraEnvVars:
- name: NODE_EXTRA_CA_CERTS
value: /etc/aisix/postgres-ca/ca.crt
extraVolumes:
- name: postgres-ca
configMap:
name: aisix-postgres-ca
items:
- key: ca.crt
path: ca.crt
extraVolumeMounts:
- name: postgres-ca
mountPath: /etc/aisix/postgres-ca
readOnly: true
For a Secret, replace the configMap block with:
secret:
secretName: aisix-postgres-ca
items:
- key: ca.crt
path: ca.crt
Provision that Secret in the same namespace. Only the public CA certificate is needed; keep the CA private key with the certificate issuer. Use unique volume names and mount paths, preserving next-cache and /app/.next/cache for the built-in cache. These settings affect the dashboard; configure database TLS for the other control-plane components separately as needed.
Apply the values with a chart version that supports these fields and keep PostgreSQL TLS verification enabled. Manage the certificate resource and values in your deployment source so later GitOps syncs retain the mount.
After a CA update or rotation, restart the dashboard so Node.js reloads NODE_EXTRA_CA_CERTS. The chart does not automatically restart Pods when an external ConfigMap or Secret changes:
kubectl rollout restart deployment/aisix-cp-ui --namespace aisix-cp
kubectl rollout status deployment/aisix-cp-ui --namespace aisix-cp
Dashboard Locale
| Value | Purpose |
|---|---|
ui.defaultLocale | Dashboard language for the deployment. Supported values are en and zh. |