Install with Helm
Install DataxLand on Kubernetes with the Helm chart, including the secrets Secret, the license Secret, minimal production values, post-install checks, a trial setup with in-cluster Postgres and MinIO, External Secrets, NetworkPolicy and ServiceMonitor.
This page uses the release name dataxland, the namespace dataxland and the domain dataxland.corp.example. Replace them
with your own values.
Before you start you need: infrastructure as described in Requirements and sizing, Helm 3,
kubectl pointed at the cluster, and from DataxLand: the chart, the image repository name, image pull access (or the
offline image bundle) and the license file
license.json.
1. Namespace
kubectl create namespace dataxlandEach namespace holds one installation: the api Service is always named api (the web image calls
http://api:8000 out of the box).
If the image registry requires a login, create an image pull Secret and declare it under imagePullSecrets:
kubectl -n dataxland create secret docker-registry dataxland-pull \
--docker-server=ghcr.io --docker-username=<name> --docker-password=<token>2. Secrets Secret
The chart contains no secret values. Create one Secret where each key matches an environment variable:
| Key | Required | Contents |
|---|---|---|
DX_POSTGRES_URL | yes | Connection string of the dx database, for example postgresql://dx:<password>@pg.corp.example:5432/dx?sslmode=require |
DX_DUCKLAKE_CATALOG_PASSWORD | yes | Password of the Postgres user (used for the dx_lake database) |
DX_SESSION_SECRET | yes | Random string that signs login sessions |
DX_SECRET_KEY | yes | Random string that encrypts stored secrets (source passwords, tokens) |
DX_DELEGATION_SIGNING_KEY | yes | Random string that signs short-lived delegation tokens between services |
DX_BACKUP_ENCRYPTION_KEY | yes | 32 bytes, URL-safe base64, encrypts backups |
DX_DUCKLAKE_S3_KEY_ID, DX_DUCKLAKE_S3_SECRET | yes | Object storage keys |
DX_SMTP_PASSWORD | no | SMTP password |
DX_BACKUP_S3_KEY_ID, DX_BACKUP_S3_SECRET | no | Separate keys for the backup bucket, if they differ from the warehouse keys |
DX_METRICS_TOKEN | no | Requires a token to read /metrics |
| Model API key | depends on the model | Variable name from the model's api_key_env. The default catalog uses DEEPSEEK_API_KEY |
kubectl -n dataxland create secret generic dataxland-env \
--from-literal=DX_POSTGRES_URL='postgresql://dx:<password>@pg.corp.example:5432/dx?sslmode=require' \
--from-literal=DX_DUCKLAKE_CATALOG_PASSWORD='<password>' \
--from-literal=DX_SESSION_SECRET="$(openssl rand -hex 32)" \
--from-literal=DX_SECRET_KEY="$(openssl rand -hex 32)" \
--from-literal=DX_DELEGATION_SIGNING_KEY="$(openssl rand -hex 32)" \
--from-literal=DX_BACKUP_ENCRYPTION_KEY="$(openssl rand -base64 32 | tr '+/' '-_')" \
--from-literal=DX_DUCKLAKE_S3_KEY_ID='<key id>' \
--from-literal=DX_DUCKLAKE_S3_SECRET='<secret>'If the Postgres password contains special characters, URL-encode it in DX_POSTGRES_URL.
Store DX_SECRET_KEY and DX_BACKUP_ENCRYPTION_KEY in two places right away (your company secret store and an offline
copy). Lose DX_SECRET_KEY and every data source has to be reconnected; lose DX_BACKUP_ENCRYPTION_KEY and no backup can be
decrypted.
3. License Secret
kubectl -n dataxland create secret generic dataxland-license --from-file=license.json=./license.jsonWithout a license the installation still runs, but in read-only mode. See Offline license.
4. Production values
A minimal values-prod.yaml (AWS example):
image:
repositoryPrefix: <name provided by DataxLand>
imagePullSecrets:
- name: dataxland-pull
deployment:
publicUrl: https://dataxland.corp.example
superAdmins: [admin@corp.example]
extraEnv:
DX_SMTP_HOST: smtp.corp.example
DX_SMTP_PORT: "587"
DX_SMTP_USER: dataxland
DX_SMTP_FROM: dataxland@corp.example
license:
existingSecret: dataxland-license
secrets:
existingSecret: dataxland-env
postgres:
external:
host: pg.corp.example
database: dx
catalogDatabase: dx_lake
user: dx
objectStorage:
endpoint: s3.ap-southeast-1.amazonaws.com
region: ap-southeast-1
urlStyle: vhost
lakeBucket: dx-lake
tenantKeys: "off"
backup:
bucket: dx-backups
persistence:
storageClass: efs-rwx
size: 100Gi
ingress:
className: nginx
host: dataxland.corp.example
annotations:
cert-manager.io/cluster-issuer: letsencryptKeys you will often change:
| Key | Meaning |
|---|---|
deployment.publicUrl | The URL users open; required |
deployment.superAdmins | Emails of installation-wide admins |
deployment.signupMode | invite (default), approval or open |
deployment.timezone | Time zone for business dates and backup times, default Asia/Ho_Chi_Minh |
deployment.extraEnv | Extra environment variables for api, worker, mcp (SMTP, notification channels) |
image.registry, image.repositoryPrefix, image.tag | Image registry; an empty image.tag uses the chart version |
image.digests | Pin images by digest, for example {api: sha256:..., web: sha256:...} |
objectStorage.lakePrefix | Prefix inside the warehouse bucket, when the bucket is shared |
ingress.tls.secretName | Secret with the certificate; empty means dataxland-tls (created by cert-manager) |
ingress.mcp.enabled, ingress.mcp.host | Expose the MCP server, for example mcp.dataxland.corp.example |
ingress.api.enabled, ingress.api.host | Expose the api's /v1 directly, only when you need OAuth callbacks or webhooks |
api.autoscaling.enabled, web.autoscaling.enabled | Enable the HPA |
mcp.enabled | Turn off the MCP server if you don't use it |
Object storage on GCP, Azure or on-prem: see the table in Requirements and sizing.
5. Install
helm install dataxland <chart path> -n dataxland -f values-prod.yaml
kubectl -n dataxland get pods -w<chart path> is the directory or .tgz file of the chart DataxLand ships with the release. On the first install the
components create the Postgres schema themselves; on later upgrades the migrate Job does it before the new version rolls out.
After installing, Helm prints notes, with warnings if the license is missing, if in-cluster Postgres or MinIO is in use, or if the chart generated the Secret itself.
6. Check and sign in
kubectl -n dataxland port-forward svc/api 8000:8000
curl -s http://localhost:8000/readyz/readyz checks Postgres, the catalog and object storage. Once it succeeds:
- Open
https://dataxland.corp.example. - Sign up with an email listed in
deployment.superAdmins. This email needs no invitation code and must turn on two-factor authentication. - Go to Admin → Operations, section Deployment and licence: check the license status, usage and air-gapped mode.
- Create the first workspace, then invite users.
License status from the command line:
kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-statusTrial with in-cluster Postgres and MinIO
To try DataxLand on a small cluster, the chart can run Postgres and MinIO inside the cluster. These two components are for trials only: a single replica, no backups, no HA.
# values-trial.yaml
deployment:
publicUrl: http://localhost:3000
superAdmins: [admin@corp.example]
license:
existingSecret: dataxland-license
postgres:
bundled:
enabled: true
minio:
bundled: true
objectStorage:
tenantKeys: minio
persistence:
accessMode: ReadWriteOnce
size: 10Gi
api:
replicas: 1
web:
replicas: 1
ingress:
enabled: falsehelm install dataxland <chart path> -n dataxland -f values-trial.yaml
kubectl -n dataxland port-forward svc/dataxland-web 3000:3000If you don't set secrets.existingSecret, the chart creates the dataxland-env Secret itself with random keys and keeps it
across upgrades. A trial still needs a license file; without one the installation is read-only.
Secrets from External Secrets Operator
If your secrets live in a secret store (AWS Secrets Manager, Google Secret Manager, Azure Key Vault, Vault) and the cluster runs
External Secrets Operator, the chart creates an ExternalSecret instead of a hand-made Secret. The target is still the
dataxland-env Secret.
secrets:
existingSecret: ""
externalSecret:
enabled: true
secretStoreRef: {name: cloud-secrets, kind: ClusterSecretStore}
refreshInterval: 1h
data:
DX_SECRET_KEY: dataxland/prod/secret-key
DX_POSTGRES_URL: {key: dataxland-app, property: DX_POSTGRES_URL}Each key in data is a variable name; the value is the remoteKey in the store, or a full remoteRef (key, property)
when several variables live in one JSON secret. List every required key from section 2.
NetworkPolicy
Requires a CNI that supports NetworkPolicy. Enable it with:
networkPolicy:
enabled: true
ingressControllerNamespace: ingress-nginx
ingressControllerLabels: {app.kubernetes.io/name: ingress-nginx}
monitoringNamespace: monitoringThe chart denies all inbound traffic, then allows only: the ingress controller into web and mcp (and api if
ingress.api is on), the installation's pods calling each other, and Prometheus in monitoringNamespace reading metrics ports
9464 to 9466.
Restricting outbound traffic (required in air-gapped mode):
networkPolicy:
enabled: true
egress:
restrict: true
dnsNamespace: kube-system
allowCIDRs: [10.0.0.0/16]
allowPorts: [5432, 443, 587]With restrict: true, pods may only call DNS, pods of the same installation and the ranges in allowCIDRs (Postgres, object
storage, AI model, SMTP, source databases). An empty allowPorts means every port to those ranges.
ServiceMonitor
With Prometheus Operator:
serviceMonitor:
enabled: true
interval: 30s
labels: {release: prometheus}The chart scrapes /metrics from api (port 9464), worker (9465) and mcp (9466). If you set DX_METRICS_TOKEN, the
chart's ServiceMonitor does not send the token for you; add authentication to your Prometheus configuration. A set of
Prometheus alert rules ships with each release; also load an alert for a license nearing expiry (see
Offline license).
Related
Requirements and sizing
The infrastructure you need before self-hosting DataxLand (Kubernetes, Postgres 16, S3-compatible object storage, a shared volume, ingress and TLS), the default resources of each component and how to pick object storage on each cloud.
Reference Terraform (AWS, GCP, Azure)
Sample Terraform modules that build the network, a managed Kubernetes cluster, Postgres, object storage, a shared volume and a secret store, then install the DataxLand Helm chart on AWS, GCP or Azure; a reference template, not yet applied to a real account.