OPSEXP-2608 Migrate diagrams to mermaid

docs/SECURITY.md

@@ -67,7 +67,7 @@ mentioned in this variable will be automatically to the list of relaxed origins
 for CORS queries. By default they will be allowed tu use any following methods:
 DELETE, GET, HEAD, OPTIONS, POST, PUT. If you want to restrict methods or
 further tweak the CORS configuration, you can do so by overriding the whole
-`cors` variable as shown bellow:
+`cors` variable as shown below:
 
 ```yaml
 cors:
@@ -123,7 +123,7 @@ Renditions using the LibreOffice transformer to render HTML are subject to the
 BSSRF attacks. In order to mitigate this risk, you may decide to disable the
 optimal renditions and instead generate lower quality renditions (where
 basically images would not be rendered as part of the HTML).
-That is achieved by the variable bellow:
+That is achieved by the variable below:
 
 ```yaml
 bssrf_protection_enabled: true

docs/_config.yml

@@ -31,3 +31,6 @@ defaults:
 
 plugins:
   - jekyll-relative-links
+
+mermaid:
+  version: "10.9.0"

docs/components-upgrade.md

@@ -41,9 +41,9 @@ Alfresco also releases some hotfixes and an hotfix upgrade would be moving from
 
 In order to apply a later hotfix, you need to first match the pre-requisites, then change the ACS version to point to the hotfix version in the appropriate file, and finally run the playbook again.
 
-In the example bellow we want to upgrade from the initial 7.0.1 installation to 7.0.1.4 hotfix:
+In the example below we want to upgrade from the initial 7.0.1 installation to 7.0.1.4 hotfix:
 
-Edit `7.0.N-extra-vars.yml` and changes the the bellow snippet:
+Edit `7.0.N-extra-vars.yml` and changes the the below snippet:
 
 ```yaml
 acs:
@@ -64,7 +64,7 @@ acs:
 > IMPORTANT: make sure you do not set the version to a version number that's not a hotfix (version number needs to be 4 digits and the 3 first ones needs to match the ones of the initially deployed version)
 > This is because, as explained earlier, "in-place" upgrades are only supported for hotfixes
 
-Once these changes are saved run the command bellow:
+Once these changes are saved run the command below:
 
 ```bash
 ansible-playbook playbooks/acs.yml -i inventory_ssh.yml -e "@7.0.N-extra-vars.yml"
@@ -77,7 +77,7 @@ After the playbook ran successfully your environment delivers the upgraded versi
 
 #### Rolling back a hotfix "in-place" upgrade
 
-If something goes wrong with the upgrade, or if tests are not successful after upgrade completed, rolling back the environment can be done by following the steps bellow:
+If something goes wrong with the upgrade, or if tests are not successful after upgrade completed, rolling back the environment can be done by following the steps below:
 
 - restoring Database and contentstore backup
 - reverting the version changes to previous state in the config file (either `group_vars/all` or version specific config files)

docs/deployment-guide.md

