deployment: corrections from review

Co-authored-by: Guillaume Viger <[email protected]>

Author: ppanero

docs/deployment/configuration.md

@@ -1,16 +1,16 @@
 # Configuration
 
-This section explain the current configuration options that are available for the different components that are deployed but the Helm charts.
+This section explains the current configuration options that are available for the different components deployed by these Helm charts.
 
 ## Global
 
-The is only one mandatory configuration, which is the host name, for example:
+There is only one mandatory configuration: the host name.
 
 ```yaml
 host: your-rdm-instance.com
 ```
 
-Moreover, the services can be deployed along, note that it is recommended to deploy separatelly Elasticsearch and PostgreSQL for a production deployment.
+Moreover, the services can be deployed along. Note that it is recommended to deploy Elasticsearch and PostgreSQL separately for a production deployment.
 Therefore, by default only `redis` and `rabbitmq` are enabled. Example configuration:
 
 ``` yaml
@@ -27,24 +27,16 @@ elasticsearch:
 
 ## HAProxy
 
-You can change the number of connections allowed by the haproxy with the `maxconn` variable:
+You can change the number of connections allowed by haproxy with the `maxconn` variable:
 
 ```
 haproxy:
   maxconn: 100
 ```
 
-!!! warning "Only one parent element"
-    By default the HAProxy is enabled, `inside_cluster` has the value `true`, nonetheless if you decide to set it, you only need
-    to specify once the `haproxy` parent in the yaml file. Otherwise the last one will override the previous. It should be something like:
-    ``` yaml
-    haproxy:
-        inside_cluster: true
-        maxconn: 100
-    ```
 ## Nginx
 
-The charts allow you to configure the amount of connections per nginx node (replica) and the amount of nodes:
+These charts allow you to configure the amount of connections per nginx node (replica) and the amount of nodes:
 
 ```
 nginx:
@@ -54,9 +46,9 @@ nginx:
 
 ## Web nodes
 
-The web nodes host the WSGI application, in order to be scalable you can configure the number of "nodes", called replicas, how many processes do each node run and with how many threads per process. The only mandatory parameter is the docker image (`image`) that should get as value the url where to pull the image from.
+The web nodes host the WSGI application. In order to be scalable you can configure the number of "nodes", called replicas, with how many processes each node runs and with how many threads per process. The only mandatory parameter is the docker image (`image`) that should get as value the url where to pull the image from.
 
-In addition, you can add automatic scaling, by setting minimum and maximum replicas and the threshold of cpu usage in which a new node should be spawned. For example, with a threshold of 65%, it meand that when the average CPU utilization of the nodes reaches 65% a new node will de spawned, till it reaches the setted maximum:
+In addition, you can add automatic scaling by setting minimum (`min_web_replicas`) and maximum (`max_web_replicas`) replicas, and the cpu usage threshold in percentage (`scaler_cpu_utilization`) that spawns a new node. For example, with a `scaler_cpu_utilization` value of 65, it means that when the average CPU utilization of the nodes reaches 65%, a new node will be spawned. This process will repeat itself until the maximum number of replicas has been reached:
 
 ``` yaml
 web:
@@ -75,10 +67,9 @@ web:
 
 ## Worker nodes
 
-Finally, the worker nodes. By default they are enabled, but you can cancel their deployment by setting `enabled` to `false`. If enabled, in the same fashion than the web nodes
-they require an `image`.
+Finally, the worker nodes. By default they are enabled, but you can cancel their deployment by setting `enabled` to `false`. If enabled, they require an `image` like the web nodes.
 
-In addition, you can configure how many worker nodes (replicas) will be deployed, which the application they will run, with which concurrency level and the logging level.
+In addition, you can configure the number of worker nodes (replicas) to be deployed, the application they will run, their concurrency level and their logging level.
 
 ``` yaml
 worker:

docs/deployment/index.md

@@ -1,29 +1,29 @@
 # How can I deploy InvenioRDM?
 
