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
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. |
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.
Dashboard Locale
| Value | Purpose |
|---|---|
ui.defaultLocale | Dashboard language for the deployment. Supported values are en and zh. |