On-Premises Configuration

AISIX on-premises deployments are configured through a Docker Compose .env file or Helm values, depending on how you install the control plane.

Use this reference with On-Premises Deployment 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-ee/.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 managed-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 managed gateway hosts can reach.
AISIX_CLOUD_DASHBOARD_URL	Internal dashboard URL used by cp-api. The Compose default points to the dashboard service.

Set AISIX_CLOUD_PUBLIC_BASE_URL and AISIX_CLOUD_DPMGR_BASE_URL before exposing the deployment outside the local host or container network.

Pricing Catalog

Variable	Purpose
AISIX_CLOUD_PRICESYNC_URL	Online model-pricing catalog URL. The default points to models.dev.
AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH	Offline pricing snapshot path. When set, cp-api seeds the catalog from the snapshot and does not contact models.dev.

The offline package sets AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH automatically so pricing works without outbound network access.

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.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 managed gateway hosts can reach.
api.dpImage	AISIX gateway image shown in generated managed-gateway install snippets.

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	Application password for the bundled PostgreSQL chart.
postgresql.auth.postgresPassword	PostgreSQL superuser password for the bundled PostgreSQL chart.
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.