Dossier Organizer: Installation
levigo provides a Helm chart to install and operate Dossier Organizer within a Kubernetes cluster. Functionality is approved with Azure Kubernetes Service, but using a custom on-premise system is also possible. 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 Dossier Organizer deployment. The Helm chart provisions all required pods:
loading...Don't be confused - the components are grouped by functionality here - this does not imply that these components are deployed to different namespaces or the like.
Viewer
- jwt-viewer: The jadice web toolkit document viewer allows to view, change and annotate documents.
Organizer
- organizer: This pod provides Dossier Organizer's core functionality - the ability to view and organize collections.
DB
- collection data: The db can be hosted inside the cluster or externally. the Organizer container has to be able to reach the db with a good bandwidth.
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 Dossier Organizer Helm chart will then be available at:
https://artifacts.jadice.com/repository/helm-charts/fusion-dossier-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
Dossier Organizer requires two externally reachable hosts:
myorganizer.mycompany.com - for the Dossier 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
my-deploy-dossier-workflow-action.yaml
dossier-organizer
my-values.yaml
Helm configuration
In general, please follow the steps described in the Kubernetes deployment of the Dossier 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 Dossier 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, Dossier 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 | only for test installations, since in-memory Note that pod replication is automatically set to 1 when H2 is used. |
| MariaDB | org.mariadb.jdbc.Driver | jdbc:mariadb://mydb/fusion | org.hibernate.dialect.MariaDBDialect | Default, if nothing else is specified |
| 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.SQLServerDriver | jdbc:sqlserver://mydb;databaseName=fusion | org.hibernate.dialect.SQLServerDialect |
Installing the Helm charts
Installation
Follow the steps described in the Kubernetes deployment of the Dossier 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-dossier-organizer/values.yaml fusion-dossier-organizer levigo/fusion-dossier-organizer
Verifying the installation
Check that your pods are up and running.
Call the public-facing URL of your installation, as it was configured in the fusion Ingress, for example: https://my-organizer.mydomain.com/