Output Organizer Helm chart

This chart bootstraps an Output Organizer on a Kubernetes cluster using the Helm package manager.

Output Organizer is a scalable web based solution for assembling and annotating documents, and generating output documents to be processed in other applications.

As you can see, the chart provisions four deployments (subchart names in brackets):

• Output Organizer backend ("organizer")
• jadice web viewer ("viewer")
• controller ("controller")
• export worker ("worker-topdf")

Sample configuration

Prior to installing the Helm chart, you need to provide some required parameters. A minimal values.yaml with these required parameters looks like this:

my-values.yaml

##
# Global configuration to be used by all sub components
##
global:
  imageRegistry: "registry.jadice.com" # Global Docker image registry

  # Two external ingress configuration have defined for your organizer application.
  urls:
    fusion:
      externalUrl: https://my-output-organizer.com
    viewer:
      externalUrl: https://my-output-organizer-viewer.com

##
# Secrets for sensitive information:
# -> to use encrypted 'sealed-secrets' see: https://github.com/bitnami-labs/sealed-secrets
##
secrets:
  useSealedSecrets: true
  # Depending on your configuration of secrets.useSealedSecrets this config has to be configured differently.
  # If you don't use sealed secrets the registry credentials can be put here in the fields 'server', 'username' and 
  # 'password'.
  # If you use sealed secrets you have to create a docker config JSON string, seal it and put it in the 
  # 'dockerconfigjson' field.
  imageRegistry:
    # Option 1:
    server: "***"
    username: "***"
    password: "***"
    # Option 2:
    dockerconfigjson: "***"

##
# Organizer specific configuration
##
organizer:
  ingress:
  # insert your ingress config here.
  resources:
  # insert your resources config here.
  
  ## Secrets for the DB to store fusion collections in. (this section depends on the configured DB -  default is H2)
  db:
    username: "***"
    password: "***"

##
# Viewer specific configuration
##
viewer:
  ingress:
  # insert your ingress config here.
  resources:
  # insert your resources config here.

##
# Controller specific configuration
##
controller:
  resources:
  # insert your resources config here.

##
# Exporter specific configuration
##
worker-topdf:
  resources:
  # insert your resources config here.

Install the helm chart with your values applied:

$ helm repo add levigo https://artifacts.jadice.com/repository/helm-charts/ --username <username> --password <password>
$ helm upgrade --install --namespace my-namespace --values my-values.yaml my-release levigo/fusion-output-organizer

---

Prerequisites

Kubernetes

• Kubernetes 1.14+
• Helm 3.1.0+
• (optional but recommended: sealed secrets )

Container Image Access

Because the images used in this chart are from a private container registry, you need to have access to the container registry registry.jadice.com or access to a proxy of the same registry.

For details see image pull secrets.

---

Installing the Chart

To install the chart with the release name my-release from levigo helm repository:

$ helm repo add levigo https://artifacts.jadice.com/repository/helm-charts/ --username <username> --password <password>
$ helm install --namespace my-namespace --values my-values.yaml my-release levigo/fusion-output-organizer

The command deploys fusion-output-organizer on the Kubernetes cluster in the default configuration. The configuration section lists the parameters that can be configured during installation.

Uninstalling the Chart

To uninstall/delete the my-release deployment:

$ helm delete my-release

The command removes all the Kubernetes components associated with the chart and deletes the release.

---

Configuration

The following tables lists the configurable parameters of the fusion-output-organizer chart and their default values.

Universal service settings

Let's start with universal settings for Kubernetes. These can be applied to every service in the values file. The <service>placeholder has to be replaced with a deployed kubernetes service alias like organizer, viewer, etc. these Aliases can be found in the chart.yaml and as prefix in the values file.

