# 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](/en/docs/self-host/requirements), Helm 3,
`kubectl` pointed at the cluster, and from DataxLand: the chart, the image repository name, image pull access (or the
[offline image bundle](/en/docs/self-host/airgapped#7-copy-images-into-an-internal-registry)) and the license file
`license.json`.

## 1. Namespace

```bash
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`:

```bash
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` |

```bash
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

```bash
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](/en/docs/self-host/license).

## 4. Production values

A minimal `values-prod.yaml` (AWS example):

```yaml
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:

| 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](/en/docs/self-host/requirements#object-storage-on-each-cloud).

## 5. Install

```bash
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

```bash
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:

```bash
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.

```yaml
# 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
```

```bash
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.

```yaml
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:

```yaml
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):

```yaml
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:

```yaml
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](/en/docs/self-host/license#monitoring-expiry)).

## Related

- [Air-gapped mode](/en/docs/self-host/airgapped)
- [Upgrades and backups](/en/docs/self-host/upgrade-backup)
- [Offline license](/en/docs/self-host/license)
