Euro-Office Docs for Kubernetes

This repository contains a set of files to deploy Euro-Office Docs into a Kubernetes cluster or OpenShift cluster.

Contents

• Requirements
• Introduction
• Deploy prerequisites
  • 1. Add Helm repositories
  • 2. Install Persistent Storage
  • 3. Deploy RabbitMQ
  • 4. Deploy Redis
  • 5. Deploy Database
  • 6. Deploy StatsD exporter
    • 6.1 Add Helm repositories
    • 6.2 Installing Prometheus
    • 6.3 Installing StatsD exporter
  • 7. Make changes to Node-config configuration files
    • 7.1 Create a ConfigMap containing a json file
    • 7.2 Specify parameters when installing Euro-Office Docs
  • 8. Add custom Fonts
  • 9. Add Plugins
  • 10. Add custom dictionaries
  • 11. Change interface themes
    • 11.1 Create a ConfigMap containing a json file
    • 11.2 Specify parameters when installing Euro-Office Docs
  • 12. Connecting Amazon S3 bucket as a cache to Euro-Office Helm Docs
• Deploy Euro-Office Docs
  • 1. Deploy the Euro-Office Docs license
    • 1.1 Create secret
    • 1.2 Specify parameters when installing Euro-Office Docs
  • 2. Deploy Euro-Office Docs
  • 3. Uninstall Euro-Office Docs
  • 4. Parameters
  • 5. Configuration and installation details
  • 5.1 Example deployment (optional)
  • 5.2 Metrics deployment (optional)
  • 5.3 Expose Euro-Office Docs
    • 5.3.1 Expose Euro-Office Docs via Service (HTTP Only)
    • 5.3.2 Expose Euro-Office Docs via Ingress
    • 5.3.2.1 Installing the Kubernetes Nginx Ingress Controller
    • 5.3.2.2 Expose Euro-Office Docs via HTTP
    • 5.3.2.3 Expose Euro-Office Docs via HTTPS
    • 5.3.2.4 Expose Euro-Office Docs via HTTPS using the Let’s Encrypt certificate
    • 5.3.2.5 Expose Euro-Office Docs on a virtual path
    • 5.3.3 Expose Euro-Office Docs via route in OpenShift
  • 5.4 Admin Panel deployment (optional)
  • 6. Scale Euro-Office Docs (optional)
    • 6.1 Horizontal Pod Autoscaling
    • 6.2 Manual scaling
  • 7. Update Euro-Office Docs
  • 8. Shutdown Euro-Office Docs (optional)
  • 9. Update Euro-Office Docs license (optional)
  • 10. Euro-Office Docs installation test (optional)
  • 11. Run Jobs in a private k8s cluster (optional)
  • 12. Access to the info page (optional)
• Using Grafana to visualize metrics (optional)
  • 1. Deploy Grafana
    • 1.1 Deploy Grafana without installing ready-made dashboards
    • 1.2 Deploy Grafana with the installation of ready-made dashboards
  • 2 Access to Grafana via Ingress
  • 3. View gathered metrics in Grafana

Requirements

• Kubernetes version no lower than 1.19+ or OpenShift version no lower than 3.11+
• A minimum of two worker nodes is required for the Kubernetes cluster
• Resources for the cluster hosts: 4 CPU \ 8 GB RAM min
• Kubectl is installed on the cluster management host
• Helm v3.15+ is installed on the cluster management host

Introduction

• You must have a Kubernetes or OpenShift cluster installed. Please, checkout the reference to set up Kubernetes. Please, checkout the reference to setup OpenShift.
• Although installation is possible using the Kubernetes cluster version 1.19+, we recommend using at least one of three latest minor release versions.
• You should also have a local configured copy of kubectl. See this guide how to install and configure kubectl.
• You should install Helm v3.15+. Please follow the instruction here to install it.
• If you use OpenShift, you can use both oc and kubectl to manage deploy.
• If the installation of components external to ‘Docs’ is performed from Helm Chart in an OpenShift cluster, then it is recommended to install them from a user who has the cluster-admin role, in order to avoid possible problems with access rights. See this guide to add the necessary roles to the user.
• To install Docs into an OpenShift cluster, it may be necessary to grant a specific SecurityContextConstraints policy. This policy provides permission to run containers using a user with ID = 101 and ID = 1001. For more information, see OPENSHIFT.md file.

