Deploying on Kubernetes with Helm

This guide explains how to install Document Engine from the command line on any Kubernetes(opens in a new tab) platform with Helm(opens in a new tab).

We also provide these examples:

A generic Kubernetes example(opens in a new tab) that uses Terraform
An AWS EKS example(opens in a new tab) that also provisions an EKS cluster and a managed database

Prerequisites

Before you start, make sure:

kubectl(opens in a new tab) is installed.
Helm(opens in a new tab) is installed.
Your Kubernetes context is configured.
You’ll install into a namespace(opens in a new tab) named document-engine.

If needed, create the namespace:

kubectl create namespace document-engine

To set it as the default namespace in the current context, run:

kubectl config set-context --current --namespace=document-engine

If you do this, you won’t need to add -n document-engine to the commands below.

Add the Document Engine Helm repository:

helm repo add pspdfkit https://pspdfkit.github.io/helm-charts
helm repo update

Prepare the Helm values file

Start with the values.simple.yaml(opens in a new tab) deployment configuration file(opens in a new tab) from the Helm chart:

curl -o document-engine.values.yaml \
    https://raw.githubusercontent.com/PSPDFKit/helm-charts/master/charts/document-engine/values.simple.yaml

This configuration sets up:

Document Engine
A PostgreSQL database
An unnamed Ingress(opens in a new tab) resource

The PostgreSQL database in this setup uses ephemeral storage, so Document Engine won’t persist data stored in it. If you want to configure the database yourself, refer to the database configuration section.

You can also start with the full parameter set by downloading values.yaml(opens in a new tab):

curl -o document-engine.values.yaml \
    https://raw.githubusercontent.com/PSPDFKit/helm-charts/master/charts/document-engine/values.yaml

In both cases:

Edit document-engine.values.yaml.
Add more values files.
Override values directly in the Helm command.

Set up the license

If you have a license, create a secret for the activation key:

kubectl -n document-engine \
  create secret generic document-engine-license \
  --from-literal=DOCUMENT_ENGINE_ACTIVATION_KEY=<YOUR ACTIVATION KEY>

Then reference it in document-engine.values.yaml by setting documentEngineLicense.externalSecret.name and documentEngineLicense.externalSecret.key:

documentEngineLicense:
  externalSecret:
    name: document-engine-license
    key: DOCUMENT_ENGINE_ACTIVATION_KEY

Refer to the product activation guide for more information.

Database configuration

If you already have a PostgreSQL database, configure Document Engine to use it.

First, disable installation of the external PostgreSQL Helm chart(opens in a new tab) in document-engine.values.yaml:

postgresql:
  enabled: false

Then create secrets with your database settings:

kubectl -n document-engine \
  create secret generic de-db-secret \
    --from-literal=PGHOST='<database host>' \
    --from-literal=PGPORT='<database port>' \
    --from-literal=PGSSL='<true or false>' \
    --from-literal=PGDATABASE='<database name>' \
    --from-literal=PGUSER='<username>' \
    --from-literal=PGPASSWORD='<password>'

kubectl -n document-engine \
  create secret generic de-db-admin-secret \
    --from-literal=PG_ADMIN_USER='<username>' \
    --from-literal=PG_ADMIN_PASSWORD='<password>'

If migration jobs are disabled, set PG_ADMIN_USER to the same value as PGUSER, and set PG_ADMIN_PASSWORD to the same value as PGPASSWORD. Refer to the configuration options guide for more information.

Finally, point Document Engine to your database in document-engine.values.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

Configure object storage

To use S3-compatible asset storage instead of the database, update document-engine.values.yaml:

assetStorage:
  s3:
    bucket: "<your bucket name>"
    region: "<bucket region>"
    # host: "os.local"
    port: 443
      scheme: "https://"

Set host only if you use S3-compatible storage with a custom URL.

If you don’t provide bucket access through an instance profile(opens in a new tab), IAM role for a service account(opens in a new tab), pod-level IAM role association(opens in a new tab), or another inherited authorization method, create credentials manually.

Create a secret:

kubectl -n document-engine \
  create secret generic de-s3-secret \
    --from-literal=AWS_ACCESS_KEY_ID='<AWS access key>' \
    --from-literal=AWS_SECRET_ACCESS_KEY='<AWS secret key>'

Then configure Document Engine to use it:

assetStorage:
  s3:
    auth:
      externalSecretName: de-s3-secret

Install the Helm chart

To install the chart into the document-engine namespace, run:

helm upgrade --install -n document-engine \
  document-engine pspdfkit/document-engine \
  -f document-engine.values.yaml

Overriding parameters directly isn’t recommended for production, but it’s useful for testing.

For example, to scale the deployment to two nodes, run:

helm upgrade --install -n document-engine \
  document-engine pspdfkit/document-engine \
  -f document-engine.values.yaml \
  --set replicaCount=2

Refer to the horizontal scaling guide for more information.

To enable clustering so document-scoped requests route to an owner node, set the clustering environment variables through extraEnvs. Also make sure the chart exposes a headless service whose name matches CLUSTERING_SERVICE_NAME:

extraEnvs:
  - name: CLUSTERING_ENABLED
    value: "true"
  - name: CLUSTERING_METHOD
    value: kubernetes_dns
  - name: CLUSTERING_SERVICE_NAME
    value: document-engine

Refer to the horizontal scaling guide for background on clustering behavior. When clustering is enabled, rolling restarts may produce normal Removing it from the ring and Cluster handshake completed log messages as pods leave and rejoin the ring.

This command installs the chart if it isn’t installed yet. Otherwise, it updates the existing installation. During an update, Helm aligns the deployed state with your command-line parameters, values files, and chart version.

Access the Document Engine service inside the cluster

After you install the chart, your application accesses the service(opens in a new tab) from inside the Kubernetes cluster.

Kubernetes service names follow this format:

<service name>.<namespace>.svc.cluster.local

In this case, the service name is:

document-engine.document-engine.svc.cluster.local

To reach the Document Engine API and dashboard from outside the cluster, configure an Ingress(opens in a new tab) resource. Refer to the ingress guide.

Logging and monitoring

Kubernetes supports different ways to collect logs, traces, and metrics from workloads. Document Engine writes logs to standard output and supports OpenTelemetry traces.

Migrate from Docker Compose

If you’ve used Docker Compose before, use the Helm values structure when possible. Since many values map to configuration options defined as environment variables, use extraEnvs if needed:

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 is the shortest path from docker-compose.yml to values.yaml, but it has limitations and isn’t recommended for production.