Self-hosting (Enterprise)

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 dataxland

Each 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:

KeyRequiredContents
DX_POSTGRES_URLyesConnection string of the dx database, for example postgresql://dx:<password>@pg.corp.example:5432/dx?sslmode=require
DX_DUCKLAKE_CATALOG_PASSWORDyesPassword of the Postgres user (used for the dx_lake database)
DX_SESSION_SECRETyesRandom string that signs login sessions
DX_SECRET_KEYyesRandom string that encrypts stored secrets (source passwords, tokens)
DX_DELEGATION_SIGNING_KEYyesRandom string that signs short-lived delegation tokens between services
DX_BACKUP_ENCRYPTION_KEYyes32 bytes, URL-safe base64, encrypts backups
DX_DUCKLAKE_S3_KEY_ID, DX_DUCKLAKE_S3_SECRETyesObject storage keys
DX_SMTP_PASSWORDnoSMTP password
DX_BACKUP_S3_KEY_ID, DX_BACKUP_S3_SECRETnoSeparate keys for the backup bucket, if they differ from the warehouse keys
DX_METRICS_TOKENnoRequires a token to read /metrics
Model API keydepends on the modelVariable 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.json

Without 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: letsencrypt

Keys you will often change:

KeyMeaning
deployment.publicUrlThe URL users open; required
deployment.superAdminsEmails of installation-wide admins
deployment.signupModeinvite (default), approval or open
deployment.timezoneTime zone for business dates and backup times, default Asia/Ho_Chi_Minh
deployment.extraEnvExtra environment variables for api, worker, mcp (SMTP, notification channels)
image.registry, image.repositoryPrefix, image.tagImage registry; an empty image.tag uses the chart version
image.digestsPin images by digest, for example {api: sha256:..., web: sha256:...}
objectStorage.lakePrefixPrefix inside the warehouse bucket, when the bucket is shared
ingress.tls.secretNameSecret with the certificate; empty means dataxland-tls (created by cert-manager)
ingress.mcp.enabled, ingress.mcp.hostExpose the MCP server, for example mcp.dataxland.corp.example
ingress.api.enabled, ingress.api.hostExpose the api's /v1 directly, only when you need OAuth callbacks or webhooks
api.autoscaling.enabled, web.autoscaling.enabledEnable the HPA
mcp.enabledTurn 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:

  1. Open https://dataxland.corp.example.
  2. Sign up with an email listed in deployment.superAdmins. This email needs no invitation code and must turn on two-factor authentication.
  3. Go to Admin → Operations, section Deployment and licence: check the license status, usage and air-gapped mode.
  4. 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-status

Trial 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: false
helm install dataxland <chart path> -n dataxland -f values-trial.yaml
kubectl -n dataxland port-forward svc/dataxland-web 3000:3000

If 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: monitoring

The 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).

Markdown