Deploy prerequisites

1. Add Helm repositories

$ helm repo add bitnami https://charts.bitnami.com/bitnami
$ helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
$ helm repo add nfs-server-provisioner https://kubernetes-sigs.github.io/nfs-ganesha-server-and-external-provisioner
$ helm repo add euro-office https://download.euro-office.com/charts/stable
$ helm repo update

2. Install Persistent Storage

If you want to use Amazon S3 as a cache, please skip this step.

Install NFS Server Provisioner

Note: When installing NFS Server Provisioner, Storage Classes - NFS is created. When installing into an OpenShift cluster, the user must have a role that allows you to create Storage Classes in the cluster. Read more here.

$ helm install nfs-server nfs-server-provisioner/nfs-server-provisioner \
  --set persistence.enabled=true \
  --set persistence.storageClass=PERSISTENT_STORAGE_CLASS \
  --set persistence.size=PERSISTENT_SIZE

• PERSISTENT_STORAGE_CLASS is a Persistent Storage Class available in your Kubernetes cluster.

  Persistent Storage Classes for different providers:

  • Amazon EKS: gp2
  • Digital Ocean: do-block-storage
  • IBM Cloud: Default ibmc-file-bronze. More storage classes
  • Yandex Cloud: yc-network-hdd or yc-network-ssd. More details
  • minikube: standard

• PERSISTENT_SIZE is the total size of all Persistent Storages for the nfs Persistent Storage Class. You can express the size as a plain integer with one of these suffixes: T, G, M, Ti, Gi, Mi. For example: 9Gi.

See more details about installing NFS Server Provisioner via Helm here.

Configure a Persistent Volume Claim

Note: The default nfs Persistent Volume Claim is 8Gi. You can change it in the values.yaml file in the persistence.storageClass and persistence.size section. It should be less than PERSISTENT_SIZE at least by about 5%. It’s recommended to use 8Gi or more for persistent storage for every 100 active users of Euro-Office Docs.

The PersistentVolume type to be used for PVC placement must support Access Mode ReadWriteMany. Also, PersistentVolume must have as the owner the user from whom the Euro-Office Docs will be started. By default it is ds (101:101).

Note: If you want to enable WOPI, please set the parameter wopi.enabled=true. In this case Persistent Storage must be connected to the cluster nodes with the disabled caching attributes for the mounted directory for the clients. For NFS Server Provisioner it can be achieved by adding noac option to the parameter storageClass.mountOptions. Please find more information here.

3. Deploy RabbitMQ

To install RabbitMQ to your cluster, run the following command:

$ helm install rabbitmq --version 16.0.14 bitnami/rabbitmq \
  --set persistence.storageClass=PERSISTENT_STORAGE_CLASS \
  --set resourcesPreset=none \
  --set image.repository=bitnamilegacy/rabbitmq \
  --set image.tag=4.1.3-debian-12-r1 \
  --set global.security.allowInsecureImages=true \
  --set metrics.enabled=false

Note: Set the metrics.enabled=true to enable exposing RabbitMQ metrics to be gathered by Prometheus.

See more details about installing RabbitMQ via Helm here.

4. Deploy Redis

To install Redis to your cluster, run the following command:

$ helm install redis --version 22.0.7 bitnami/redis \
  --set architecture=standalone \
  --set master.persistence.storageClass=PERSISTENT_STORAGE_CLASS \
  --set master.resourcesPreset=none \
  --set global.security.allowInsecureImages=true \
  --set image.repository=bitnamilegacy/redis \
  --set image.tag=8.2.1-debian-12-r0 \
  --set metrics.enabled=false

Note: Set the metrics.enabled=true to enable exposing Redis metrics to be gathered by Prometheus. Also add the following parameters: metrics.image.repository=bitnamilegacy/redis-exporter and metrics.image.tag=1.76.0-debian-12-r0.

See more details about installing Redis via Helm here.

5. Deploy Database

As a database server, you can use PostgreSQL, MySQL or MariaDB

If PostgreSQL is selected as the database server, then follow these steps

To install PostgreSQL to your cluster, run the following command:

Note: Set the metrics.enabled=true to enable exposing Database metrics to be gathered by Prometheus. Also add the following parameters: metrics.image.repository=bitnamilegacy/postgres-exporter and metrics.image.tag=0.17.1-debian-12-r16.