@@ -20,7 +20,7 @@ for a brief introduction.
     * [Setup runtime environment](#setup-runtime-environment)
   * [Minimal configuration](#minimal-configuration)
   * [Understanding the playbook](#understanding-the-playbook)
-    * [The control node](#the-control-node)
+    * [The Control Node](#the-control-node)
     * [Understanding the inventory file](#understanding-the-inventory-file)
     * [Folder Structure](#folder-structure)
     * [Service Configuration](#service-configuration)
@@ -228,9 +228,9 @@ known_urls:
 Let's take a step back to learn more about Ansible and the playbook before
 moving to more advanced topics.
 
-### The control node
+### The Control Node
 
-The machine the playbook is run from is known as the control node. Ansible has
+The machine the playbook is run from is known as the Control Node. Ansible has
 some prerequisites for this control node. The main one is that it needs to run
 on a POSIX compliant system, meaning Linux or others Unix (including MacOSX)
 but not Windows.
@@ -329,15 +329,43 @@ In this project you'll find 3 example inventory files:
 The `inventory_local.yml` which is ready to use in order to deploy all
 components on the local machine.
 
-![Local Deployment Type](./resources/deployment-type-local.png)
+```mermaid
+flowchart LR
+user[👤] --> Playbooks
+subgraph Control Node
+  Playbooks
+  Inventory
+  role1[[role1]]
+  roleN[[roleN]]
+end
+Playbooks --- Inventory
+Playbooks --> role1
+Playbooks --> roleN
+```
 
 The `inventory_ssh.yml` which provides s skeleton for you to update and match
 your architecture so each component can be deployed on a dedicated node.
 
-![SSH Deployment Type](./resources/deployment-type-ssh.png)
+```mermaid
+flowchart LR
+user[👤] --> Playbooks
+subgraph Control Node
+  Playbooks
+  Inventory
+end
+subgraph node1
+  role1[[role1]]
+end
+subgraph nodeN
+  roleN[[roleN]]
+end
+Playbooks --> node1
+Playbooks --> nodeN
+Inventory --- Playbooks
+```
 
 The `inventory_ha.yml` which is very similar to the previous one but also
-provides s skeleton for repository clustering (see [the deployment guide](./deployment-guide.md) for details on repository clustering).
+provides support for repository clustering (see [acs cluster section](#acs-cluster) for more details).
 
 A complete documentation about inventory file is available at [inventory file](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#intro-inventory)
 
@@ -787,7 +815,33 @@ amp_downloads:
 
 The diagram below shows the result of a localhost deployment.
 
-![Localhost Deployment](./resources/acs-localhost.png)
+```mermaid
+graph LR
+user[👤] --> playbook
+subgraph CN[Control Node]
+  playbook(Playbooks)
+  activemq[ActiveMQ]
+  elasticsearch[ElasticSearch]
+  nginx[Nginx]
+  repository[Repository]
+  postgres[Postgres]
+  search_enterprise[Search Enterprise]
+  sfs[Shared File Store]
+  sync[Sync Service]
+  transformers[AIO Transform Engine]
+  trouter(Transform Router)
+end
+playbook --> activemq
+playbook --> elasticsearch
+playbook --> nginx
+playbook --> repository
+playbook --> postgres
+playbook --> search_enterprise
+playbook --> sfs
+playbook --> sync
+playbook --> transformers
+playbook --> trouter
+```
 
 To deploy ACS 23.1 Enterprise on the local machine navigate to the folder you extracted the ZIP to and execute the playbook as the current user using the following command (the playbook will escalate privileges when required):
 
@@ -858,7 +912,26 @@ If you want to deploy everything to a single machine follow the steps in the [Si
 
 The diagram below shows the result of a single machine deployment.
 
-![Single Machine Deployment](./resources/acs-single-machine.png)
+```mermaid
+graph LR
+user[👤] --> playbook
+subgraph CN[Control Node]
+  playbook(Playbooks)
+end
+subgraph TN[Target Node]
+  activemq[ActiveMQ]
+  elasticsearch[ElasticSearch]
+  nginx[Nginx]
+  repository[Repository]
+  postgres[Postgres]
+  search_enterprise[Search Enterprise]
+  sfs[Shared File Store]
+  sync[Sync Service]
+  transformers[AIO Transform Engine]
+  trouter(Transform Router)
+end
+playbook --> TN
+```
 
 Once you have prepared the target host and configured the inventory_ssh.yaml file you are ready to run the playbook.
 
@@ -916,7 +989,52 @@ Once ACS has initialized access the system using the following URLs with a brows
 
 The diagram below shows the result of a multi machine deployment.
 
-![Multi Machine Deployment](./resources/acs-multi-machine.png)
+```mermaid
+graph LR
+user[👤] --> playbook
+subgraph CN[Control Node]
+  playbook(Playbooks)
+end
+subgraph database_node
+  postgres[Postgres]
+end
+subgraph repository_node
+  repository[Repository]
+end
+subgraph activemq_node
+  activemq[ActiveMQ]
+end
+subgraph search_node
+  elasticsearch[ElasticSearch]
+  search_enterprise[Search Enterprise]
+end
+subgraph nginx_node
+  nginx[Nginx]
+end
+subgraph acc_node
+  acc[Control Center]
+end
+subgraph adw_node
+  adw[Digital Workspace]
+end
+subgraph sync_node
+  sync[Sync Service]
+end
+subgraph transformers_node
+  transformers[AIO Transform Engine]
+  trouter(Transform Router)
+  sfs[Shared File Store]
+end
+playbook --> database_node
+playbook --> repository_node
+playbook --> activemq_node
+playbook --> search_node
+playbook --> nginx_node
+playbook --> acc_node
+playbook --> adw_node
+playbook --> sync_node
+playbook --> transformers_node
+```
 
 Once you have prepared the target hosts (ensuring the [relevant ports](#tcp-port-configuration) are accessible) and configured the inventory_ssh.yaml file you are ready to run the playbook.
 
@@ -972,7 +1090,7 @@ Once ACS has initialized access the system using the following URLs with a brows
 
 ### Additional command switches for ansible-playbook
 
-There are some useful argument you can use with `ansible-playbook` command in many circumstances. Some are highlighted bellow but take a look at [The ansible-playbook documentation](https://docs.ansible.com/ansible/latest/cli/ansible-playbook.html) for complete list of options.
+There are some useful argument you can use with `ansible-playbook` command in many circumstances. Some are highlighted below but take a look at [The ansible-playbook documentation](https://docs.ansible.com/ansible/latest/cli/ansible-playbook.html) for complete list of options.
 
 * `-k` : Prompt for SSH password. Useful when no SSH keys have been deployed but needs to be th same on all hosts (prefer SSH whenever possible)
 * `-K` : Prompt for sudo password. Useful when the user used to connect to the machine is not root

docs/index.md

@@ -6,20 +6,14 @@ nav_order: 1
 
 # Alfresco Ansible Deployment
 
-This project provides an [Ansible](https://www.ansible.com) playbook capable of
-deploying Alfresco Content Services (ACS).
-
-Ansible is an open-source software provisioning, configuration management and
-application-deployment tool enabling infrastructure as code.
-
-A user runs a playbook that deploys to any number of hosts as shown in the
-diagram below.
-
-![Ansible Overview](./resources/ansible-overview.png)
+This project provides [Ansible](https://www.ansible.com) playbooks capable of
+deploying Alfresco Content Services (ACS) on one or more nodes (typically
+Virtual Machines).
 
 ## Prerequisites
 
-* If you want to install the Enterprise version, Nexus credentials for [https://artifacts.alfresco.com](https://artifacts.alfresco.com) are required.
+* If you want to install the Enterprise version, Nexus credentials for
+  [https://artifacts.alfresco.com](https://artifacts.alfresco.com) are required.
 
 ## Documentation
 

docs/overview.md

@@ -15,8 +15,6 @@ It doesn't use any agents nor additional custom security infrastructure, so it's
 
 An Ansible playbook contains one or more roles. A role is an independent component which allows reuse of common configuration steps. It consists of a set of tasks used to configure a host to serve a certain purpose, for example, configuring a service. This is depicted in the diagram below.
 
-![Playbook Overview](./resources/playbook-overview.png)
-
 Roles are defined using YAML files with a predefined directory structure.
 
 A role directory structure contains directories: defaults, vars, tasks, files, templates, meta, and handlers.