The following guide covers the installation process of the ‘DocSpace’ into a Kubernetes cluster or OpenShift cluster.
- Kubernetes version no lower than 1.19+ or OpenShift version no lower than 3.11+
- A minimum of three hosts 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. Read more on the installation of kubectl here
- Helm is installed on the cluster management host. Read more on the installation of Helm here
- If you use OpenShift, you can use both
oc
andkubectl
to manage deploy. - If the installation of components external to ‘DocSpace’ 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.
Note: When installing to an OpenShift cluster, you must apply the SecurityContextConstraints
policy, which adds permission to run containers from a user whose ID = 1000
and ID = 1001
.
To do this, run the following commands:
$ oc apply -f https://raw.githubusercontent.com/ONLYOFFICE/Kubernetes-AppServer/docspace/sources/scc/helm-components.yaml
$ oc adm policy add-scc-to-group scc-helm-components system:authenticated
$ helm repo add bitnami https://charts.bitnami.com/bitnami
$ helm repo add stable https://charts.helm.sh/stable
$ helm repo add elastic https://helm.elastic.co
$ helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
$ helm repo update
Note: When installing NFS Server Provisioner, Storage Classes - NFS
is created. When installing to 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 stable/nfs-server-provisioner --set persistence.enabled=true,persistence.storageClass=do-block-storage,persistence.size=50Gi
See more details about installing NFS Server Provisioner via Helm here.
Create a secret containing the root
user password and the user password to be used by the DocSpace.
To do this, in the ./sources/secrets/mysql-password.yaml
file, change the values for the mysql-root-password
and mysql-password
keys.
Next, create a secret by running the following command:
$ kubectl apply -f ./sources/secrets/mysql-password.yaml
$ helm install mysql -f ./sources/mysql_values.yaml bitnami/mysql
See more details about installing MySQL via Helm here.
$ helm install elasticsearch --version 7.13.1 -f ./sources/elasticsearch_values.yaml elastic/elasticsearch
Test the Elasticsearch cluster by running helm test elasticsearch
, the output should have the following line:
Phase: Succeeded
See more details about installing Elasticsearch via Helm here.
To install RabbitMQ to your cluster, run the following command:
$ helm install rabbitmq bitnami/rabbitmq \
--set persistence.size=9Gi \
--set auth.username=guest \
--set auth.password=guest \
--set metrics.enabled=false
See more details about installing RabbitMQ via Helm here.
To install Redis to your cluster, run the following command:
$ helm install redis bitnami/redis \
--set architecture=standalone \
--set auth.enabled=false \
--set master.persistence.size=9Gi \
--set metrics.enabled=false
See more details about installing Redis via Helm here.
Note: When installing to an OpenShift cluster, you must apply the SecurityContextConstraints
policy, which adds permission to run containers from a user whose ID = 104
.
To do this, run the following commands:
$ oc apply -f https://raw.githubusercontent.com/ONLYOFFICE/Kubernetes-AppServer/docspace/sources/scc/app-components.yaml
$ oc adm policy add-scc-to-group scc-app-components system:authenticated
Also, you must set the podSecurityContext.enabled
parameter to true
:
$ helm install [RELEASE_NAME] ./ --set podSecurityContext=true
To install DocSpace to your cluster, run the following command:
$ helm install [RELEASE_NAME] -f values.yaml ./
The command deploys DocSpace on the Kubernetes cluster in the default configuration. The [Parameters] section lists the parameters that can be configured during installation.
See helm install for command documentation.
To uninstall/delete the docspace
deployment:
$ helm uninstall [RELEASE_NAME]
The helm uninstall
command removes all the Kubernetes components associated with the chart and deletes the release.
See helm uninstall for command documentation.
It's necessary to set the parameters for updating. For example,
$ helm upgrade [RELEASE_NAME] ./ \
--set images.tag=[tag]
Note: also need to specify the parameters that were specified during installation
Or modify the values.yaml
file and run the command:
$ helm upgrade [RELEASE_NAME] -f values.yaml ./
Running the helm upgrade
command runs a hook that cleans up the directory with libraries and then fills with new ones. This is needed when updating the version of DocSpace. The default hook execution time is 300s.
The execution time can be changed using --timeout [time]
, for example:
$ helm upgrade [RELEASE_NAME] -f values.yaml ./ --timeout 15m
If you want to update any parameter other than the version of the DocSpace, then run the helm upgrade
command without hooks
, for example:
$ helm upgrade [RELEASE_NAME] ./ --set jwt.enabled=false --no-hooks
See helm upgrade for command documentation.
To rollback updates, run the following command:
$ helm rollback [RELEASE_NAME]
See helm rollback for command documentation.
Parameter | Description | Default |
---|
You should skip step[#1.1] if you are going to expose DocSpace via HTTPS
This type of exposure has the least overheads of performance, it creates a loadbalancer to get access to DocSpace. Use this type of exposure if you use external TLS termination, and don't have another WEB application in the k8s cluster.
To expose DocSpace via service, set the service.proxy.type
parameter to LoadBalancer
:
$ helm install [RELEASE_NAME] ./ --set service.proxy.type=LoadBalancer,service.proxy.port.external=8092
Run the following command to get the DocSpace
service IP:
$ kubectl get service onlyoffice-proxy -o jsonpath="{.status.loadBalancer.ingress[*].ip}"
After that, DocSpace will be available at http://DOCSPACE-SERVICE-IP/
.
If the service IP is empty, try getting the DocSpace
service hostname:
$ kubectl get service onlyoffice-proxy -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"
In this case, DocSpace will be available at http://DOCSPACE-SERVICE-HOSTNAME/
.
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
See more detail about installing Nginx Ingress Controller via Helm here.
You should skip step[2.1.2] if you are going to expose DocSpace 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 DocSpace. 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 DocSpace via ingress HTTP, set the ingress.enabled
parameter to true:
$ helm install [RELEASE_NAME] ./ --set ingress.enabled=true
Run the following command to get the docspace
ingress IP:
$ kubectl get ingress ingress-app -o jsonpath="{.status.loadBalancer.ingress[*].ip}"
After that, DocSpace will be available at http://DOCSPACE-INGRESS-IP/
.
If the ingress IP is empty, try getting the docspace
ingress hostname:
$ kubectl get ingress ingress-app -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"
In this case, DocSpace will be available at http://DOCSPACE-INGRESS-HOSTNAME/
.
This type of exposure allows you to enable internal TLS termination for DocSpace.
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 [RELEASE_NAME] ./ --set ingress.enabled=true,ingress.tls.enabled=true,ingress.tls.secretName=tls,ingress.host=example.com
Run the following command to get the docspace
ingress IP:
$ kubectl get ingress ingress-app -o jsonpath="{.status.loadBalancer.ingress[*].ip}"
If the ingress IP is empty, try getting the docspace
ingress hostname:
$ kubectl get ingress ingress-app -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"
Associate the docspace
ingress IP or hostname with your domain name through your DNS provider.
After that, DocSpace will be available at https://your-domain-name/
.