See more details about installing PostgreSQL via Helm here.

If MySQL is selected as the database server, then follow these steps

To install MySQL to your cluster, run the following command:

See more details about installing MySQL via Helm here.

Here PERSISTENT_SIZE is a size for the Database persistent volume. For example: 8Gi.

It’s recommended to use at least 2Gi of persistent storage for every 100 active users of Euro-Office Docs.

Note: Set the metrics.enabled=true to enable exposing Database metrics to be gathered by Prometheus. Also add the following parameters: metrics.image.repository=bitnamilegacy/mysqld-exporter and metrics.image.tag=0.17.2-debian-12-r16.

6. Deploy StatsD exporter

This step is optional. You can skip step #6 entirely if you don’t want to run StatsD exporter

6.1 Add Helm repositories

$ helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
$ helm repo add kube-state-metrics https://kubernetes.github.io/kube-state-metrics
$ helm repo update

6.2 Installing Prometheus

To install Prometheus to your cluster, run the following command:

$ helm install prometheus -f https://raw.githubusercontent.com/Euro-Office/Kubernetes-Docs/master/sources/extraScrapeConfigs.yaml prometheus-community/prometheus \
  --set server.global.scrape_interval=1m

To change the scrape interval, specify the server.global.scrape_interval parameter.

See more details about installing Prometheus via Helm here.

6.3 Installing StatsD exporter

To install StatsD exporter to your cluster, run the following command:

See more details about installing Prometheus StatsD exporter via Helm here.

To allow the StatsD metrics in Euro-Office Docs, follow step 5.2

7. Make changes to Node-config configuration files

This step is optional. You can skip step #7 entirely if you don’t need to make changes to the configuration files

7.1 Create a ConfigMap containing a json file

In order to create a ConfigMap from a file that contains the local.json structure, you need to run the following command:

$ kubectl create configmap local-config \
  --from-file=./local.json

Note: Any name can be used instead of local-config.

7.2 Specify parameters when installing Euro-Office Docs

When installing Euro-Office Docs, specify the extraConf.configMap=local-config and extraConf.filename=local.json parameters

Note: If you need to add a configuration file after the Euro-Office Docs is already installed, you need to execute step 7.1 and then run the helm upgrade documentserver euro-office/docs --set extraConf.configMap=local-config --set extraConf.filename=local.json --no-hooks command or helm upgrade documentserver -f ./values.yaml euro-office/docs --no-hooks if the parameters are specified in the values.yaml file.

8. Add custom Fonts

This step is optional. You can skip step #8 entirely if you don’t need to add your fonts

In order to add fonts to Euro-Office Docs, you need to follow a number of steps. See more details here.

9. Add Plugins

This step is optional. You can skip step #9 entirely if you don’t need to add plugins

In order to add plugins to Euro-Office Docs, you need to follow a number of steps. See more details here.

You can also configure the list of default plugins displayed or remove them completely.

10. Add custom dictionaries

This step is optional. You can skip step #10 entirely if you don’t need to add your dictionaries

In order to add your custom dictionaries to Euro-Office Docs, you need to follow a number of steps. See more details here.

11. Change interface themes

This step is optional. You can skip step #11 entirely if you don’t need to change the interface themes

11.1 Create a ConfigMap containing a json file

To create a ConfigMap with a json file that contains the interface themes, you need to run the following command:

$ kubectl create configmap custom-themes \
  --from-file=./custom-themes.json

Note: Instead of custom-themes and custom-themes.json you can use any other names.

11.2 Specify parameters when installing Euro-Office Docs

When installing Euro-Office Docs, specify the extraThemes.configMap=custom-themes and extraThemes.filename=custom-themes.json parameters.

Note: If you need to add interface themes after the Euro-Office Docs is already installed, you need to execute step 11.1 and then run the helm upgrade documentserver euro-office/docs --set extraThemes.configMap=custom-themes --set extraThemes.filename=custom-themes.json --no-hooks command or helm upgrade documentserver -f ./values.yaml euro-office/docs --no-hooks if the parameters are specified in the values.yaml file.

12. Connecting Amazon S3 bucket as a cache to Euro-Office Helm Docs

In order to connect Amazon S3 bucket as a cache, you need to create a configuration file or edit the existing one in accordance with this guide and change the value of the parameter persistence.storageS3 to true.

Deploy Euro-Office Docs