Parameter	Description
<service>.resources.requests.cpu	CPU units for the service to be allocated initially.
<service>.resources.requests.memory	Memory size for the service to be allocated initially.
<service>.resources.limits.cpu	Maximum CPU units that can be used by the service.
<service>.resources.limits.memory	Maximum Memory size that can be used by the service.
<service>.ingress.enabled	Enable / Disable the ingress for a service. In order for this service to work, user access is needed, hence some kind of access for an operator has to be provided.
<service>.ingress.annotations	Additional annotations for configuring the ingress.
<service>.ingress.hosts	The hostname of the service and eventual path rewrites.
<service>.ingress.tls	For configuring the corresponding TLS secrets of the previously defined hostnames.
<service>.ingress.ingressClassName	The ingress class name.
<service>.management.endpoints.web.exposure.include	Set which endpoints are exposed.
<service>.management.prometheus.metrics.export.enabled	Export prometheus metrics.
<service>.management.jmx.metrics.export.enabled	Export JMX metrics.
<service>.startupProbe.initialDelaySeconds	Initial delay of the startup probe in seconds.
<service>.startupProbe.periodSeconds	Time between requests for the startup probe in seconds.
<service>.startupProbe.timeoutSeconds	Maximum response time for the startup probe in seconds.
<service>.startupProbe.successThreshold	How often a startup probe has to succeed for the pod to be considered healthy.
<service>.startupProbe.failureThreshold	How often a startup probe is allowed to fail before the pod is considered unhealthy.
<service>.livenessProbe.initialDelaySeconds	Initial delay of the liveness probe in seconds.
<service>.livenessProbe.periodSeconds	Time between requests for the liveness probe in seconds.
<service>.livenessProbe.timeoutSeconds	Maximum response time for the liveness probe in seconds.
<service>.livenessProbe.successThreshold	How often a liveness probe has to succeed for the pod to be considered healthy.
<service>.livenessProbe.failureThreshold	How often a liveness probe is allowed to fail before the pod is considered unhealthy.
<service>.readinessProbe.initialDelaySeconds	Initial delay of the readiness probe in seconds.
<service>.readinessProbe.periodSeconds	Time between requests for the readiness probe in seconds.
<service>.readinessProbe.timeoutSeconds	Maximum response time for the readiness probe in seconds.
<service>.readinessProbe.successThreshold	How often a readiness probe has to succeed for the pod to be considered healthy.
<service>.readinessProbe.failureThreshold	How often a readiness probe is allowed to fail before the pod is considered unhealthy.
<service>.securityContext	Contains general security information for an individual pod depending on your environment5
<service>.podSecurityContext	Contains security information for an individual pod depending on your environment5
<service>.affinity	Configuration for service pod affinity6
<service>.nodeSelector	Configuration for service pod node selection6
<service>.tolerations	Configuration for service pod tolerations6

Secrets

The chart also supports the use of Sealed Secrets instead of regular Kubernetes secrets. Sealed Secret values can also be specified directly in the Helm values.yaml. Simply set secrets.useSealedSecrets to true and use the encrypted values for all parameters in the section "secrets". For further information on how to encrypt secrets see table in the Sealed Secrets section.

Image pull secrets

To access the container registry you have the following three options:

1. Provide the name of an existing Kubernetes registry-secret via global.imagePullSecrets.

   For instructions on how to create a Kubernetes docker-registry secret check out the Documentation or the output of kubectl create secret docker-registry --help

2. Provide the credentials to the registry via the following parameters:

   Parameter	Description	Default
   secrets.imageRegistry.server	Server of the container registry	registry.jadice.com
   secrets.imageRegistry.username	Username for the container registry	nil
   secrets.imageRegistry.password	Password for the container registry	nil

3. For sealed secrets, you can encrypt the content of a ~/.docker/config.json file as a String and provide this as the value for the parameter secrets.imageRegistry.dockerconfigjson.

   To create this String you could run the following command

   kubectl create secret docker-registry registry-secret \
     --docker-username=<user> \
     --docker-password=<password> \
     --docker-server=registry.jadice.com \
     --dry-run=client -o json | jq -r '.data[".dockerconfigjson"]' | base64 -d | kubeseal --raw --from-file=/dev/stdin --namespace <namespace> --name registry-secret

   Note:

   • Requires jq and kubeseal
   • Replace <user>, <password>, <namespace> with the respective values.

