ONLYOFFICE Docs for Kubernetes

1. Deploy the ONLYOFFICE Docs license

1. Create secret

   If you have a valid ONLYOFFICE Docs license, create a secret license from the file:

   $ kubectl create secret generic [SECRET_LICENSE_NAME] --from-file=path/to/license.lic

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

   The source license file name should be 'license.lic' because this name would be used as a field in the created secret.
   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.
2. Specify parameters when installing ONLYOFFICE Docs

   When installing ONLYOFFICE Docs, specify the license.existingSecret=[SECRET_LICENSE_NAME] parameter.

   $ helm install documentserver onlyoffice/docs --set license.existingSecret=[SECRET_LICENSE_NAME]

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

2. Deploy ONLYOFFICE Docs

To deploy ONLYOFFICE Docs with the release name documentserver:

$ helm install documentserver onlyoffice/docs

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

3. Uninstall ONLYOFFICE 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 ONLYOFFICE 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

If you want to delete the ONLYOFFICE 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 ONLYOFFICE 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 onlyoffice/docs --set ingress.enabled=true,ingress.ssl.enabled=true,ingress.host=example.com

This command gives expose ONLYOFFICE 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 onlyoffice/docs

5. Configuration and installation details

1. Example deployment (optional)

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

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

2. Metrics deployment (optional)

   To deploy metrics, set metrics.enabled to true:

   $ helm install documentserver onlyoffice/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 onlyoffice/docs --set grafana.enabled=true --set grafana.ingress.enabled=true

3. Expose ONLYOFFICE Docs
   1. Expose ONLYOFFICE Docs via Service (HTTP Only)
      You should skip this step if you are going to expose ONLYOFFICE Docs via HTTPS.

      This type of exposure has the least overheads of performance, it creates a loadbalancer to get access to ONLYOFFICE 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 ONLYOFFICE Docs via service, set the service.type parameter to LoadBalancer:

      $ helm install documentserver onlyoffice/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, ONLYOFFICE 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, ONLYOFFICE Docs will be available at http://DOCUMENTSERVER-SERVICE-HOSTNAME/.

   2. Expose ONLYOFFICE Docs via Ingress
      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

         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/ONLYOFFICE/Kubernetes-Docs/master/sources/ingress_values.yaml ingress-nginx/ingress-nginx

         See more detail about installing Nginx Ingress via Helm here.

      2. Expose ONLYOFFICE Docs via HTTP
         You should skip this step if you are going to expose ONLYOFFICE 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 ONLYOFFICE 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 ONLYOFFICE Docs via ingress HTTP, set the ingress.enabled parameter to true:

         $ helm install documentserver onlyoffice/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, ONLYOFFICE 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, ONLYOFFICE Docs will be available at http://DOCUMENTSERVER-INGRESS-HOSTNAME/.

      3. Expose ONLYOFFICE Docs via HTTPS

         This type of exposure allows you to enable internal TLS termination for ONLYOFFICE 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 onlyoffice/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, ONLYOFFICE Docs will be available at https://your-domain-name/.

      4. Expose ONLYOFFICE 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.

   3. Expose ONLYOFFICE Docs on a virtual path

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

      $ helm install documentserver onlyoffice/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(/|$)(.*).

4. Expose ONLYOFFICE Docs via route in OpenShift

   This type of exposure allows you to expose ONLYOFFICE Docs via route in OpenShift. To expose ONLYOFFICE Docs via route, use these parameters: openshift.route.enabled, openshift.route.host, openshift.route.path.

   $ helm install documentserver onlyoffice/docs --set openshift.route.enabled=true,openshift.route.host=your-domain-name,openshift.route.path=/docs

   For tls termination, manually add certificates to the route via OpenShift web console.

6. Scale ONLYOFFICE Docs (optional)

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.

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 ONLYOFFICE Docs

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

$ helm upgrade documentserver onlyoffice/docs \
  --set docservice.image.tag=[version]

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

$ helm upgrade documentserver -f values.yaml onlyoffice/docs

Running the helm upgrade command runs a hook that shuts down the ONLYOFFICE Docs and cleans up the database. This is needed when updating the version of ONLYOFFICE 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 onlyoffice/docs --timeout 15m

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

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

To rollback updates, run the following command:

$ helm rollback documentserver

8. Shutdown ONLYOFFICE Docs (optional)

To perform the shutdown, run the following command:

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

Where <NAMESPACE> is the namespace where ONLYOFFICE Docs is installed. If not specified, the default value will be used: default.

For example:

$ kubectl apply -f https://raw.githubusercontent.com/ONLYOFFICE/Kubernetes-Docs/master/sources/shutdown-ds.yaml -n onlyoffice

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 ONLYOFFICE 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 ONLYOFFICE 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.

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

10. ONLYOFFICE Docs installation test (optional)

You can test ONLYOFFICE 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 ONLYOFFICE 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>

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 ONLYOFFICE 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/ONLYOFFICE/server/master/schema/postgresql/removetbl.sql
$ wget -O createdb.sql https://raw.githubusercontent.com/ONLYOFFICE/server/master/schema/postgresql/createdb.sql

If MySQL is selected as the database server:

$ wget -O removetbl.sql https://raw.githubusercontent.com/ONLYOFFICE/server/master/schema/mysql/removetbl.sql
$ wget -O createdb.sql https://raw.githubusercontent.com/ONLYOFFICE/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

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

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.