1. Deploy the Euro-Office Docs license

1.1. Create secret

If you have a valid Euro-Office Docs license, create a secret license from the file:

• Where SECRET_LICENSE_NAME is the name of a future secret with a license

Note: The source license file name should be ’license.lic’ because this name would be used as a field in the created secret.

Note: If the installation is performed without creating a secret with the existing license file, an empty secret license will be automatically created. For information on how to update an existing secret with a license, see here.

1.2. Specify parameters when installing Euro-Office Docs

When installing Euro-Office Docs, specify the license.existingSecret=[SECRET_LICENSE_NAME] parameter.

Note: If you need to add license after the Euro-Office Docs is already installed, you need to execute step 1.1 and then run the helm upgrade documentserver euro-office/docs --set license.existingSecret=[SECRET_LICENSE_NAME] --no-hooks command or helm upgrade documentserver -f ./values.yaml euro-office/docs --no-hooks if the parameters are specified in the values.yaml file.

2. Deploy Euro-Office Docs

To deploy Euro-Office Docs with the release name documentserver:

$ helm install documentserver euro-office/docs

The command deploys Euro-Office Docs on the Kubernetes cluster in the default configuration. The Parameters section lists the parameters that can be configured during installation.

Note: When installing Euro-Office Docs in a private k8s cluster behind a Web proxy or with no internet access, see the notes below.

3. Uninstall Euro-Office Docs

To uninstall/delete the documentserver deployment:

$ helm delete documentserver

Executing the helm delete command launches hooks, which perform some preparatory actions before completely deleting the Euro-Office Docs, which include stopping the server, cleaning up the used PVC and database tables. The default hook execution time is 300s. The execution time can be changed using --timeout [time], for example:

$ helm delete documentserver --timeout 25m

Note: When deleting Euro-Office Docs in a private k8s cluster behind a Web proxy or with no internet access, see the notes below.

If you want to delete the Euro-Office Docs without any preparatory actions, run the following command:

$ helm delete documentserver --no-hooks

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

4. Parameters

• *Note: The prefix -de is specified in the value of the image repository, which means solution type. Possible options:

  • -de. For commercial Developer Edition
  • -ee. For commercial Enterprise Edition

  The default value of this parameter refers to the Euro-Office Document Server Developer Edition. To learn more about this edition and compare it with other editions, please see the comparison table on this page.

Specify each parameter using the --set key=value[,key=value] argument to helm install. For example,

$ helm install documentserver euro-office/docs --set ingress.enabled=true,ingress.ssl.enabled=true,ingress.host=example.com

This command gives expose Euro-Office Docs via HTTPS.

Alternatively, a YAML file that specifies the values for the parameters can be provided while installing the chart. For example,

$ helm install documentserver -f values.yaml euro-office/docs

Tip: You can use the default values.yaml

5. Configuration and installation details

5.1 Example deployment (optional)

To deploy the example, set the example.enabled parameter to true:

$ helm install documentserver euro-office/docs --set example.enabled=true

5.2 Metrics deployment (optional)

To deploy metrics, set metrics.enabled to true:

$ helm install documentserver euro-office/docs --set metrics.enabled=true

If you want to use Grafana to visualize metrics, set grafana.enabled to true. If you want to use Nginx Ingress to access Grafana, set grafana.ingress.enabled to true:

$ helm install documentserver euro-office/docs --set grafana.enabled=true --set grafana.ingress.enabled=true

5.3 Expose Euro-Office Docs

5.3.1 Expose Euro-Office Docs via Service (HTTP Only)

You should skip step#5.3.1 if you are going to expose Euro-Office Docs via HTTPS

This type of exposure has the least overheads of performance, it creates a loadbalancer to get access to Euro-Office Docs. Use this type of exposure if you use external TLS termination, and don’t have another WEB application in the k8s cluster.

To expose Euro-Office Docs via service, set the service.type parameter to LoadBalancer:

$ helm install documentserver euro-office/docs --set service.type=LoadBalancer,service.port=80

Run the following command to get the documentserver service IP:

$ kubectl get service documentserver -o jsonpath="{.status.loadBalancer.ingress[*].ip}"

After that, Euro-Office Docs will be available at http://DOCUMENTSERVER-SERVICE-IP/.

If the service IP is empty, try getting the documentserver service hostname:

$ kubectl get service documentserver -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"

