Output Organizer: Installation
levigo provides a Helm chart to install and operate Output Organizer within a Kubernetes cluster. The chart is verified to work on Azure, Rancher, Tanzu, OpenShift and many more.
A reasonable understanding of Kubernetes and Helm concepts is required to follow the installation instructions.
Architecture
Deployment
The diagram below provides a high level overview of a Output Organizer deployment. The Helm chart provisions all required pods:
loading...The worker pods can be expanded to include custom functionality for your workflow. By default, a default export worker is included.
Viewer
- viewer: The jadice web toolkit document viewer allows to view, modify and annotate documents.
Organizer
- organizer: The organizer pod provides the Output Organizer's core functionality - the ability to upload, assemble and modify documents prior to generating an output document.
- document storage: Since input and output documents have a very limited lifetime, they can be stored in an ephemeral system volume.
- runtime data: Document metadata and annotations are stored in a configured database. By default, the database is an embedded H2.
controller
- controller: The flow controller is part of the flow data processing and is responsible to queue and distribute long-running tasks.
workers
- worker-topdf: The to-PDF worker is a exporter that generates the desired PDF output document(s)
- Other optional workers can be deployed on demand. These workers can be included by modifying the job templates. For more information see additional configuration
Only viewer and organizer pods need a configured Ingress for an external URL. All communication through external systems should use the Fusion REST API.
Data flow
The next diagram shows how the public facing components are accessed and how the components interact.
loading...Preparing the installation
Prerequisites
- Kubernetes 1.14+
- Helm 3.1.0+
- Ingress Controller with sticky session support, e.g. NGINX
- Optional: sealed secrets
Registry access
Contact your levigo representative to get access to the repositories:
- Helm Charts: https://artifacts.jadice.com/repository/helm-charts/
- Container Images: http://registry.jadice.com
The Output Organizer Helm chart will then be available at:
https://artifacts.jadice.com/repository/helm-charts/fusion-output-organizer-x.y.z.tgz
Create Kubernetes cluster
Create Kubernetes cluster. For Azure, you can follow the instructions according to how to Deploy an Azure Kubernetes Service cluster.
Configure Kubernetes cluster
Perform preliminary steps to prepare the cluster for the new deployment, at least:
- Check/increase CPU and memory quotas
- Create a namespace
- Check/increase max nodes in autoscaler (optional)
Hostnames and CNAME records for external hosts
Output Organizer requires two externally reachable hosts:
myorganizer.mycompany.com - for the Output Organizer backend and frontend myviewer.mycompany.com - for the document viewer
It is good practice to define the hostnames upfront since they are part of the Helm configuration.
CNAME records (example):
myorganizer.mycompany.com → <myorg>.westeurope.cloudapp.azure.com
myviewer.mycompany.com → <myorg>.westeurope.cloudapp.azure.com
(Optional) Create a project to hold configuration values and trigger deployment workflow
Typically, we create a project repository providing the Helm configuration and set up a workflow to install/update the cluster. Any repository and deployment mechanism that allows Helm commands will suffice. In our example, we assume a GitHub repository with an attached GitHubAction workflow. The project structure can be set up as follows:
Project structure for Helm deployment:
/MyHelmRepo
.github
workflows
deploy-output-org-workflow.yaml
output-organizer
my-values.yaml
Helm configuration
In general, please follow the steps described in the Kubernetes deployment of the Output Organizer Helm chart. In the following paragraphs, you can find additional remarks on specific topics.
Sealing Secrets
In case you are relying on Sealed Secrets, please make sure you encrypt the secrets with your Sealed Secrets Controller in the Cluster. For details on how the secrets are constructed, see the Kubernetes deployment in the Output Organizer Helm chart. Provide the namespace (as defined above) and the predefined names (as listed in Kubernetes deployment) when generating the sealed values. Afterward, enter the encrypted values in your values.yaml.
Ingress
For the Ingress configuration any ingress with sticky sessions will suffice. The Ingress Controller itself has to be configured in the cluster management. Here is a sample configuration for the "fusion" StatefulSet using nginx:
ingress:
enabled: true
className: "nginx"
annotations:
cert-manager.io/cluster-issuer: "letsencrypt"
nginx.ingress.kubernetes.io/proxy-body-size: 100m
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"
nginx.ingress.kubernetes.io/ssl-redirect: "true"
nginx.ingress.kubernetes.io/configuration-snippet: |
server_tokens off;
location /actuator {
deny all;
return 403;
}
hosts:
- host: myorganizer.mycompany.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: <myorganizer-ingress-tls-secret-name>
hosts:
- myorganizer.mycompany.com
CPU, Memory and Storage
Here services deployed by our fusion chat can be customized in terms of resources. we strongly recommend to adjust these values when scaling the application or to improve stability and performace. A sample configuration would look like this:
resources:
requests:
cpu: 500m
memory: 1024Mi
ephemeral-storage: "1024Mi"
limits:
cpu: 500m
memory: 1024Mi
ephemeral-storage: "1024Mi"
For sizing recommendations see fusion sizing.
(Optional) Database Configuration
In addition to the pre-configured MariaDB default database, Output Organizer supports a variety of Databases over JPA. This enables you to connect to existing database instances. The database can be configured using a JDBC URL, a Driver Class and a DB Dialect. Our configuration is set up similar to the Spring Boot JPA configuration. To help you set the correct values for your database we compiled a list of examples for the different databases:
driver-class (organizer.db.driverClassName) | jdbc-url (organizer.db.jdbcURL) | database-platform / dialect (organizer.db.databasePlatform) | Comment | |
|---|---|---|---|---|
| H2 | org.h2.Driver | jdbc:h2:mem:fusion | org.hibernate.dialect.H2Dialect | Default, only for use with a single organizer instance |
| MariaDB | org.mariadb.jdbc.Driver | jdbc:mariadb://mydb/fusion | org.hibernate.dialect.MariaDBDialect | |
| MySQL | com.mysql.jdbc.Driver | jdbc:mysql://mydb/fusion | org.hibernate.dialect.MySQL8Dialect | |
| PostgreSQL | org.postgresql.Driver | jdbc:postgresql://mydb/fusion | org.hibernate.dialect.PostgreSQL95Dialect | |
| MSSQL | com.microsoft.sqlserver.jdbc.SQLServerDrive | jdbc:sqlserver://mydb;databaseName=fusion | org.hibernate.dialect.SQLServer2012Dialect |
Installing the Helm charts
Installation
Follow the steps described in the Kubernetes deployment of the Output Organizer Helm chart. Basically, you need to perform the following steps:
- Add levigo registry using provided credentials
- Update helm repo
- Install charts from levigo registry with configuration defined in the previously created values.yaml file
helm repo add levigo "<https://artifacts.jadice.com/repository/helm-charts/>" --username "<username>" --password "<password>"
helm repo update
helm upgrade --install --namespace my-namespace --values ./my-output-organizer/values.yaml fusion-output-organizer levigo/fusion-Output-organizer
Verifying the installation
You can check the state of yor cluster using kubectl or any available cluster management UI. If all pods are running and report as ready, your installation is successful.
Now you can check the public-facing Ingress URL of the organizer pod in a web browser of your choice for example: https://my-organizer.mydomain.com/
Here you should see the landing page of the Output Organizer web application:
