Installation

Before you begin (Prerequisites)

  • Digital Distributed Container License (received from support@trisotech.com)

  • A Kubernetes environment

    • The kubectl command line utility with a valid configuration connected to an existing cluster.

    • The helm command line utility with a valid configuration connected to an existing cluster.

    • A Kubernetes Ingress Controller (GKE Load Balancer, AWS ALB, AKS Application Gateway, nginx, Kong, …​ )

Installation

This installation procedure fetches the helm charts from Trisotech official container registry (registry.trisotech.com). To use a private container registry, follow the instruction under the Private Container Registry page.

The installation is templated using helm charts.

Downloading the DES helm chart

Login to the Trisotech registry using this command:

helm registry login -u license registry.trisotech.com

When prompted for a password, use the Trisotech DDC license to authenticate.

Download the helm chart using this command:

helm pull oci://registry.trisotech.com/des/charts/ddc --version <VERSION>

Replace <VERSION> with the current version of the Digital Enterprise Suite. You can consult our release notes page to find the latest version available.

Installing using helm

Default installation can be done using this command:

 helm upgrade --install \
      --set image.repository=<DDC_IMAGE>
      --set image.tag=<TAG> \
      --set image.pullSecrets=<PULL_SECRET> \
      --set ddc.LICENSE=<LICENSE> \
      --set ingress.hosts[0]=<DNS_NAME> \
      --wait \
      --namespace=ddc \
      --create-namespace \
      --atomic \
      <DDC_NAME> ddc-<VERSION>.tgz

Replace <DDC_IMAGE> and <TAG> with the DDC image location. For an image that would be under my.org/ddc:1.0.0, <DDC_IMAGE> is my.org/ddc and the <tag> is 1.0.0.

Replace <PULL_SECRET> with the name of the pull secret that you want to use for the container image.

Replace <DDC_NAME> with the deployment name you want to give to this DDC. Typically, you will have different DDC images deployed at the same time.

Replace <DNS_NAME> with the ingress host name to use. This is the URL under which the DES will be accessible.

You can also add multiple ingress names.

If you wish to install in a different namespace than ddc, you can change that value in the --namespace=ddc command line option.

Customizing the ingress controller

By default, the chart will use an nginx ingress by setting the ingress className to nginx. It will also by default generate annotations for nginx ingress and for the Let’s Encrypt certificate manager. These extra annotations should be ignored by another ingress controller.

Ingress Controller

To change the ingress controller to a different ingress class, add the command line parameter to the helm installation:

--set ingress.className=nginx

You can also add an ingress annotations by adding the command line parameter(s) to the helm installation:

--set ingress.annotations."my\.ingress\.annotation"=value1
--set ingress.annotations."my\.other\.ingress\.annotation"=value2
...

TLS

To generate a tls section to the ingress to instruct the controller on which hosts require tls (https) and where the secret containing the certificate is, you can add the command line parameter(s) to the helm installation:

--set ingress.tls=true

This adds a tls section to the ingress with a secret named des-des-tls that you will need to fill with the tls secret.

To create this secret, you will need to create a secret containing:

Variable

Definition

NAME

The helm instance name (can be obtained using helm ls)

KEY

The file containing the RSA key

CERT

The certificate with chain
The certificate must contain all intermediates and the root certificate. They must be concatenated in order of precision (certificate, intermediate certificate, root certificate)

Here is the command to add the tls secret:

kubectl create secret tls des-des-tls \
        --key=<KEY> \
        --cert=<CERT>

Using nginx and Let’s Encrypt

If there is no existing ingress controller, the DES can work with the open source nginx ingress controller using https certificates managed by Let’s Encrypt.

First install nginx using helm:

kubectl create namespace ingress-basic

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

helm upgrade --install nginx-ingress ingress-nginx/ingress-nginx \
    --namespace ingress-basic \
    --create-namespace \
    --set rbac.create=true

Then install the certificate manager from Let’s Encrypt:

kubectl create namespace cert-manager

helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set installCRDs=true

Confirm that each pod is in running state:

kubectl get pods --namespace cert-manager

Create the cluster issuer (Cert-Manager configuration):

cat << EOF > cluster-issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: <EMAIL_ADDRESS>
    privateKeySecretRef:
      name: letsencrypt
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

kubectl apply -f cluster-issuer.yaml

Replacing <EMAIL_ADDRESS> with your email address.

Custom Ingress Definition

To disable the ingress generation and generate custom ingress separately, add the command line parameter to the helm installation:

--set ingress.enabled=false

Customizing storage