In this case, Euro-Office Docs will be available at http://DOCUMENTSERVER-SERVICE-HOSTNAME/.

5.3.2 Expose Euro-Office Docs via Ingress

5.3.2.1 Installing the Kubernetes Nginx Ingress Controller

To install the Nginx Ingress Controller to your cluster, run the following command:

$ helm install nginx-ingress ingress-nginx/ingress-nginx --set controller.publishService.enabled=true,controller.replicaCount=2

Note: To install Nginx Ingress with the same parameters and to enable exposing ingress-nginx metrics to be gathered by Prometheus, run the following command:

$ helm install nginx-ingress -f https://raw.githubusercontent.com/Euro-Office/Kubernetes-Docs/master/sources/ingress_values.yaml ingress-nginx/ingress-nginx

See more detail about installing Nginx Ingress via Helm here.

5.3.2.2 Expose Euro-Office Docs via HTTP

You should skip step5.3.2.2 if you are going to expose Euro-Office Docs via HTTPS

This type of exposure has more overheads of performance compared with exposure via service, it also creates a loadbalancer to get access to Euro-Office Docs. Use this type if you use external TLS termination and when you have several WEB applications in the k8s cluster. You can use the one set of ingress instances and the one loadbalancer for those. It can optimize the entry point performance and reduce your cluster payments, cause providers can charge a fee for each loadbalancer.

To expose Euro-Office Docs via ingress HTTP, set the ingress.enabled parameter to true:

$ helm install documentserver euro-office/docs --set ingress.enabled=true

Run the following command to get the documentserver ingress IP:

$ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].ip}"

After that, Euro-Office Docs will be available at http://DOCUMENTSERVER-INGRESS-IP/.

If the ingress IP is empty, try getting the documentserver ingress hostname:

$ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"

In this case, Euro-Office Docs will be available at http://DOCUMENTSERVER-INGRESS-HOSTNAME/.

5.3.2.3 Expose Euro-Office Docs via HTTPS

This type of exposure allows you to enable internal TLS termination for Euro-Office Docs.

Create the tls secret with an ssl certificate inside.

Put the ssl certificate and the private key into the tls.crt and tls.key files and then run:

$ kubectl create secret generic tls \
  --from-file=./tls.crt \
  --from-file=./tls.key

$ helm install documentserver euro-office/docs --set ingress.enabled=true,ingress.ssl.enabled=true,ingress.host=example.com

Run the following command to get the documentserver ingress IP:

$ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].ip}"

If the ingress IP is empty, try getting the documentserver ingress hostname:

$ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"

Associate the documentserver ingress IP or hostname with your domain name through your DNS provider.

After that, Euro-Office Docs will be available at https://your-domain-name/.

5.3.2.4 Expose Euro-Office Docs via HTTPS using the Let’s Encrypt certificate

• Add Helm repositories:

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

• Installing cert-manager

  $ helm install cert-manager --version v1.17.4 jetstack/cert-manager \
    --namespace cert-manager \
    --create-namespace \
    --set crds.enabled=true \
    --set crds.keep=false
  

Next, perform the installation or upgrade by setting the ingress.enabled, ingress.ssl.enabled and ingress.letsencrypt.enabled parameters to true. Also set your own values in the parameters ingress.letsencrypt.email, ingress.host or ingress.tenants(for example, --set "ingress.tenants={tenant1.example.com,tenant2.example.com}") if you want to use multiple domain names.

5.3.2.5 Expose Euro-Office Docs on a virtual path

This type of exposure allows you to expose Euro-Office Docs on a virtual path, for example, http://your-domain-name/docs. To expose Euro-Office Docs via ingress on a virtual path, set the ingress.enabled, ingress.host and ingress.path parameters.

$ helm install documentserver euro-office/docs --set ingress.enabled=true,ingress.host=your-domain-name,ingress.path=/docs

The list of supported ingress controllers for virtual path configuration:

• Ingress NGINX by Kubernetes
• NGINX Ingress by NGINX
• HAProxy Ingress by HAProxy

For virtual path configuration with Ingress NGINX by Kubernetes, append the pattern (/|$)(.*) to the ingress.path, for example, /docs becomes /docs(/|$)(.*).

5.3.3 Expose Euro-Office Docs via route in OpenShift

This type of exposure allows you to expose Euro-Office Docs via route in OpenShift. Route configuration can be found here.

