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, then preserve it across later package refreshes.
Images and Release Version
| Variable | Purpose |
|---|---|
AISIX_VERSION | Release tag used by the control-plane images. |
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 | AISIX gateway image shown in generated AISIX Cloud gateway install snippets. |
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. |
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.
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.
These are service-level settings in docker-compose.yaml, not options exposed directly in the generated .env file:
api service setting | Purpose |
|---|---|
AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH | Seed model pricing from the in-image snapshot and disable online synchronization. |
AISIX_CLOUD_PRICESYNC_URL | Override the models.dev catalog URL when running in online pricing mode. |
To use online pricing, remove AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH from the api service. Optionally add AISIX_CLOUD_PRICESYNC_URL for an internal mirror, then recreate the service.
Playground
| 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. |
Notification Destinations
AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS lets cp-api send budget notifications to private, internal, or loopback addresses. It is disabled by default as an SSRF protection. The packaged Compose file does not expose this setting in the generated .env file or pass it to cp-api by default.
To enable private notification destinations, add the setting under services.api.environment in docker-compose.yaml, then recreate the api service:
services:
api:
environment:
AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS: "true"
Enable it only when a trusted webhook receiver or Slack proxy is on an internal network.
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
The chart source and values are published in the api7/api7-helm-chart repository.
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 | Kubernetes Service settings for cp-api. |
dpm.service.type, dpm.service.port | Kubernetes Service settings for dp-manager. |
ui.service.type, ui.service.port | Kubernetes Service settings for the dashboard service behind cp-api. |
Control Plane URLs
| Value | Purpose |
|---|---|
api.publicBaseURL | Browser-facing control-plane origin. |
api.dpmgrBaseURL | dp-manager mTLS endpoint that AISIX gateway hosts can reach. A DNS name or an IP address. The chart also passes it 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. |
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.
Dashboard Locale
| Value | Purpose |
|---|---|
ui.defaultLocale | Dashboard language for the deployment. Supported values are en and zh. |