-You can deploy InvenioRDM in several ways. You can install it in your [local computer](../develop/index.md) to have more easily customizable environment, otherwise you can deploy a [containerized environment](../preview/index.md) that demonstrates the setup of all components runnning in docker containers. In this section it is explained how to deploy in a closer-to-production manner.
+In previous sections, you could see how to install InvenioRDM in your [local computer](../develop/index.md) for development, and how to run [containerized environment](../preview/index.md) that demonstrates the setup of all components running in docker containers. In this section we cover how to deploy InvenioRDM in a closer-to-production manner.
 
 !!! warning "Do not deploy as-is in production"
-    Please note that it is mentioned as "closer-to-production", this is because even if the designed architecture can scale and withstand the load of a production service (It has been tested to stand peaks of up to 180 requests/s), the security configurations might not be enough and you should review it. In addition, it can deploy the extra services (Elasticsearch and PostgreSQL) along with them, however this ones are not configured with redundancy and persistance.
+    Please note the "closer-to-production" statement, this is because even if the designed architecture can scale and withstand the load of a production service (It has been tested to stand peaks of up to 180 requests/s), you need to review the security configurations and customize resources to fit your use case. In addition, Elasticsearch and PostgreSQL can be deployed along with the application, however they are not configured with redundancy and persistance in mind.
 
 ## Helm Charts
 