5.4 Admin Panel deployment (optional)

To deploy the Admin Panel, set the adminpanel.enabled parameter to true:

$ helm install documentserver euro-office/docs --set adminpanel.enabled=true

For first authorization, use the secret value Bootstrap code. You can find it by opening the adminpanel Pod log. The Bootstrap code is valid for 1 hour.

6. Scale Euro-Office Docs (optional)

This step is optional. You can skip step 6 entirely if you want to use default deployment settings.

6.1 Horizontal Pod Autoscaling

You can enable Autoscaling so that the number of replicas of docservice and converter deployments is calculated automatically based on the values and type of metrics.

For resource metrics, API metrics.k8s.io must be registered, which is generally provided by metrics-server. It can be launched as a cluster add-on.

To use the target utilization value (target.type==Utilization), it is necessary that the values for resources.requests are specified in the deployment.

For more information about Horizontal Pod Autoscaling, see here.

To enable HPA for the docservice deployment, specify the docservice.autoscaling.enabled=true parameter. In this case, the docservice.replicas parameter is ignored and the number of replicas is controlled by HPA.

Similarly, to enable HPA for the converter deployment, specify the converter.autoscaling.enabled=true parameter. In this case, the converter.replicas parameter is ignored and the number of replicas is controlled by HPA.

With the autoscaling.enabled parameter enabled, by default Autoscaling will adjust the number of replicas based on the average percentage of CPU Utilization. For other configurable Autoscaling parameters, see the Parameters table.

6.2 Manual scaling

The docservice and converter deployments consist of 2 pods each other by default.

To scale the docservice deployment, use the following command:

$ kubectl scale -n default deployment docservice --replicas=POD_COUNT

where POD_COUNT is a number of the docservice pods.

Do the same to scale the converter deployment:

$ kubectl scale -n default deployment converter --replicas=POD_COUNT

7. Update Euro-Office Docs

It’s necessary to set the parameters for updating. For example,

$ helm upgrade documentserver euro-office/docs \
  --set images.tag=[version]

Note: also need to specify the parameters that were specified during installation

Or modify the values.yaml file and run the command:

$ helm upgrade documentserver -f values.yaml euro-office/docs

Running the helm upgrade command runs a hook that shuts down the Euro-Office Docs and cleans up the database. This is needed when updating the version of Euro-Office Docs. The default hook execution time is 300s. The execution time can be changed using –timeout [time], for example

$ helm upgrade documentserver -f values.yaml euro-office/docs --timeout 15m

Note: When upgrading Euro-Office Docs in a private k8s cluster behind a Web proxy or with no internet access, see the notes below.

If you want to update any parameter other than the version of the Euro-Office Docs, then run the helm upgrade command without hooks, for example:

$ helm upgrade documentserver euro-office/docs --set jwt.enabled=false --no-hooks

To rollback updates, run the following command:

$ helm rollback documentserver

Note: When rolling back Euro-Office Docs in a private k8s cluster behind a Web proxy or with no internet access, see the notes below.

8. Shutdown Euro-Office Docs (optional)

To perform the shutdown, run the following command:

$ kubectl apply -f https://raw.githubusercontent.com/Euro-Office/Kubernetes-Docs/master/sources/shutdown-ds.yaml -n <NAMESPACE>

Where:

• <NAMESPACE> - Namespace where Euro-Office Docs is installed. If not specified, the default value will be used: default.

For example:

$ kubectl apply -f https://raw.githubusercontent.com/Euro-Office/Kubernetes-Docs/master/sources/shutdown-ds.yaml -n euro-office

After successfully executing the Pod shutdown-ds that created the Job, delete this Job with the following command:

$ kubectl delete job shutdown-ds -n <NAMESPACE>

If after stopping Euro-Office Docs you need to start it again then restart docservice and converter pods. For example, using the following command:

$ kubectl delete pod converter-*** docservice-*** -n <NAMESPACE>

9. Update Euro-Office Docs license (optional)

After the release v5.1.1, you can update the license by simply recreating the secret with the new license, without deleting or rebooting pods. The documentserver is now able to dynamically reread the license file after replacing it. For example:

In order to update the license, you need to perform the following steps:

• Place the license.lic file containing the new key in some directory
• Run the following commands:

$ kubectl delete secret [SECRET_LICENSE_NAME] -n <NAMESPACE>
$ kubectl create secret generic [SECRET_LICENSE_NAME] --from-file=path/to/license.lic -n <NAMESPACE>