Global Parameters

These values can be defined globally, overwriting the values defined for each component, including MariaDB.

Parameter	Description	Default
global.imageRegistry	Global Docker image registry	nil
global.imagePullSecrets	Global Docker registry secret names as an array	["registry-secret"]
global.storageClass	Global storage class for dynamic provisioning	nil
global.urls.fusion.externalUrl	External url for the fusion backend configured by ingress	nil
global.urls.fusion.serviceUrl	Kubernetes service url fot accessing the fusion service cluster internally	http://fusion-output-organizer-default
global.urls.viewer.externalUrl	External url for the viewer backend configured by ingress	nil
global.config.annotationProfile	Annotation configuration profile used by all Fusion Service in the cluster see	<Default Profile ...>

Output Organizer ("organizer")

The base configuration of output organizer includes all necessary configuration setting to run the fusion backend as is. If you like to customize your deployment the following configuration settings can be used:

Parameter	Description	Default
organizer.flow.export.enabled	Flag to enable export.	true
organizer.flow.export.jobType	The job type of the worker	jf-single:fusion-export
organizer.exportNotification.enabled	Flag to enable export notification	false
organizer.exportNotification.url	The url of the endpoint
organizer.exportNotification.auth.userAuth.enabled	Flag to use user auth for the to be notified service	false
organizer.exportNotification.auth.basicAuthenticated.enabled	Flag to enable Basic auth for the to be notified service	false
organizer.exportNotification.auth.bearerAuthenticated.enabled	Bearer auth for the to be notified service	false
organizer.config.collectionTypeDefinitions	Configuration property contains a list of custom collection type definition files see.
organizer.config.collectionTypeNames	Lists the corresponding collection type names to the definitions defined in 'collectionTypeDefinitions'. The name must be the same as the ID defined in the collection definition json. The order of elements has to match its counterpart in 'collectionTypeDefinitions' see.
organizer.config.policyDefinitions	Configuration property contains a list of custom access policy definition files see.
organizer.config.policyValidityDate	Lists the corresponding validity date of the access policies defined in 'policyDefinitions'. The date has to follow the date schema "yyyyMMdd-HHmmss-SSS". The active policy is always the policy with the newest validity that is not set in the future. The order of elements has to match its counterpart in 'policyDefinitions' see.
organizer.config.styles	Configuration property contains a css to modify the frontend appearance see.
organizer.config.logos	Configuration property allows the replacement of the default application logo see.
organizer.config.favicon	Configuration property allows the replacement of the default application favicon see.
organizer.config.zoomAutoFit	Configures the default zoom behaviour. 'true' adjusts zoom automatically depending on the size of the document, 'false' simply sets the zoom level to 100%.	true
organizer.config.xframeOptions	Configures the X-Frame-Options header. Possible values: 'deny', 'sameorigin', 'disable'.	deny
organizer.loaders.localHostRedirect	If your storage source for documents uses the same host address but is not reachable as localhost form the fusion application server, you can turn off this redirect. (This redirect removes the need for an ingress routing to locally stored documents and therefore improves performance.)	true
organizer.logging.pattern	Allows you to define a custom logging pattern (see)
organizer.logging.level.*	Allows you to configure logging levels on a package or class basis (see)
organizer.db.jdbcURL	Database JDBC-URL	jdbc:h2:mem:fusiondb
organizer.db.driverClassName	Database Driver name	org.h2.Driver
organizer.db.databasePlatform	Database language dialect	org.hibernate.dialect.H2Dialect
organizer.storage.directory	Custom Data directory for uploaded documents and temporary data	/home/nonroot/data
organizer.storage.sizeLimit	Local container size limit for uploaded documents and temporary data in mb	20480
organizer.storage.ehcache.enabled	Enable EHCache storage (disable other storage solutions)	true
organizer.storage.ehcache.pagingFileSizeLimit	Disc cache size in mb (has to be smaller that organizer.storage.sizeLimit)	18432
organizer.storage.ehcache.heapEntries	Heap cache size in number of entities	500
organizer.storage.ehcache.expiryTimeMinutes	Cache expiry time for cache data to be cleaned up after.	1440
organizer.storage.s3.enabled	Enable s3 storage (disable other storage solutions)	false
organizer.truststore.enabled	Enable a custom truststore for the container.	false
organizer.truststore.cacerts	Truststore with custom (root) certificatessee.
organizer.jadice.licenseConfiguration.license	The license field contains the necessary license information
organizer.jadice.licenseConfiguration.fingerprint	The unique fingerprint associated with your license
organizer.jadice.licenseConfiguration.publicKey	The public key that corresponds to the license. The public key is necessary for validating the authenticity of the license.