-[Helm](https://helm.sh) is the package manager for [Kubernetes](https://kubernetes.io/). This means, that by using Helm charts you can deploy InvenioRDM in any cloud provider that supports Kubernetes (e.g. OpenShift clusters, Google Cloud, Amazon Web Services, IBM Cloud).
+[Helm](https://helm.sh) is the package manager for [Kubernetes](https://kubernetes.io/). This means, that by using Helm charts (packages in Helm lingo) you can deploy InvenioRDM in any cloud provider that supports Kubernetes (e.g. OpenShift clusters, Google Cloud, Amazon Web Services, IBM Cloud).
 
 **What is a Helm chart?**
 
-A Helm chart is a definition of the architecture of the system, meaning how all components interconnect with each other (In a similar fashion that a `docker-compose` file).
+A Helm chart is a definition of the architecture of the system, meaning how all components interconnect with each other (Similar to a `docker-compose` file).
 
-In addition, Helm allows you to **install, version and upgrade and rollback** your InvenioRDM installation in an easy way. You can find more information about Helm [here](https://helm.sh/docs/intro/quickstart/).
+In addition, Helm allows you to **install, version, upgrade and rollback** your InvenioRDM installation in an easy way. You can find more information about Helm [here](https://helm.sh/docs/intro/quickstart/).
 
 ### Charts description
 
-The currents charts propose the following architecture:
+The current charts propose the following architecture:
 
-- HAProxy as entry point. It provides load balancing and queuing of the requests.
+- HAProxy as entry point. It provides load balancing and queuing of requests.
 - Nginx as reverse proxy. It serves as reverse proxy, to help HAproxy and uWSGI "talk" the same language (protocol).
 - Web application nodes, running the uWSGI application.
 - Redis and RabbitMQ come along in containers.
-- Elasticsearch and PostgreSQL can be added to the deployment, however they are not configured in-depth and therefore not suited for more than demo purposes.
+- Elasticsearch and PostgreSQL can be added to the deployment. However they are not configured in-depth and therefore not suited for more than demo purposes.
 
 For more in-depth documentation see the [services description](services.md) and the configuration available [here](configuration.md).
 
@@ -42,19 +42,19 @@ helm-invenio/invenio	0.2.0        	1.16.0     	Open Source framework for large-s
 helm-invenio/invenio	0.1.0        	1.16.0     	Open Source framework for large-scale digital repositories
 ```
 
-You can also install by cloning from GitHub by cloning the repository:
+You can also install by cloning from GitHub:
 
 ```
 $ git clone https://github.com/inveniosoftware/helm-invenio.git
 $ cd helm-invenio/
 ```
 
-Then you will need, to reference the `./invenio` folder rather than the chart name (`helm-invenio/invenio`).
+In this case, you will need to reference the `./invenio` folder rather than the chart name (`helm-invenio/invenio`).
 
 ## Supported Platforms
 
 !!! warning "Only compatible with OpenShift"
-    Pleas note that currently these Helm charts are only compatible with OpenShift.
+    Please note that currently these Helm charts are only compatible with OpenShift.
 
 - [OpenShift](openshift.md)
 - [Kubernetes](kubernetes.md)

docs/deployment/openshift.md

@@ -8,7 +8,7 @@
 
 ## Deploying InvenioRDM
 
-First of all login and select the right project in your OpenShift cluster:
+First of all, log in and select the right project in your OpenShift cluster:
 
 ```console
 $ oc login <your.openshift.cluster>
@@ -17,7 +17,7 @@ $ oc project invenio
 
 ### Secrets
 
-Before deploying in need to provide the credentials so the application can access the different services:
+Before deploying, you need to provide the credentials so the application can access the different services. Replace the credentials and configuration below with your own:
 
 **Database secrets:**
 
@@ -47,7 +47,7 @@ secret "mq-secrets" created
 
 **Elasticsearch secrets:**
 
-!!! info "Elasticaserch variables"
+!!! info "Elasticsearch variables"
     Currently, and until [invenio-search#198](https://github.com/inveniosoftware/invenio-search/issues/198) has been addressed, the Elasticsearch configuration
     has to be loaded in a single environment variable.
 
@@ -59,13 +59,13 @@ $ oc create secret generic \
 ```
 
 !!! info "Extra configuration is possible"
-    Note that you might need to add extra configuration to the elasticsearch hosts, sucha as vertificate verification (`verify_certs`), prefixing (`url_prefix`) and more.
+    Note that you might need to add extra configuration to the Elasticsearch hosts, such as certificate verification (`verify_certs`), prefixing (`url_prefix`) and more.
 
 ### Install InvenioRDM
 
-Before installing you need to configure two things, the rest are optional and you can read more about it [here](configuration.md):
+Before installing you need to configure two things in your `values.yml` file. The rest are optional and you can read more about them [here](configuration.md):
 
-- Your host in a `values.yaml` file.
+- The host.
 - The web/worker docker images.
 
 ``` yaml
@@ -78,7 +78,7 @@ worker:
   image: your/invenio-image
 ```
 
-The next step is the installation itself, with your own configuration in the `values.yaml`. If you added the repository you can install it by using the chart name and the desired version:
+The next step is the installation itself, with your own configuration in the `values.yaml`. If you added the repository, you can install it by using the chart name and the desired version:
 
 ``` console
 $ helm install -f values.yaml invenio helm-invenio/invenio --version 0.2.0
@@ -144,8 +144,9 @@ $ oc process -f job.yml --param JOB_NAME='demo-data-1' \
 
 **Cron job**
 
-Now imagine you might have some bulk record creation that needs to be indexed, or any other task that you have to do every certain period of time.
-For that you can define cronjobs:
+Now, imagine you have some bulk record indexing, or any other task that you have to do periodically.
+
+For that, you can define cronjobs:
 
 ``` console
 $ oc process -f cronjob.yml --param JOB_NAME=index-run \
@@ -155,7 +156,7 @@ $ oc process -f cronjob.yml --param JOB_NAME=index-run \
 ### Upgrade your instance
 
 If you have performed some changes to your instance (e.g. configuration) or you want to upgrade the version of the charts, you can do so with
-the `upgrade` command of `helm`, note that you still need to disable the openapi validation which is only supoprted after version 3.1.2:
+the `upgrade` command of `helm`. Note that you still need to disable the openapi validation which is yet not supported in version 3.1.2 (However, it is merged into the master branch and should come out soon):
 
 ``` console
 $ helm upgrade -f values.yaml --disable-openapi-validation

mkdocs.yml

@@ -44,10 +44,10 @@ nav:
     - S3 Storage: 'extensions/s3.md'
   - Deploy:
     - How can I deploy it?: 'deployment/index.md'
+    - OpenShift: 'deployment/openshift.md'
+    - Kubernetes: 'deployment/kubernetes.md'
     - System components: 'deployment/services.md'
     - Configuration:  'deployment/configuration.md'
-    - Kubernetes: 'deployment/kubernetes.md'
-    - OpenShift: 'deployment/openshift.md'
 
 
 # Customization