OPSEXP-2365 Update docs for v7.0.0 (#1042)

.pre-commit-config.yaml

@@ -39,7 +39,7 @@ repos:
       - id: docker-compose-check
         exclude: override-docker-compose.yml
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.32.2
+    rev: v0.37.0
     hooks:
       - id: markdownlint
         args: ["--ignore", "helm/**/README.md"]

README.md

@@ -6,50 +6,56 @@
 [![docker-compose (enterprise)](https://github.com/Alfresco/acs-deployment/actions/workflows/docker-compose-enterprise.yml/badge.svg)](https://github.com/Alfresco/acs-deployment/actions/workflows/docker-compose-enterprise.yml)
 [![docker-compose (community)](https://github.com/Alfresco/acs-deployment/actions/workflows/docker-compose-community.yml/badge.svg)](https://github.com/Alfresco/acs-deployment/actions/workflows/docker-compose-community.yml)
 
-This project contains the code for starting the entire Alfresco Content
-Services (ACS) product with [Docker](https://docs.docker.com/get-started) using
-[Docker Compose](https://docs.docker.com/compose) or
+This project contains the code for running Alfresco Content Services (ACS) with
+[Docker](https://docs.docker.com/get-started) using [Docker
+Compose](https://docs.docker.com/compose) or on
 [Kubernetes](https://kubernetes.io) using [Helm Charts](https://helm.sh).
 
-Our tests are executed using Helm, kubectl versions provided by github action
-runners [Ubuntu-22.04](https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md#ubuntu-2204)
-and against EKS clusters running Kubernetes 1.21 & 1.22.
+Automated tests for helm charts are running on KinD cluster v1.25 and EKS v1.27.
+
+## Important changes for helm charts
+
+The v7.0.0 release is the first release of the acs helm charts which completely
+leverage the new individual subcharts we started releasing since March 2023 in a
+dedicated repo:
+[alfresco-helm-charts](https://github.com/Alfresco/alfresco-helm-charts).
+
+This change will make life easier to whoever want to customize or extend the
+helm deployments and simplify the future maintenance, at the cost of breaking
+the compatibility with the values structure which remained almost stable since
+the v6 release.
+
+Please review the new [values](helm/alfresco-content-services/values.yaml)
+carefully and adapt any custom configuration you may have. You can read the
+[upgrades guide](docs/helm/upgrades.md) for more details on the changes.
+
+> Deploying to new namespace is always the preferred way of upgrading ACS as we
+> do not test charts for upgrade scenarios (even with previous versions)
+> neither do we provide roll-back facilities.
 
 ## Prerequisites
 
-By default the Enterprise version of ACS is installed. To accomplish this
-private Docker images stored in Quay.io are downloaded. Alfresco customers can
-request Quay.io credentials by logging a ticket with
-[Alfresco Support](https://support.alfresco.com/).
+The ACS Enterprise version is installed by default, using Docker images from
+Quay.io. If you're an Alfresco customer, you can request Quay.io credentials by
+logging a ticket with [Hyland Community](https://community.hyland.com).
 
-The images downloaded directly from Docker Hub, or Quay.io are for a limited
-trial of the Enterprise version of Alfresco Content Services that goes into
-read-only mode after 2 days. If you'd like to try Alfresco Content Services for
-a longer period, request the 30-day
-[Download Trial](https://www.alfresco.com/platform/content-services-ecm/trial/download).
+The repository Docker image provides a limited trial of the Enterprise version
+of Alfresco Content Services, which switches to read-only mode after 2 days. For
+a longer trial, you can request the 30-day [Download
+Trial](https://www.alfresco.com/platform/content-services-ecm/trial/download).
 
-To avoid license restrictions and private Docker images follow the instructions
-to deploy the Community Edition.
+The Community Edition can be installed without the need of a license or quay.io
+account.
 
 ## Versioning
 
-**NOTE:** **The versioning strategy used in this project has changed, if you
-have previously used this project please read this section carefully!**
-
 The master branch of this repository now contains the artifacts required to
 deploy both the the latest work-in-progress development version and previous
-stable versions of ACS.
+stable versions of ACS that are still supported.
 
-The default behaviour is to use the latest work-in-progress development version
-however, individual files are now provided to deploy the latest hot fix version
-of each major.minor version of ACS. The `support/*` branches will remain in
-place but will no longer be maintained.
-
-A new version numbering scheme is also being introduced. During the development
-phase one or more milestone releases will be produced indicated by an `M`
-suffix, for example "5.0.0-M1". Once feature complete one or more RC releases
-will be produced followed by the final GA release. Upon release the repository
-will be tagged with the release number.
+During the development phase, one or more milestone releases will be produced
+indicated by an `-M` suffix, for example `6.0.0-M.1``. Once an ACS version
+become GA, also a GA release of this repository will be published.
 
 The table below shows the exact version of ACS deployed with each chart version/tag.
 
@@ -95,16 +101,11 @@ The table below shows the exact version of ACS deployed with each chart version/
 
 ### Why there is no 5.4.0?
 
-During the development of 5.4.0 we've started turning subcharts (search, sync,
-activemq, ...) into individual charts hosted on a new repository. That decision
-introduces some breaking changes like resource renaming and values structure
-modifications. For that reason we chose to bump to a new major version to
-capture the fact upgrades can be problematic and one should prefer deploying new
-version to a new namespace rather than attempting upgrades.
-
-> Deploying to new namespace is always the preferred way of upgrading ACS as we
-> do not test charts for upgrade scenarios (even with previous versions)
-> neither do we provide roll-back facilities.
+During the development of 5.4.0 we've started moving individual components
+templates (search, sync, activemq, ...) into individual charts on
+[alfresco-helm-charts](https://github.com/Alfresco/alfresco-helm-charts). That
+decision introduced some breaking changes like resource renaming and values
+structure modifications that has been shipped since v6.0.0.
 
 ### End of Life'd versions
 
@@ -120,7 +121,7 @@ file for a version with the latest charts or using the old charts.
 | 6.2                     | 5.3.0                           |
 | 6.1                     | 5.1.1                           |
 
-> These charts are mentioned for reference but are not supported.
+> These charts should not be used for any new deployment but just for reference.
 
 ## Getting Started
 
@@ -167,8 +168,8 @@ Start the release by opening a PR against the appropriate branch that will:
   first time with `charts` option. Inspect the changes pushed on the branch,
   revert unwanted changes if necessary.
 * Run [Bump versions][1] workflow against the same branch with option `values`.
-  Inspect the changes pushed on the branch, revert unwanted changes if
-  necessary.
+  This will update both docker compose tags and helm charts values.
+  Inspect the changes pushed on the branch, looking for any missing update.
 
 [1]: https://github.com/Alfresco/acs-deployment/actions/workflows/bumpVersions.yml
 

docs/helm/desktop-deployment.md

@@ -23,6 +23,8 @@ default ingress controller. You may need to exit and restart Rancher Desktop
 for the change to take effect. Ref: [Setup NGINX Ingress
 Controller](https://docs.rancherdesktop.io/how-to-guides/setup-NGINX-Ingress-Controller)
 
+Then proceed to the [deployment](#deployment) section to install ingress-nginx.
+
 ### Docker Desktop specific configuration
 
 On top of the Docker desktop

docs/helm/eks-deployment.md

@@ -464,8 +464,8 @@ Deploy the latest version of ACS by running the following command (replacing
 helm install acs alfresco/alfresco-content-services \
   --set alfresco-repository.persistence.enabled=true \
   --set alfresco-repository.persistence.storageClass="nfs-client" \
-  --set filestore.persistence.enabled=true \
-  --set filestore.persistence.storageClass="nfs-client" \
+  --set alfresco-transform-service.filestore.persistence.enabled=true \
+  --set alfresco-transform-service.filestore.persistence.storageClass="nfs-client" \
   --set global.known_urls=https://acs.YOUR-DOMAIN-NAME \
   --set global.alfrescoRegistryPullSecrets=quay-registry-secret \
   --set global.search.sharedSecret=$(openssl rand -hex 24) \
@@ -510,8 +510,8 @@ helm install acs alfresco/alfresco-content-services \
     --set global.known_urls=https://acs.YOUR-DOMAIN-NAME \
     --set alfresco-repository.persistence.enabled=true \
     --set alfresco-repository.persistence.storageClass="nfs-client" \
-    --set filestore.persistence.enabled=true \
-    --set filestore.persistence.storageClass="nfs-client" \
+    --set alfresco-transform-service.filestore.persistence.enabled=true \
+    --set alfresco-transform-service.filestore.persistence.storageClass="nfs-client" \
     --set global.alfrescoRegistryPullSecrets=quay-registry-secret \
     --set global.search.sharedSecret=$(openssl rand -hex 24) \
     --atomic \

docs/helm/examples/with-ai.md

@@ -29,10 +29,10 @@ setup of the services):
 ```bash
 helm install acs alfresco/alfresco-content-services \
   --set alfresco-repository.persistence.enabled=false \
-  --set filestore.persistence.enabled=true \
-  --set filestore.persistence.storageClass="nfs-client" \
+  --set alfresco-transform-service.filestore.persistence.enabled=true \
+  --set alfresco-transform-service.filestore.persistence.storageClass="nfs-client" \
   --set global.known_urls=https://acs.YOUR-DOMAIN-NAME \
-  --set global.search.sharedSecret:=$(openssl rand -hex 24) \
+  --set global.search.sharedSecret=$(openssl rand -hex 24) \
   --set global.alfrescoRegistryPullSecrets=quay-registry-secret \
   --set alfresco-repository.image.repository="quay.io/alfresco/alfresco-content-repository-aws" \
   --set share.image.repository="quay.io/alfresco/alfresco-share-aws" \

docs/helm/examples/with-aws-services.md

@@ -45,18 +45,20 @@ The rest of this document assume EFS is used for SFS. To disable it replace
 the values below:
 
 ```yaml
-filestore:
-  persistence:
-    enabled: true
-    storageClass: nfs-client
+alfresco-transform-service:
+  filestore:
+    persistence:
+      enabled: true
+      storageClass: nfs-client
 ```
 
 with:
 
 ```yaml
-filestore:
-  persistence:
-    enabled: false  # or use helm CLI --set filestore.persistence.enabled=false
+alfresco-transform-service:
+  filestore:
+    persistence:
+      enabled: false  # or use helm CLI --set alfresco-transform-service.filestore.persistence.enabled=false
 ```
 
 ## Setup Services
@@ -255,10 +257,11 @@ alfresco-repository:
     CATALIAN_OPTS: >-
       -Ds3.bucketName=YOUR-BUCKET-NAME
       -Ds3.bucketLocation=YOUS_AWS_REGION
-filestore:
-  persistence:
-    enabled: true
-    storageClass: nfs-client
+alfresco-transform-service:
+  filestore:
+    persistence:
+      enabled: true
+      storageClass: nfs-client
 postgresql:
   enabled: false
 database:
@@ -320,8 +323,8 @@ helm -n alfresco install acs \
   --set alfresco-repository.image.repository=alfresco-content-repository-aws \
   --set alfresco-repository.configuration.search.flavor=elasticsearch \
   --set alfresco-repository.configuration.search.securecomms=https \
-  --set filestore.persistence.enabled=true \
-  --set filestore.persistence.storageClass="nfs-client" \
+  --set alfresco-transform-service.filestore.persistence.enabled=true \
+  --set alfresco-transform-service.filestore.persistence.storageClass="nfs-client" \
   --set alfresco-repository.image.repository="quay.io/alfresco/alfresco-content-repository-aws" \
   --set alfresco-repository.environment.CATALINA_OPTS="-Ds3.bucketName=YOUR-BUCKET-NAME -Ds3.bucketLocation=YOUS_AWS_REGION" \
   --set postgresql.enabled=false \

docs/helm/examples/with-ms-teams.md

@@ -24,8 +24,8 @@ When we bring all this together we can deploy ACS using the command below (repla
 ```bash
 helm install acs alfresco/alfresco-content-services \
   --set alfresco-repository.persistence.enabled=true \
-  --set filestore.persistence.enabled=true \
-  --set filestore.persistence.storageClass="nfs-client" \
+  --set alfresco-transform-service.filestore.persistence.enabled=true \
+  --set alfresco-transform-service.filestore.persistence.storageClass="nfs-client" \
   --set global.known_urls=https://acs.YOUR-DOMAIN-NAME \
   --set global.search.sharedSecret:=$(openssl rand -hex 24) \
   --set global.alfrescoRegistryPullSecrets=quay-registry-secret \
@@ -40,14 +40,14 @@ helm install acs alfresco/alfresco-content-services \
   --set messageBroker.user="alfresco" \
   --set messageBroker.password="YOUR-MQ-PASSWORD" \
   --set msTeams.enabled=true \
-  --set msTeamsService.alfresco.baseUrl="https://acs.YOUR-DOMAIN-NAME:443"
-  --set msTeamsService.alfresco.digitalWorkspace.contextPath="/workspace/" \
-  --set msTeamsService.microsoft.app.id="YOUR-MS-APP-ID" \
-  --set msTeamsService.microsoft.app.password="YOUR-MS-APP-PWD" \
-  --set msTeamsService.microsoft.app.oauth.connectionName="alfresco" \
-  --set msTeamsService.teams.chat.filenameEnabled=true \
-  --set msTeamsService.teams.chat.metadataEnabled=true \
-  --set msTeamsService.teams.chat.imageEnabled=true \
+  --set alfresco-connector-msteams.alfresco.baseUrl="https://acs.YOUR-DOMAIN-NAME:443" \
+  --set alfresco-connector-msteams.alfresco.digitalWorkspace.contextPath="/workspace/" \
+  --set alfresco-connector-msteams.microsoft.app.id="YOUR-MS-APP-ID" \
+  --set alfresco-connector-msteams.microsoft.app.password="YOUR-MS-APP-PWD" \
+  --set alfresco-connector-msteams.microsoft.app.oauth.connectionName="alfresco" \
+  --set alfresco-connector-msteams.teams.chat.filenameEnabled=true \
+  --set alfresco-connector-msteams.teams.chat.metadataEnabled=true \
+  --set alfresco-connector-msteams.teams.chat.imageEnabled=true \
   --atomic \
   --timeout 10m0s \
   --namespace=alfresco

docs/helm/examples/with-ooi.md

@@ -27,8 +27,8 @@ setup of the services):
 ```bash
 helm install acs alfresco/alfresco-content-services \
   --set alfresco-repository.persistence.enabled=false \
-  --set filestore.persistence.enabled=true \
-  --set filestore.persistence.storageClass="nfs-client" \
+  --set alfresco-transform-service.filestore.persistence.enabled=true \
+  --set alfresco-transform-service.filestore.persistence.storageClass="nfs-client" \
   --set global.known_urls=https://acs.YOUR-DOMAIN-NAME \
   --set global.search.sharedSecret:=$(openssl rand -hex 24) \
   --set global.alfrescoRegistryPullSecrets=quay-registry-secret \
@@ -42,7 +42,7 @@ helm install acs alfresco/alfresco-content-services \
   --set messageBroker.url="YOUR-MQ-ENDPOINT" \
   --set messageBroker.user="alfresco" \
   --set messageBroker.password="YOUR-MQ-PASSWORD" \
-  --set ooi.enabled=true \
+  --set alfresco-connector-ms365.enabled=true \
   --set-string alfresco-digital-workspace.env.APP_CONFIG_PLUGIN_MICROSOFT_ONLINE="true" \
   --set alfresco-digital-workspace.env.APP_CONFIG_MICROSOFT_ONLINE_OOI_URL="https://YOUR-EXTERNAL-HOST/ooi-service/api/-default-/private/office-integration/versions/1/edit-sessions/" \
   --set alfresco-digital-workspace.env.APP_CONFIG_MICROSOFT_ONLINE_CLIENTID="YOUR-ADW-MS-ONLINE-CLIENT-ID" \