Recommendation: Note that pod replication is automatically set to 1 when H2 is used. Since H2 is an in-memory database, it may not be suitable for high load scenarios. Therefore, consider using MariaDB instead of H2 for better scalability and multiple instances. If scalability is an issue, switch to MariaDB and adjust the configuration accordingly.

Recommendation: Note that pod replication is automatically set to 1 when H2 is used. Since H2 is an in-memory database, it may not be suitable for high load scenarios. Therefore, consider using MariaDB instead of H2 for better scalability and multiple instances. If scalability is an issue, switch to MariaDB and adjust the configuration accordingly.

Jadice web viewer ("viewer")

Jadice web viewer provides the document viewer to display most file formats in the browser frontend. Here are the configuration settings for the jadice web viewer:

Parameter	Description	Default
viewer.contextPath	Allows you to configure the context path of the application (e.g. /foobar.mycompany.de/levigo/viewer)	/
viewer.serverConnection	Connection type for communication between the viewer client and its backend server. Possible values: WebSocket, LongPoll, ServerSentEvents	WebSocket

Jadice Flow controller ("controller")

Jadice flow controller manages and coordinates export jobs initiated by the users. All jobs are started by requesting their execution at the controller, the controller then redirects them to a worker responsible for the export.

Parameter	Description	Default
controller.workers	Configuration property allows the replacement of the default worker configuration see.	<Default Configuration ...>
controller.jobtemplates	Configuration property allows the replacement of the default job template configuration see.	<Default Configuration ...>

Jadice Flow export worker ("worker-topdf")

Jadice Flow worker-topdf combines collection documents to create the desired export document stream.
For settings see

Sealed Secrets

To encrypt sealed secrets you need to provide the cluster namespace, secret name, secret key and a secret value. The namespace can be chosen freely, the rest can be filled according to the following table. (All placeholders in the value fields have to be replaced with the actual values.)

secret-name	secret-key	secret-value
registry-secret	.dockerconfigjson	{'auths':{'registry.jadice.com':{'username':'[USER]','password':'[PASSWORD]','email':'[EMAIL]','auth':'[TOKEN]'}}}
database-secret	password	[PASSWORD]
db-secret	username	[USERNAME]
loader-auth-secret	loader-password	[PASSWORD]
loader-auth-secret	loader-user	[USER]
loader-auth-secret	loader-token	[TOKEN]
oauth-secret	app-id-uri	api://[APP_ID]
oauth-secret	client-id	[APP_ID]
oauth-secret	issuer	[ISSUER_URL]
oauth-secret	scope	[SCOPE]
s3-secret	s3-access-key	[KEY]
s3-secret	s3-bucket	[NAME]
s3-secret	s3-endpoint	[URL]
s3-secret	s3-secret-key	[KEY]
sba-secret	sba-password	[PASSWORD]
sba-secret	sba-user	[USER]
export-notification-auth-secret	export-notification-username	[USERNAME]
export-notification-auth-secret	export-notification-password	[PASSWORD]
export-notification-auth-secret	export-notification-bearer-token	[BEARER_TOKEN]
save-notification-auth-secret	save-notification-username	[USERNAME]
save-notification-auth-secret	save-notification-password	[PASSWORD]
save-notification-auth-secret	save-notification-bearer-token	[BEARER_TOKEN]