--- title: "Deploying Document Engine on Kubernetes with a Helm chart" canonical_url: "https://www.nutrient.io/guides/document-engine/deployment/helm/" md_url: "https://www.nutrient.io/guides/document-engine/deployment/helm.md" last_updated: "2026-05-22T14:49:21.611Z" description: "This guide describes a generic way to install Document Engine from the command line on any Kubernetes platform using Helm." --- # Deploying on Kubernetes with Helm This guide describes a generic way to install Document Engine from the command line on any [Kubernetes](https://kubernetes.io/) platform using [Helm](https://helm.sh/). We have an [example](https://github.com/PSPDFKit/document-engine-reference-architecture/tree/master/examples/de-kubernetes-helm) of how this can be orchestrated with Terraform in any Kubernetes environment, along with [another example](https://github.com/PSPDFKit/document-engine-reference-architecture/tree/master/examples/de-aws-eks) that also provisions an AWS EKS cluster and a managed database. ## Prerequisites This guide assumes you have [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) and [Helm](https://helm.sh/docs/intro/install/) installed, that you have a configured context, and that you’re going to install into a [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) named `document-engine`. If necessary, create the namespace: ```bash kubectl create namespace document-engine ``` If you want, you can make it the default namespace in the current context: ```bash kubectl config set-context --current --namespace=pspdfkit ``` If you do that, you won’t have to add `-n document-engine` to the commands below. Let Helm know about Document Engine charts: ```bash helm repo add pspdfkit https://pspdfkit.github.io/helm-charts helm repo update ``` ## Preparing the Helm values file Start with the [`values.simple.yaml`](https://github.com/PSPDFKit/helm-charts/blob/master/charts/document-engine/values.simple.yaml) [deployment configuration file](https://helm.sh/docs/chart_template_guide/values_files/) from the Helm chart: ```bash curl -o document-engine.values.yaml \ https://raw.githubusercontent.com/PSPDFKit/helm-charts/master/charts/document-engine/values.simple.yaml ``` This configuration will set up Document Engine with a PostgreSQL database and a nameless [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource. The PostgreSQL database it creates will make use of ephemeral storage, so any data stored in it while using the Document Engine instance won’t be persisted. If you want to set up the database yourself, refer to the corresponding [section](#database-configuration). You can also begin with the full set of parameters by getting the [`values.yaml`](https://github.com/PSPDFKit/helm-charts/blob/master/charts/document-engine/values.yaml) file: ```bash curl -o document-engine.values.yaml \ https://raw.githubusercontent.com/PSPDFKit/helm-charts/master/charts/document-engine/values.yaml ``` In both cases, you can alter the `document-engine.values.yaml` file, as well as use additional files or override values directly within the Helm command. ## Setting up the license If you have a license, create a secret for the activation key: ```bash kubectl -n document-engine \ create secret generic document-engine-license \ --from-literal=DOCUMENT_ENGINE_ACTIVATION_KEY= ``` Then refer to it in the `document-engine.values.yaml` file. To do that, find the `documentEngineLicense.externalSecret` section and set the `name` and `key` values there: ```yaml documentEngineLicense: externalSecret: name: document-engine-license key: DOCUMENT_ENGINE_ACTIVATION_KEY ``` See more about license configuration in our [product activation](https://www.nutrient.io/guides/document-engine/deployment/product-activation.md) guide. ## Database configuration If you already have a PostgreSQL database, you need to configure it. To disable installation of the [external PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/main/bitnami/postgresql), make the following change in `document-engine.values.yaml`: ```yaml postgresql: enabled: false ``` Create secrets with the parameters of your database: ```bash kubectl -n document-engine \ create secret generic de-db-secret \ --from-literal=PGHOST='' \ --from-literal=PGPORT='' \ --from-literal=PGSSL='' \ --from-literal=PGDATABASE='' \ --from-literal=PGUSER='' \ --from-literal=PGPASSWORD='' kubectl -n document-engine \ create secret generic de-db-admin-secret \ --from-literal=PG_ADMIN_USER='' \ --from-literal=PG_ADMIN_PASSWORD='' ``` If migration jobs are disabled, set the same `PG_ADMIN_USER` as `PGUSER` and the same `PG_ADMIN_PASSWORD` as `PGPASSWORD`. You can read more about Document Engine configuration in the [corresponding guide](https://www.nutrient.io/guides/document-engine/configuration/options.md). Finally, refer Document Engine to your database using the following settings in `document-engine.values.yaml`: ```yaml assetStorage: enableMigrationJobs: false databaseEngine: postgresql postgres: enabled: true auth: createSecret: false #...or use external secrets: # `PGUSER`, `PGPASSWORD`, `PGDATABASE`, `PGHOST`, `PGPORT`, `PGSSL` externalSecretName: de-db-secret # `PG_ADMIN_USER` and `PG_ADMIN_PASSWORD` externalAdminSecretName: de-db-admin-secret ``` ## Object storage To set [S3-compatible asset storage](https://www.nutrient.io/guides/document-engine/configuration/asset-storage.md) instead of the database, update `document-engine.values.yaml` in the following way: ```yaml assetStorage: s3: bucket: "" region: "" # host: "os.local" port: 443 scheme: "https://" ``` You only need to set `/pspdfkit/storage/s3/host` if you’re using S3-compatible storage with a custom URL. If you aren’t providing access to your bucket using an underlying [instance profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html), [IAM role for a service account](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html), [pod-level IAM role association](https://docs.aws.amazon.com/eks/latest/userguide/associate-service-account-role.html), or any other authorization propagation, you might need to set up credentials. To do that, create a secret: ```bash kubectl -n document-engine \ create secret generic de-s3-secret \ --from-literal=AWS_ACCESS_KEY_ID='' \ --from-literal=AWS_SECRET_ACCESS_KEY='' ``` Then, configure Document Engine to use it: ```yaml assetStorage: s3: auth: externalSecretName: de-s3-secret ``` ## Installing the Helm chart To install the Helm chart with your deployment configuration into the previously created `document-engine` namespace, use the following command: ```bash helm upgrade --install -n document-engine \ document-engine pspdfkit/document-engine \ -f document-engine.values.yaml ``` You can also override specific parameters. This isn’t recommended in production, but it’s useful for testing purposes. Here’s how to scale up the deployment to two nodes (for more information, refer to the dedicated guide on [horizontal scaling](https://www.nutrient.io/guides/document-engine/deployment/horizontal-scaling.md)): ```bash helm upgrade --install -n document-engine \ document-engine pspdfkit/document-engine \ -f document-engine.values.yaml \ --set replicaCount=2 ``` The command above installs the chart if it hasn’t yet been installed; otherwise, it updates it. Such an update operation will ensure that the state of the deployed components corresponds to the command-line parameters, changes in the values file, and new versions of the chart. ## Accessing the Document Engine Service inside the Cluster Once the Helm chart is installed, your application can access the [service](https://kubernetes.io/docs/concepts/services-networking/service/) from within the Kubernetes cluster. Service names in Kubernetes are defined as `..svc.cluster.local`. In this scenario, the name would be `document-engine.document-engine.svc.cluster.local`. To reach the Document Engine API and dashboard from outside the cluster, [configure](https://www.nutrient.io/guides/document-engine/deployment/ingress.md) an [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource. ## Logging and monitoring Kubernetes allows different ways to retrieve logs, traces, and metrics from the workload. Document Engine writes logs to the standard output and supports [OpenTelemetry traces](https://www.nutrient.io/guides/document-engine/monitoring/opentelemetry.md). ## Migrating from Docker Compose If you’ve previously used Docker Compose, it’s still recommended to use our Helm [values](#preparing-the-helm-values-file) structure. However, since most of the values map to [configuration options](https://www.nutrient.io/guides/document-engine/configuration/options.md) defined as environment variables, it’s also possible to use an `extraEnvs` value: ```yaml extraEnvs: - name: JWT_ALGORITHM value: RS512 - name: DASHBOARD_USERNAME value: testUser - name: DASHBOARD_PASSWORD value: testPassword - name: MAX_UPLOAD_SIZE_BYTES value: "12345678" - name: ASSET_STORAGE_CACHE_SIZE value: "987654321" - name: LOG_LEVEL value: debug ``` This approach is the quickest path from `docker-compose.yml` to `values.yaml`, but it has limitations and isn’t recommended for use in production. --- ## Related pages - [Choose a Docker registry](/guides/document-engine/deployment/docker-registry.md) - [Deploying to Amazon Web Services](/guides/document-engine/deployment/aws.md) - [Deploying to Google Cloud Platform](/guides/document-engine/deployment/google-cloud-platform.md) - [Document Engine deployment overview](/guides/document-engine/deployment.md) - [Backup and recovery](/guides/document-engine/deployment/backup-and-recovery.md) - [Deploying to Microsoft Azure](/guides/document-engine/deployment/microsoft-azure-aks.md) - [Product activation](/guides/document-engine/deployment/product-activation.md) - [Application-specific timeouts](/guides/document-engine/deployment/ingress.md) - [Horizontal scaling](/guides/document-engine/deployment/horizontal-scaling.md) - [Deploying on Kubernetes](/guides/document-engine/deployment/kubernetes.md)