• Where SECRET_LICENSE_NAME is the name of an existing secret with a license

Thats all, the documentserver will reread the new license itself.

[DEPRECATED METHOD]

• Restart docservice and converter pods. For example, using the following command:

$ kubectl delete pod converter-*** docservice-*** -n <NAMESPACE>

10. Euro-Office Docs installation test (optional)

You can test Euro-Office Docs availability and access to connected dependencies by running the following command:

$ helm test documentserver -n <NAMESPACE>

The output should have the following line:

Phase: Succeeded

To view the log of the Pod running as a result of the helm test command, run the following command:

$ kubectl logs -f test-ds -n <NAMESPACE>

The Euro-Office Docs availability check is considered a priority, so if it fails with an error, the test is considered to be failed.

After this, you can delete the test-ds Pod by running the following command:

$ kubectl delete pod test-ds -n <NAMESPACE>

Note: This testing is for informational purposes only and cannot guarantee 100% availability results. It may be that even though all checks are completed successfully, an error occurs in the application. In this case, more detailed information can be found in the application logs.

11. Run Jobs in a private k8s cluster (optional)

When running Job for installation, update, rollback and deletion, the container being launched needs Internet access to download the latest sql scripts. If the access of containers to the external network is prohibited in your k8s cluster, then you can perform these Jobs by setting the privateCluster=true parameter and manually create a ConfigMap with the necessary sql scripts.

To do this, run the following commands:

If your cluster already has remove-db-scripts and init-db-scripts configmaps, then delete them:

$ kubectl delete cm remove-db-scripts init-db-scripts

Download the Euro-Office Docs database scripts for database cleaning and database tables creating:

If PostgreSQL is selected as the database server:

$ wget -O removetbl.sql https://raw.githubusercontent.com/Euro-Office/server/master/schema/postgresql/removetbl.sql
$ wget -O createdb.sql https://raw.githubusercontent.com/Euro-Office/server/master/schema/postgresql/createdb.sql

If MySQL is selected as the database server:

$ wget -O removetbl.sql https://raw.githubusercontent.com/Euro-Office/server/master/schema/mysql/removetbl.sql
$ wget -O createdb.sql https://raw.githubusercontent.com/Euro-Office/server/master/schema/mysql/createdb.sql

Create a configmap from them:

$ kubectl create configmap remove-db-scripts --from-file=./removetbl.sql
$ kubectl create configmap init-db-scripts --from-file=./createdb.sql

Note: If you specified a different name for ConfigMap and for the file from which it is created, set the appropriate parameters for the corresponding Jobs:

• existingConfigmap.tblRemove.name and existingConfigmap.tblRemove.keyName for scripts for database cleaning
• existingConfigmap.tblCreate.name and existingConfigmap.tblCreate.keyName for scripts for database tables creating

Next, when executing the commands helm install|upgrade|rollback|delete, set the parameter privateCluster=true

Note: If it is possible to use a Web Proxy in your network to ensure the Pods containers have access to the Internet, then you can leave the parameter privateCluster=false, not manually create a configmaps with sql scripts and set the parameter webProxy.enabled=true, also setting the appropriate parameters for the Web Proxy.

12. Access to the info page (optional)

The access to /info page is limited by default. In order to allow the access to it, you need to specify the IP addresses or subnets (that will be Proxy container clients in this case) using proxy.infoAllowedIP parameter. Taking into consideration the specifics of Kubernetes net interaction it is possible to get the original IP of the user (being Proxy client) though it’s not a standard scenario. Generally the Pods / Nodes / Load Balancer addresses will actually be the clients, so these addresses are to be used. In this case the access to the info page will be available to everyone. You can further limit the access to the info page using Nginx Basic Authentication which you can turn on by setting proxy.infoAllowedUser parameter value and by setting the password using proxy.infoAllowedPassword parameter, alternatively you can use the existing secret with password by setting its name with proxy.infoAllowedExistingSecret parameter.

Using Grafana to visualize metrics (optional)

This step is optional. You can skip this section if you don’t want to install Grafana

1. Deploy Grafana

Note: It is assumed that step #6.2 has already been completed.

1.1 Deploy Grafana without installing ready-made dashboards

You should skip step #1.1 if you want to Deploy Grafana with the installation of ready-made dashboards

