Update documentation

README.md

@@ -46,6 +46,12 @@ ansible-playbook opentermsarchive.deployment.<playbook-name> --check --diff
 
 > See “[Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html)” in Ansible’s user guide for more information about Ansible collections.
 
+### Versions compatibility
+
+| Deployment | Engine | Federated API |
+| --- | --- | --- |
+| 0.1.0 | >= 0.36.0 | >= 0.1.0 |
+
 - - -
 
 ### Engine application
@@ -62,13 +68,19 @@ Available playbooks for the engine application:
 
 Available [variables](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html) are listed below, along with default values:
 
-| Variable | Description | Default value |
-| --- | --- | --- |
-| `ota_engine_config_path` | Path to the engine config file related to the inventory file | `../config/production.json` |
-| `ota_engine_declarations_branch` | [Git branch or tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish) of the declarations repository to use | `main` |
-| `ota_engine_snapshots_branch` | [Git branch or tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish) of the snapshots repository to use | `main` |
-| `ota_engine_versions_branch` | [Git branch or tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish) of the versions repository to use | `main` |
-| `ota_engine_declarations_directory` | Path of the directory where the code will be deployed on the server | Value declared in the `name` key in the engine config file |
+| Variable | Description | Default value | Required |
+| --- | --- | --- | --- |
+| `ota_engine_ota_bot_private_key` | SSH private key of GitHub user with privileges on snapshots and versions repositories. | No default value | ✔︎ |
+| `ota_engine_smtp_password` | Password for the SMTP server used for sending errors notifications by email | No default value | - |
+| `ota_engine_sendinblue_api_key` | SendInBlue API key used to send email notifications | No default value | - |
+| `ota_engine_github_token` | When defined, this authentication token enables GitHub issue creation on the declarations repository | No default value | - |
+| `ota_engine_config_path` | Path to the engine config file related to the inventory file | `../config/production.json` | - |
+| `ota_engine_declarations_branch` | [Git branch or tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish) of the declarations repository to use | `main` | - |
+| `ota_engine_snapshots_branch` | [Git branch or tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish) of the snapshots repository to use | `main` | - |
+| `ota_engine_versions_branch` | [Git branch or tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish) of the versions repository to use | `main` | - |
+| `ota_engine_declarations_directory` | Path of the directory where the code will be deployed on the server | Value declared in the `name` key in the engine config file | - |
+
+For encryption of sensitive configuration entries, please refer to the [dedicated section](#encrypt-sensitive-configuration-entries).
 
 These variables can be overriden in the inventory file, for example:
 
@@ -108,11 +120,14 @@ Available playbooks for the Federated API application:
 
 Available variables are listed below, along with default values:
 
-| Variable | Description | Default value |
-| --- | --- | --- |
-| `ota_federated_api_repo` | Repository URL of the federated API code | `https://github.com/OpenTermsArchive/federated-api.git` |
-| `ota_federated_api_directory` | Path of the directory where the code will be deployed on the server | `federated-api` |
-| `ota_federated_api_branch` | [Git branch or tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish) of the federated API repository to use | `main` |
+| Variable | Description | Default value | Required |
+| --- | --- | --- | --- |
+| `ota_federated_api_repo` | Repository URL of the federated API code | `https://github.com/OpenTermsArchive/federated-api.git` | - |
+| `ota_federated_api_directory` | Path of the directory where the code will be deployed on the server | `federated-api` | - |
+| `ota_federated_api_branch` | [Git branch or tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftree-ishatree-ishalsotreeish) of the federated API repository to use | `main` | - |
+| `ota_federated_api_smtp_password` | Password for the SMTP server used for sending errors notifications by email. | - | - |
+
+For encryption of sensitive configuration entries, please refer to the [dedicated section](#encrypt-sensitive-configuration-entries).
 
 These variables can be overridden in the inventory file, for example:
 
@@ -137,6 +152,61 @@ Available [tags](https://docs.ansible.com/ansible/latest/user_guide/playbooks_ta
 
 - - -
 
+## Encrypt sensitive configuration entries
+
+Certain configuration entries contain sensitive information that should be encrypted to ensure security. Ansible provides a convenient way to encrypt such strings using its built-in [vault feature](https://docs.ansible.com/ansible/2.9/user_guide/vault.html):
+
+```sh
+ansible-vault encrypt_string --name <sensitive-config-name> <sensitive-config-content>
+```
+
+For example, to encrypt the OTA-Bot private key required by the engine:
+
+```sh
+ansible-vault encrypt_string --name 'ota_engine_ota_bot_private_key' '-----BEGIN OPENSSH PRIVATE KEY-----
+b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAABlwAAAAdzc2gtcn
+…
+UlcCkBZ5IkI0eNAAAAE25kcG50QE1CUC1OZHBudC5sYW4BAgMEBQYH
+-----END OPENSSH PRIVATE KEY-----
+'
+```
+
+The encrypted result will look like this:
+
+```sh
+ota_engine_ota_bot_private_key: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          62313438616266383732353634343736623532666365643364396464633732613966636235616261
+          3136656665316437613434323561613732373361306161640a306132316531356537373862363838
+          66363763613833373530633831653163303961376331393761366261633561656463626563383931
+          3361643836623239660a333134626139626465303234313366313433653261376437316231363834
+          32643261303534366333383131633430396366343631656363663965633964663331346231663166
+          3331316462356461373134303666613035393335333139613639
+```
+
+Then it can be used directly in the inventory file:
+
+```yml
+all:
+  hosts:
+    127.0.0.1:
+      ansible_user: debian
+      ota_engine_config_path: ./engine_config.json
+      ota_engine_declarations_branch: new-feature
+      ota_engine_ota_bot_private_key: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          62313438616266383732353634343736623532666365643364396464633732613966636235616261
+          3136656665316437613434323561613732373361306161640a306132316531356537373862363838
+          66363763613833373530633831653163303961376331393761366261633561656463626563383931
+          3361643836623239660a333134626139626465303234313366313433653261376437316231363834
+          32643261303534366333383131633430396366343631656363663965633964663331346231663166
+          3331316462356461373134303666613035393335333139613639
+```
+
+Repeat the process for each sensitive configuration entry that needs encryption.
+
+- - -
+
 ## Development
 
 ### Requirements
@@ -204,7 +274,6 @@ vagrant halt  # stop machine
 vagrant destroy  # remove machine
 vagrant up
 ```
-
 ---
 
 ## License