By default, the DDC is deployed stateless without storage (persistent volume or mongodb).

Persistent Storage

To activate persistent storage, add the command line parameter to the helm installation:

--set storage.enabled=true

The requested storage will be of the default storage class with a size of 10Gi.

You can see the default storage class by executing the command kubectl get storageclass and looking at which one of the storage is marked with a (default) annotation after its name. You may also want to choose a storage class that allows resizing of the volume (ALLOWVOLUMEEXPANSION property) also displayed by this command.

storage.size can only be updated after installation if supported by the storage class (see ALLOWVOLUMEEXPANSION value)

To change from the default storage class to a different one, add the command line parameter to the helm installation:

--set storage.storageClassName=my-storage-class
The chosen storage class is required to support extended file attributes.

To change the disk size, add the command line parameter to the helm installation:

--set storage.size=30Gi

Replace the size with the size that you would want.

When using the persistent storage, there are advanced parameters that can be added to the command line of the helm installation (the ddc. prefix is required):

--set ddc.PERSISTENCE_FS_LOCK=60
--set ddc.PERSISTENCE_FS_LOCK_LIMIT=5000
--set ddc.PERSISTENCE_FS_LOCK_WAIT=100
Configurations Variable Required Description

PERSISTENCE_FS_LOCK

Optional

Number of milliseconds to consider a lock still valid on an instance. Defaults to 60 seconds.

PERSISTENCE_FS_LOCK_LIMIT

Optional

Maximum time (in milliseconds) to try to acquire a lock. Defaults to 5000.

PERSISTENCE_FS_LOCK_WAIT

Optional

Interval (in milliseconds) between trying to acquire locks. Defaults to 100 ms.

MongoDB Storage

To activate the MongoDB storage, add the command line parameter to the helm installation (the ddc. prefix is required):

--set ddc.PERSISTENCE_TYPE=mongo
--set ddc.PERSISTENCE_MONGO_CONNECTION=Connection String
--set ddc.PERSISTENCE_MONGO_USER=User
--set ddc.PERSISTENCE_MONGO_PASSWORD=Password

Complete list of configuration variables and their description

Configurations Variable Required Description

PERSISTENCE_TYPE

Required

Set to mongo to use the MongoDB service storage.

PERSISTENCE_MONGO_CONNECTION

Required

The connection string of MongoDB.

PERSISTENCE_MONGO_USER

Optional

The username to connect to MongoDB. This can also be defined in the connection string.

PERSISTENCE_MONGO_PASSWORD

Optional

The password to connect to MongoDB. This can also be defined in the connection string.

PERSISTENCE_MONGO_DATABASE

Optional

When using a username/password, authorization could be done on a different database than admin.

PERSISTENCE_MONGO_LOCK

Optional

Number of milliseconds to consider a lock still valid on an instance. Defaults to 60 seconds.

PERSISTENCE_MONGO_LOCK_LIMIT

Optional

Maximum time (in milliseconds) to try to acquire a lock. Defaults to 5000.

PERSISTENCE_MONGO_LOCK_WAIT

Optional

Interval (in milliseconds) between trying to acquire locks. Defaults to 100 ms.

Customizing Logging

Logging can be adapted to the log ingestor used by setting the logging helm variables.

Configuring email sending

To activate the sending emails from the DDC, add the command line parameter to the helm installation (the ddc. prefix is required):

--set ddc.SMTP_HOST=smtp.org
--set ddc.SMTP_PORT=25
--set ddc.SMTP_TLS=true
--set ddc.SMTP_USERNAME=User
--set ddc.SMTP_PASSWORD=Password

Complete list of configuration variables and their description

Configurations Variable Required Description

SMTP_HOST

Required

SMTP hostname.

SMTP_PORT

Required

SMTP port number.

SMTP_TLS

Optional

Set to "true" if the SMTP port requires TLS, omit otherwise (or set to "false").

SMTP_USERNAME

Optional

Optional username for the SMTP server if it is required.

SMTP_PASSWORD

Optional

Optional password for the SMTP server if it is required.

EMAIL_FROM

Optional

An email address to use in the FROM field if none was provided when sending an email.

EMAIL_TO

Optional

An email address to use in the TO field if none was provided when sending an email.

Customizing the timezone

By default, the pod clock will be set to UTC. We do not recommend that you change that value but if you wish to do so, you can set the timezone based on the values enumerated on Wikipedia for TZ by adding to the command line parameter to the helm installation:

--set timezone=UTC

And changing the value from UTC to America/New_York, Europe/Paris, …​