To install Grafana to your cluster, run the following command:

$ helm install grafana --version 12.1.8 bitnami/grafana \
  --set service.ports.grafana=80 \
  --set config.useGrafanaIniFile=true \
  --set config.grafanaIniConfigMap=grafana-ini \
  --set datasources.secretName=grafana-datasource \
  --set resourcesPreset=none \
  --set image.repository=bitnamilegacy/grafana \
  --set image.tag=12.1.1-debian-12-r1 \
  --set global.security.allowInsecureImages=true

1.2 Deploy Grafana with the installation of ready-made dashboards

1.2.1 Installing ready-made Grafana dashboards

To install ready-made Grafana dashboards, set the grafana.enabled and grafana.dashboard.enabled parameters to true. If Euro-Office Docs is already installed you need to run the helm upgrade documentserver euro-office/docs --set grafana.enabled=true --set grafana.dashboard.enabled=true command or helm upgrade documentserver -f ./values.yaml euro-office/docs if the parameters are specified in the values.yaml file. As a result, ready-made dashboards in the JSON format will be downloaded from the Grafana website, the necessary edits will be made to them and configmap will be created from them. A dashboard will also be added to visualize metrics coming from the Euro-Office Docs (it is assumed that step #6 has already been completed).

1.2.2 Installing Grafana

To install Grafana to your cluster, run the following command:

$ helm install grafana --version 12.1.8 bitnami/grafana \
  --set service.ports.grafana=80 \
  --set config.useGrafanaIniFile=true \
  --set config.grafanaIniConfigMap=grafana-ini \
  --set datasources.secretName=grafana-datasource \
  --set resourcesPreset=none \
  --set image.repository=bitnamilegacy/grafana \
  --set image.tag=12.1.1-debian-12-r1 \
  --set global.security.allowInsecureImages=true \
  --set dashboardsProvider.enabled=true \
  --set dashboardsConfigMaps[0].configMapName=dashboard-node-exporter \
  --set dashboardsConfigMaps[0].fileName=dashboard-node-exporter.json \
  --set dashboardsConfigMaps[1].configMapName=dashboard-deployment \
  --set dashboardsConfigMaps[1].fileName=dashboard-deployment.json \
  --set dashboardsConfigMaps[2].configMapName=dashboard-redis \
  --set dashboardsConfigMaps[2].fileName=dashboard-redis.json \
  --set dashboardsConfigMaps[3].configMapName=dashboard-rabbitmq \
  --set dashboardsConfigMaps[3].fileName=dashboard-rabbitmq.json \
  --set dashboardsConfigMaps[4].configMapName=dashboard-postgresql \
  --set dashboardsConfigMaps[4].fileName=dashboard-postgresql.json \
  --set dashboardsConfigMaps[5].configMapName=dashboard-nginx-ingress \
  --set dashboardsConfigMaps[5].fileName=dashboard-nginx-ingress.json \
  --set dashboardsConfigMaps[6].configMapName=dashboard-documentserver \
  --set dashboardsConfigMaps[6].fileName=dashboard-documentserver.json \
  --set dashboardsConfigMaps[7].configMapName=dashboard-cluster-resourses \
  --set dashboardsConfigMaps[7].fileName=dashboard-cluster-resourses.json

After executing this command, the following dashboards will be imported into Grafana:

• Node Exporter
• Deployment Statefulset Daemonset
• Redis Dashboard for Prometheus Redis Exporter
• RabbitMQ-Overview
• PostgreSQL Database
• NGINX Ingress controller
• Euro-Office Docs
• Resource usage by Pods and Containers

Note: You can see the description of the Euro-Office Docs metrics that are visualized in Grafana here.

See more details about installing Grafana via Helm here.

2 Access to Grafana via Ingress

Note: It is assumed that step #5.3.2.1 has already been completed.

If Euro-Office Docs was installed with the parameter grafana.ingress.enabled (step #5.2) then access to Grafana will be at: http://INGRESS-ADDRESS/grafana/

If Ingres was installed using a secure connection (step #5.3.2.3), then access to Grafana will be at: https://your-domain-name/grafana/

3. View gathered metrics in Grafana

Go to the address http(s)://your-domain-name/grafana/

Login - admin

To get the password, run the following command:

In the dashboard section, you will see the added dashboards that will display the metrics received from Prometheus.