diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..b521a14a7 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,28 @@ +name: Publish docs + +permissions: + contents: write + pages: write + id-token: write + +on: + push: + branches: + - master + paths: + - "docs/**" + - ".github/workflows/docs.yml" + pull_request: + branches: + - master + paths: + - "docs/**" + - ".github/workflows/docs.yml" + +jobs: + publish: + uses: Alfresco/jekyll-build-tools/.github/workflows/jekyll-publish.yml@main + with: + working-directory: . + publish: ${{ github.event_name == 'push' && github.ref_name == 'master'}} + validate-html: true diff --git a/.gitignore b/.gitignore index 843166d35..b5faa9bc5 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,5 @@ hs_err_pid* # updatecli workflow alfresco-updatecli merged.yaml + +_site diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 5d76b9151..87653ffea 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,3 +1,4 @@ --- default: true MD013: false +MD025: false diff --git a/.ruby-version b/.ruby-version new file mode 100644 index 000000000..0aec50e6e --- /dev/null +++ b/.ruby-version @@ -0,0 +1 @@ +3.1.4 diff --git a/Gemfile b/Gemfile new file mode 100644 index 000000000..222231a2f --- /dev/null +++ b/Gemfile @@ -0,0 +1,6 @@ +source 'https://rubygems.org' + +gem "jekyll", "~> 4.3.3" +gem "just-the-docs", "0.8.1" +gem "jekyll-relative-links" +gem "html-proofer" diff --git a/README.md b/README.md index 1e67068f4..153e85054 100644 --- a/README.md +++ b/README.md @@ -15,107 +15,7 @@ This project contains the code for running Alfresco Content Services (ACS) with Compose](https://docs.docker.com/compose) or on [Kubernetes](https://kubernetes.io) using [Helm Charts](https://helm.sh). -> Automated tests for helm charts are running on KinD cluster v1.29 and EKS v1.28. - -## 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 - -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 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). - -The Community Edition can be installed without the need of a license or quay.io -account. - -## Versioning - -As of version 8.0.0 of the chart we have changed the release policy. -Previously, the chart was released together with the ACS product and we were -delivering additional values files for each major release of ACS (e.g. 7.3, -7.4, ...) and chart version were bumped with a similar increment as ACS. -With version 6.0.0, we started applying major versions bumps to reflect -breaking changes in the chart, despite only minor ACS release happened. - -With 8.0.0 onward, the release pace of the chart is completely independent from -the product versions. We will also stick to Semver principles when choosing -next version number, meaning that: - -* patch version will be used for bug fixes (last digit) -* minor version will be used for new features and modifications which do not - introduce breaking changes in the configuration interface. -* major version will be used for changes which involve breaking changes in the - configuration interface. - -The `alfresco-content-services` chart has always provided the ability to deploy -any currently supported version of ACS and its components and will continue to -do so. You are encoraged to always use the latest version of the chart to -deploy your ACS version, using the appropriate values file. For that reason we -stop providing the table mapping chart versions with the ACS version they -deploy (by default). Instead we'll just maintain the list of deprecated versions -versions mapped with the latest versions of the charts we tested deployment -with, so you can use that version to deploy older ACS version on Kubernetes. -Check the [ACS End of Life'd versions](#acs-end-of-lifed-versions) paragraph. - -You are encouraged to always use the latest version of the chart to deploy your -currently supported ACS version, using the appropriate values file. - -Finally, the master branch of this repository used to contain the latest -versions, including non-released versions! -We're also moving away from this pattern and the chart will now only ever -deploy released versions of our products. - -Should you want to try our latest dev versions, we now provide an additional -values file called `pre-release_values.yaml` which will be bumped on a regular -basis. - -This also means we will not produce `-M*` versions of the chart anymore. - -Check the [Release page](https://github.com/Alfresco/acs-deployment/releases) for the list of existing versions. - -### ACS End of Life'd versions - -While our latest version of the charts should be able to deployment any version -of ACS (theoretically), we only ever test deployment of _currently_ supported -versions. Also we do not provide values files for older unsupported version. If -you need to deploy old version we provide a reference table below to allow you -find the older values files and charts. You can either try using the values -file for a version with the latest charts or using the old charts. - -| unsupported ACS version | Last chart version providing it | -|-------------------------|---------------------------------| -| 7.0 | 8.0.1 | -| 6.2 | 5.3.0 | -| 6.1 | 5.1.1 | - -> These charts should not be used for any new deployment but just for reference. - -## Getting Started - -To get started please refer to the [Docker Compose](./docs/docker-compose) and [Helm Chart](./docs/helm) documentation. +User docs available at: [https://alfresco.github.io/acs-deployment/](https://alfresco.github.io/acs-deployment/) ## License @@ -146,7 +46,7 @@ First ensure that: Start the release by opening a PR against the appropriate branch that will: -* Update the [EOL table](#acs-end-of-lifed-versions) in case a version is deprecated +* Update the [EOL table](docs/index.md#acs-end-of-lifed-versions) in case a version is deprecated * In [alfresco-content-services](helm/alfresco-content-services/Chart.yaml), bump chart version to the version you want to release * Run `pre-commit run --all-files helm-docs` to update helm docs diff --git a/_config.yml b/_config.yml new file mode 100644 index 000000000..a8cb15f20 --- /dev/null +++ b/_config.yml @@ -0,0 +1,48 @@ +title: ACS Deployment Documentation +description: User documentation for deploying Alfresco Content Services +theme: just-the-docs +color_scheme: alfresco + +url: https://alfresco.github.io + +aux_links: + Docs: https://docs.alfresco.com/ + GitHub Repository: https://github.com/Alfresco/acs-deployment + +aux_links_new_tab: true + +gh_edit_link: true +gh_edit_link_text: "Improve this page on GitHub" +gh_edit_repository: https://github.com/Alfresco/acs-deployment +gh_edit_branch: master +gh_edit_source: . +gh_edit_view_mode: edit + +logo: "docs/images/hyland-alfresco-logos.png" +favicon_ico: "docs/images/favicon.ico" + +defaults: + # apply the default layout to all markdown pages + - scope: + path: "*" + values: + layout: default + render_with_liquid: false + +exclude: + - Brewfile + - '*/ci/*' + - Gemfile + - Gemfile.lock + - '*.yaml' + - '*/Chart.lock' + - '*.tgz' + - '*/NOTES.txt' + - README.md + - LICENSE + +plugins: + - jekyll-relative-links + +mermaid: + version: "10.9.0" diff --git a/_includes/head_custom.html b/_includes/head_custom.html new file mode 100644 index 000000000..d555d471f --- /dev/null +++ b/_includes/head_custom.html @@ -0,0 +1,3 @@ + diff --git a/_sass/color_schemes/alfresco.scss b/_sass/color_schemes/alfresco.scss new file mode 100644 index 000000000..7cc0d84fe --- /dev/null +++ b/_sass/color_schemes/alfresco.scss @@ -0,0 +1,13 @@ +$link-color: #3273dc; +$body-font-family: "Inter", sans-serif; + +$font-size-5: 0.88rem; + +.main-content { + color: #212328; + font-weight: 300; +} + +td { + word-wrap: anywhere; +} diff --git a/docs/compose.md b/docs/compose.md new file mode 100644 index 000000000..f71f5f70e --- /dev/null +++ b/docs/compose.md @@ -0,0 +1,6 @@ +--- +title: Docker Compose +has_children: true +--- + +This section contains available guides for docker-compose deployment diff --git a/docs/docker-compose/README.md b/docs/docker-compose/README.md index 8ff8311bd..de14b167f 100644 --- a/docs/docker-compose/README.md +++ b/docs/docker-compose/README.md @@ -1,3 +1,8 @@ +--- +title: Deployment +parent: Docker Compose +--- + # Alfresco Content Services Docker Compose Deployment This page describes how to quickly deploy Alfresco Content Services (ACS) using @@ -110,8 +115,7 @@ suited for test or demo environment but certainly not for production use. ## Prerequisites -As well as the prerequisites mentioned on the [main -README](/README.md#prerequisites) you will need a machine with at least 13GB of +As well as the prerequisites mentioned on the [main README](../index.md#prerequisites) you will need a machine with at least 13GB of free memory and the following software installed: * [Docker](https://www.docker.com/products/docker-desktop) @@ -131,7 +135,7 @@ Docker Daemon). ## Deploy 1. Clone this repository or download one of the docker compose files from - [here](../../docker-compose) + [here](https://github.com/Alfresco/acs-deployment/tree/master/docker-compose) 2. Navigate to the folder where the docker compose file you want to use is located 3. Log in to Quay.io with your credentials: `docker login quay.io` (only @@ -140,14 +144,14 @@ Docker Daemon). `docker compose -f major.minor.N-docker-compose.yml up` to use a previous version of ACS, or `docker compose -f pre-release-docker-compose.yml up` 5. Open the following URLs in your browser to check that everything starts up: - * Administration and REST APIs: [http://:8080/alfresco](http://localhost:8080/alfresco) - * Control Center: [http://:8080/admin](http://localhost:8080/admin) - * Alfresco Digital Workspace: [http://:8080/workspace](http://localhost:8080/workspace) - * Share: [http://:8080/share](http://localhost:8080/share) - * Search administration: [http://:8083/solr](http://localhost:8083/solr) + * Administration and REST APIs: `http://:8080/alfresco` + * Control Center: `http://:8080/admin` + * Alfresco Digital Workspace: `http://:8080/workspace` + * Share: `http://:8080/share` + * Search administration: `http://:8083/solr` 6. If you requested an extended trial license navigate to the Admin Console and apply your license: - * [http://:8080/alfresco/service/enterprise/admin/admin-license](http://localhost:8080/alfresco/service/enterprise/admin/admin-license) (`` will usually just be `localhost`) + * `http://:8080/alfresco/service/enterprise/admin/admin-license` (`` will usually just be `localhost`) * Default username and password is `admin` * See [Uploading a new license](https://docs.alfresco.com/content-services/latest/admin/license/#uploadlicense) for more details @@ -314,15 +318,15 @@ share: | SEARCH_LOG_LEVEL | The root logger level (`ERROR`, `WARN`, `INFO`, `DEBUG` or `TRACE`). | INFO | | ENABLE_SPELLCHECK | Whether spellchecking is enabled or not (`true` or `false`). | | | DISABLE_CASCADE_TRACKING | Whether cascade tracking is enabled or not (`true` or `false`). Disabling cascade tracking will improve performance, but result in some feature loss (e.g. path queries). | | -| ALFRESCO_SECURE_COMMS | Whether communication with the repository is secured (`https` or `none`). See this [page](https://github.com/Alfresco/InsightEngine/blob/master/search-services/README.md) for more details. | none | -| SOLR_SSL_KEY_STORE | Path to SSL key store. See this [page](https://github.com/Alfresco/InsightEngine/blob/master/search-services/README.md#use-alfresco-search-services-docker-image-with-docker-compose) for more details. | | -| SOLR_SSL_KEY_STORE_PASSWORD | Password for key store. See this [page](https://github.com/Alfresco/InsightEngine/blob/master/search-services/README.md#use-alfresco-search-services-docker-image-with-docker-compose) for more details. | | -| SOLR_SSL_KEY_STORE_TYPE | Key store type. See this [page](https://github.com/Alfresco/InsightEngine/blob/master/search-services/README.md#use-alfresco-search-services-docker-image-with-docker-compose) for more details. | JCEKS | -| SOLR_SSL_TRUST_STORE | Path to SSL trust store. See this [page](https://github.com/Alfresco/InsightEngine/blob/master/search-services/README.md#use-alfresco-search-services-docker-image-with-docker-compose) for more details. | | -| SOLR_SSL_TRUST_STORE_PASSWORD | Password for trust store. See this [page](https://github.com/Alfresco/InsightEngine/blob/master/search-services/README.md#use-alfresco-search-services-docker-image-with-docker-compose) for more details. | | -| SOLR_SSL_TRUST_STORE_TYPE | Trust store type. See this [page](https://github.com/Alfresco/InsightEngine/blob/master/search-services/README.md#use-alfresco-search-services-docker-image-with-docker-compose) for more details. | JCEKS | -| SOLR_SSL_NEED_CLIENT_AUTH | This variable is used to configure SSL (`true` or `false`). See this [page](https://github.com/Alfresco/InsightEngine/blob/master/search-services/README.md#use-alfresco-search-services-docker-image-with-docker-compose) for more details. | | -| SOLR_SSL_WANT_CLIENT_AUTH | This variable is used to configure SSL (`true` or `false`). See this [page](https://github.com/Alfresco/InsightEngine/blob/master/search-services/README.md#use-alfresco-search-services-docker-image-with-docker-compose) for more details. | | +| ALFRESCO_SECURE_COMMS | Whether communication with the repository is secured (`https` or `none`). See this [page](https://github.com/Alfresco/SearchServices/blob/master/search-services/README.md) for more details. | none | +| SOLR_SSL_KEY_STORE | Path to SSL key store. See this [page](https://github.com/Alfresco/SearchServices/blob/master/search-services/README.md) for more details. | | +| SOLR_SSL_KEY_STORE_PASSWORD | Password for key store. See this [page](https://github.com/Alfresco/SearchServices/blob/master/search-services/README.md) for more details. | | +| SOLR_SSL_KEY_STORE_TYPE | Key store type. See this [page](https://github.com/Alfresco/SearchServices/blob/master/search-services/README.md) for more details. | JCEKS | +| SOLR_SSL_TRUST_STORE | Path to SSL trust store. See this [page](https://github.com/Alfresco/SearchServices/blob/master/search-services/README.md) for more details. | | +| SOLR_SSL_TRUST_STORE_PASSWORD | Password for trust store. See this [page](https://github.com/Alfresco/SearchServices/blob/master/search-services/README.md) for more details. | | +| SOLR_SSL_TRUST_STORE_TYPE | Trust store type. See this [page](https://github.com/Alfresco/SearchServices/blob/master/search-services/README.md) for more details. | JCEKS | +| SOLR_SSL_NEED_CLIENT_AUTH | This variable is used to configure SSL (`true` or `false`). See this [page](https://github.com/Alfresco/SearchServices/blob/master/search-services/README.md) for more details. | | +| SOLR_SSL_WANT_CLIENT_AUTH | This variable is used to configure SSL (`true` or `false`). See this [page](https://github.com/Alfresco/SearchServices/blob/master/search-services/README.md) for more details. | | ### Alfresco Transform Router (transform-router) @@ -464,6 +468,6 @@ The list below shows the location of the publicly available `Dockerfile` for the * [share](https://github.com/Alfresco/share/blob/master/packaging/docker/Dockerfile) * [content-app](https://github.com/Alfresco/alfresco-content-app/blob/master/Dockerfile) * [solr6](https://github.com/Alfresco/SearchServices/blob/master/search-services/packaging/src/docker/Dockerfile) -* [transform-core-aio](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-transform-core-aio/alfresco-transform-core-aio-boot/Dockerfile) +* [transform-core-aio](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/aio/Dockerfile) * [activemq](https://github.com/Alfresco/alfresco-docker-activemq/blob/master/Dockerfile) * [proxy](https://github.com/Alfresco/acs-ingress/blob/master/Dockerfile) diff --git a/docs/docker-compose/examples/customisation-guidelines.md b/docs/docker-compose/examples/customisation-guidelines.md index 3fb966d62..a81d08a20 100644 --- a/docs/docker-compose/examples/customisation-guidelines.md +++ b/docs/docker-compose/examples/customisation-guidelines.md @@ -1,3 +1,8 @@ +--- +title: Customisation Guidelines +parent: Docker Compose +--- + # Customisation Guidelines Although it's possible to change and mount files/folders into existing Docker images the recommended approach is to create new custom Docker images. @@ -29,9 +34,9 @@ This process requires some familiarty with [Docker](https://www.docker.com/) and You will now need to install the AMP files into the Alfresco Content Repository image. -1. The docker-compose folder contains a file for each main code line of ACS, examine the relevant docker compose file for the version of ACS you want to apply the AMPs to. For example, to apply to the latest version of 7.3 take a look at the [7.3.N-docker-compose file](../../../docker-compose/7.3.N-docker-compose.yml) +1. The docker-compose folder contains a file for each main code line of ACS, examine the relevant docker compose file for the version of ACS you want to apply the AMPs to. For example, to apply to the latest version of 7.3 take a look at the [7.3.N-docker-compose file](https://github.com/Alfresco/acs-deployment/blob/master/docker-compose/7.3.N-docker-compose.yml) -2. Take note of the image and tag being used for the **alfresco** service in the docker compose file you chose in the previous step. For example, if you are using 7.3.N-docker-compose.yml, you will find this on [line 15](https://github.com/Alfresco/acs-deployment/blob/229fe58d077414c5d91bab9f5cec91adc902453c/docker-compose/7.3.N-docker-compose.yml#L15) as follows: +2. Take note of the image and tag being used for the **alfresco** service in the docker compose file you chose in the previous step. For example, if you are using 7.3.N-docker-compose.yml, you will find this on [line 21](https://github.com/Alfresco/acs-deployment/blob/master/docker-compose/7.3.N-docker-compose.yml) as follows: ```bash alfresco/alfresco-content-repository:7.3.0.1 @@ -90,7 +95,7 @@ You will now need to install the AMP files into the Alfresco Content Repository We will now repeat the process for the Alfresco Share image. -1. Take note of the image and tag being used for the **share** service in the docker compose file you chose in the previous section. For example, if you are using 7.3.N-docker-compose.yml, you will find this on [line 89](https://github.com/Alfresco/acs-deployment/blob/229fe58d077414c5d91bab9f5cec91adc902453c/docker-compose/7.3.N-docker-compose.yml#L89) as follows: +1. Take note of the image and tag being used for the **share** service in the docker compose file you chose in the previous section. For example, if you are using 7.3.N-docker-compose.yml, you will find this on [line 102](https://github.com/Alfresco/acs-deployment/blob/master/docker-compose/7.3.N-docker-compose.yml) as follows: ```bash alfresco/alfresco-share:7.3.0 @@ -139,4 +144,7 @@ You can start your custom docker-compose.yml using the following command: docker-compose -f up ``` -Further information on starting up or troubleshooting can be found [here](../README.md) and a more advanced example of building a custom image with configuration can be found [here](https://github.com/Alfresco/acs-packaging/blob/master/docs/create-custom-image-using-existing-docker-image.md#applying-amps-that-require-additional-configuration-advanced). +Further information on starting up or troubleshooting can be found +[here](../README.md) and a more advanced example of building a custom image with +configuration can be found +[here](https://github.com/Alfresco/acs-packaging/blob/master/docs/create-custom-image-using-existing-docker-image.md). diff --git a/docs/helm-charts.md b/docs/helm-charts.md new file mode 100644 index 000000000..14585b2e5 --- /dev/null +++ b/docs/helm-charts.md @@ -0,0 +1,7 @@ +--- +title: Charts +parent: Helm +has_children: true +--- + +This section contains available documentation for charts. diff --git a/docs/helm-deployment.md b/docs/helm-deployment.md new file mode 100644 index 000000000..ce1ab366b --- /dev/null +++ b/docs/helm-deployment.md @@ -0,0 +1,7 @@ +--- +title: Deployment +parent: Helm +has_children: true +--- + +This section contains available documentation for charts deployment. diff --git a/docs/helm-examples.md b/docs/helm-examples.md new file mode 100644 index 000000000..a3ba2fb4f --- /dev/null +++ b/docs/helm-examples.md @@ -0,0 +1,7 @@ +--- +title: Examples +parent: Helm +has_children: true +--- + +This section contains available documentation for charts examples. diff --git a/docs/helm-guides.md b/docs/helm-guides.md new file mode 100644 index 000000000..d2020b854 --- /dev/null +++ b/docs/helm-guides.md @@ -0,0 +1,7 @@ +--- +title: Guides +parent: Helm +has_children: true +--- + +This section contains available documentation for charts guides. diff --git a/docs/helm.md b/docs/helm.md new file mode 100644 index 000000000..d2f581875 --- /dev/null +++ b/docs/helm.md @@ -0,0 +1,6 @@ +--- +title: Helm +has_children: true +--- + +This section contains available guides for helm deployment diff --git a/docs/helm/README.md b/docs/helm/README.md index 144996ab2..43f4ead6e 100644 --- a/docs/helm/README.md +++ b/docs/helm/README.md @@ -1,3 +1,10 @@ +--- +title: Overview +parent: Deployment +grand_parent: Helm +nav_order: 1 +--- + # Alfresco Content Services Helm Deployment Alfresco Content Services (ACS) is an Enterprise Content Management (ECM) system that is used for document and case management, project collaboration, web content publishing, and compliant records management. The flexible compute, storage, and database services that Kubernetes offers make it an ideal platform for Alfresco Content Services. This helm chart presents an enterprise-grade Alfresco Content Services configuration that you can adapt to virtually any scenario with the ability to scale up, down or out, depending on your use case. @@ -29,7 +36,7 @@ database via [Bitnami charts][bitnami-repo] and an ActiveMQ message broker with a simple [activemq subchart][activemq-readme], both with basic authentication and without any kind of redundancy. -[activemq-readme]: ../../helm/alfresco-content-services/charts/activemq/README.md +[activemq-readme]: https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/activemq/README.md [bitnami-repo]: https://github.com/bitnami/charts You typically want to disable the embedded postgres and activemq broker and @@ -63,8 +70,7 @@ the installation. ## Deploy -For the best results we recommend [deploying ACS to AWS -EKS](./eks-deployment.md). If you have a machine with at least 16GB of memory +For the best results we recommend [deploying ACS to AWS EKS](./eks-deployment.md). If you have a machine with at least 16GB of memory you can [deploy using Docker Desktop](./desktop-deployment.md) (or similar apps like Rancher and Podman Desktop) or via [KinD](kind-deployment.md) which just requires a working Docker install on any OS. @@ -72,19 +78,19 @@ requires a working Docker install on any OS. The recommended cluster resources for the Enterprise version with the components enabled by default are: at least 3 nodes with 12 cpu cores and 32 GB of memory in total. You can install with lower requirements by fine tuning the [resource requests](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) -available in the [values](../../helm/alfresco-content-services/values.yaml) for each component. +available in the [values](https://github.com/Alfresco/acs-deployment/blob/master/helm/alfresco-content-services/values.yaml) for each component. -There are also several [examples](./examples) showing how to deploy with various configurations: +There are also several [examples](../helm-examples.md) showing how to deploy with various configurations: * [Deploy with AWS Services (S3, RDS and MQ)](./examples/with-aws-services.md) * [Deploy with Intelligence Services](./examples/with-ai.md) * [Deploy with Microsoft 365 Connector (Office Online Integration)](./examples/with-ooi.md) * [Deploy with external Keycloak SSO authentication](./examples/with-keycloak.md) * [Deploy with external infrastructure components](./examples/with-external-infrastructure.md) (e.g. elasticsearch, activemq, postgres) -* [Enable access to Search Services](./examples/search-services.mdi#enable-alfresco-search-services-external-access) -* [Enable Email Services](./examples/email-enabled.md) -* [Use a custom metadata keystore](./examples/custom-metadata-keystore.md) -* [Install ACS license as part of the deployment](./examples/alf_license.md) +* [Enable access to Search Services](./examples/search-services.md#enable-alfresco-search-services-external-access) +* [Enable Email Services](https://alfresco.github.io/alfresco-helm-charts/charts/alfresco-repository/docs/email.html) +* [Use a custom metadata keystore](https://alfresco.github.io/alfresco-helm-charts/charts/alfresco-repository/docs/keystores.html) +* [Install ACS license as part of the deployment](https://alfresco.github.io/alfresco-helm-charts/charts/alfresco-repository/docs/enterprise-license.html) ## Upgrade @@ -97,13 +103,6 @@ helm charts versions. An autogenerated list of helm values used in the chart and their default values can be found here: [Alfresco Content Services Helm Chart](./../../helm/alfresco-content-services/README.md) -Since the Alfresco Content Services chart also has local chart dependencies you can find the list of values that can be configured for these charts in their respective base folder: - -* [Alfresco ActiveMQ Helm Chart](./../../helm/alfresco-content-services/charts/activemq/README.md) -* [Alfresco Search Helm Chart](./../../helm/alfresco-content-services/charts/alfresco-search/README.md) -* [Alfresco Insight Zeppelin Helm Chart](./../../helm/alfresco-content-services/charts/alfresco-search/charts/alfresco-insight-zeppelin/README.md) -* [Alfresco Sync Service Helm Chart](./../../helm/alfresco-content-services/charts/alfresco-sync-service/README.md) - ## Customise To customise the Helm deployment, for example applying AMPs, we recommend following the best practice of creating your own custom Docker image(s). The [Customisation Guide](./examples/customisation-guidelines.md) walks you through this process. @@ -112,7 +111,7 @@ To customise the Helm deployment, for example applying AMPs, we recommend follow ### Lens -The easiest way to troubleshoot issues on a Kubernetes deployment is to use the [Lens](https://k8slens.dev) desktop application, which is available for Mac, Windows and Linux. Follow the [getting started guide](https://docs.k8slens.dev/v4.0.3/getting-started) to configure your environment. +The easiest way to troubleshoot issues on a Kubernetes deployment is to use the [Lens](https://k8slens.dev) desktop application, which is available for Mac, Windows and Linux. Follow the [getting started guide](https://docs.k8slens.dev/getting-started/) to configure your environment. ![Lens Application](./images/k8s-lens.png) diff --git a/docs/helm/autoscaling.md b/docs/helm/autoscaling.md index 1729ba686..38b9ae8b3 100644 --- a/docs/helm/autoscaling.md +++ b/docs/helm/autoscaling.md @@ -1,3 +1,9 @@ +--- +title: Autoscaling +parent: Guides +grand_parent: Helm +--- + # Alfresco components auto-scaling `alfresco-content-services` can leverage Kubernetes HorinzontalPodAutoscaling diff --git a/docs/helm/desktop-deployment.md b/docs/helm/desktop-deployment.md index db6120514..5cb01b2be 100644 --- a/docs/helm/desktop-deployment.md +++ b/docs/helm/desktop-deployment.md @@ -1,3 +1,9 @@ +--- +title: Desktop +parent: Deployment +grand_parent: Helm +--- + # Alfresco Content Services Helm Deployment on local machines This page describes how to deploy Alfresco Content Services (ACS) Enterprise or @@ -7,7 +13,7 @@ Desktop](https://docs.docker.com/desktop/). ## Prerequisites -- You've read the projects [main README](/README.md#prerequisites) +- You've read the projects [main README](../index.md#prerequisites) prerequisites section - You've read the [main Helm README](./README.md) page - You are proficient in Kubernetes @@ -28,7 +34,7 @@ Then proceed to the [deployment](#deployment) section to install ingress-nginx. ### Docker Desktop specific configuration On top of the Docker desktop -[Prerequisites](./desktop-deployment.md#Prerequisites), it is essential to +[Prerequisites](./desktop-deployment.md#prerequisites), it is essential to install the latest version of [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) & [Helm](https://helm.sh/docs/intro/install). @@ -77,7 +83,7 @@ helm repo update #### Community localhost deployment To install the latest version of Community we need to download the -[community_values.yaml file](../../helm/alfresco-content-services). Once +[community_values.yaml file](https://github.com/Alfresco/acs-deployment/blob/master/helm/alfresco-content-services/community_values.yaml). Once downloaded, execute the following to initiate the deployment. ```bash @@ -93,10 +99,10 @@ helm install acs alfresco/alfresco-content-services \ #### Enterprise localhost deployment -ACS enterprise version needs to pull container images from private image repositories. -To configure credentials for accessing the Alfresco Enterprise registry, please -review the information provided in the [registry -authentication](registry-authentication.md) +ACS enterprise version needs to pull container images from private image +repositories. To configure credentials for accessing the Alfresco Enterprise +registry, please review the information provided in the +[registry-authentication](./registry-authentication.md) The Enterprise Helm deployment is intended for a Cloud based Kubernetes cluster and therefore requires a large amount of resources out-of-the-box. To reduce the @@ -129,7 +135,7 @@ The `helm` command above installs the most current released version of ACS Enter To deploy a previous version of ACS Enterprise follow the steps below. -1. Download the version specific values file you require from [this folder](../../helm/alfresco-content-services) +1. Download the version specific values file you require from [this folder](https://github.com/Alfresco/acs-deployment/tree/master/helm/alfresco-content-services) 2. Deploying the specific version of ACS can be achieved by executing the following: ```bash @@ -151,7 +157,7 @@ To deploy ACS platform with the latest development version follow the steps belo 1. Download the [pre-release_values.yaml - file](https://raw.githubusercontent.com/Alfresco/acs-deployment/master/docs/helm/values/pre-release_values.yaml) + file](https://raw.githubusercontent.com/Alfresco/acs-deployment/master/helm/alfresco-content-services/pre-release_values.yaml) 2. Deploy ACS by executing the following command: ```bash @@ -199,7 +205,7 @@ If you deployed Enterprise you'll also have access to: In the event of a deployment failure, it is important to recognize that resource constraints are a common underlying cause. For further insights and guidance. Additionally, you can find more comprehensive troubleshooting advice -in the [Helm Troubleshooting section](./README.md#Troubleshooting) +in the [Helm Troubleshooting section](./README.md#troubleshooting) ### Lack Of Resources @@ -235,6 +241,6 @@ an increased timeout, eg. --timeout 15m0s. Alteratively run without following: --atomic --timeout 10m0s ``` -and then monitor the logs for any failing pods. Please also consult the [Helm -Troubleshooting section](./README.md#Troubleshooting) for deploying Kubernetes +and then monitor the logs for any failing pods. Please also consult the +[Helm Troubleshooting section](./README.md#troubleshooting) for deploying Kubernetes Dashboard and more generic troubleshooting tips and tricks. diff --git a/docs/helm/eks-deployment.md b/docs/helm/eks-deployment.md index 295a28dda..18bf3e1a1 100644 --- a/docs/helm/eks-deployment.md +++ b/docs/helm/eks-deployment.md @@ -1,3 +1,9 @@ +--- +title: EKS +parent: Deployment +grand_parent: Helm +--- + # Alfresco Content Services Helm Deployment with AWS EKS This page describes how to deploy Alfresco Content Services (ACS) Enterprise or @@ -18,7 +24,7 @@ The Community configuration will deploy the following system: ## Prerequisites -* You've read the projects [main README](/README.md#prerequisites) +* You've read the projects [main README](../index.md#prerequisites) prerequisites section * You've read the [main Helm README](./README.md) page * You are proficient in AWS and Kubernetes @@ -54,7 +60,7 @@ Set the cluster name in an environment variable that can be reused later: EKS_CLUSTER_NAME=my-alfresco-eks ``` -Create the cluster using the latest supported version - check the main [README](../../README.md). +Create the cluster using the latest supported version - check the main [README](https://github.com/Alfresco/acs-deployment/blob/master/README.md). Most common choices for instance types are `m5.xlarge` and `t3.xlarge`: ```sh @@ -138,7 +144,7 @@ you can alternatively: ``` 4. Go to the [Security Groups section of the VPC - Console](https://console.aws.amazon.com/vpc/home#SecurityGroups) and search + Console](https://console.aws.amazon.com/vpc/home) and search for the VPC using the ID retrieved in step 2, as shown in the screenshot below: @@ -417,8 +423,7 @@ helm upgrade --install acs alfresco/alfresco-content-services \ #### Previous Enterprise Versions -Download the version-specific values file you require from the -[chart folder](../../helm/alfresco-content-services). +1. Download the version-specific values file you require from [this folder](https://github.com/Alfresco/acs-deployment/blob/master/helm/alfresco-content-services). Deploy the specific version of ACS by running the following command (replacing `YOUR-DOMAIN-NAME` with the hosted zone you created earlier and `MAJOR` & @@ -480,7 +485,7 @@ If you deployed Enterprise you'll also have access to: If you requested an extended trial license navigate to the Admin Console and apply your license: -* [https://acs.YOUR-DOMAIN-NAME/alfresco/service/enterprise/admin/admin-license](http://localhost:8080/alfresco/service/enterprise/admin/admin-license) +* `https://acs.YOUR-DOMAIN-NAME/alfresco/service/enterprise/admin/admin-license` * Default username and password is ```admin``` * See [Uploading a new license](https://docs.alfresco.com/content-services/latest/admin/license/#uploadlicense) @@ -490,7 +495,7 @@ apply your license: By default, this tutorial installs an out-of-the-box setup, however there are many configurations options described [here](./README.md#configure). There are -also several [examples](./examples) covering various use cases. +also several [examples](../helm-examples.md) covering various use cases. This deployment is also not fully secured by default, to learn about and apply further restrictions including pod security, network policies etc. please refer diff --git a/docs/helm/examples/customisation-guidelines.md b/docs/helm/examples/customisation-guidelines.md index 4186bfb8e..aae4ded00 100644 --- a/docs/helm/examples/customisation-guidelines.md +++ b/docs/helm/examples/customisation-guidelines.md @@ -1,3 +1,9 @@ +--- +title: Customisation Guidelines +parent: Examples +grand_parent: Helm +--- + # Customisation Guidelines Any customisations (including major configuration changes) should be done @@ -14,17 +20,16 @@ values files. ## Creating Custom Docker Images -The [docker compose Customisation -Guide](../../docker-compose/examples/customisation-guidelines.md) provides a +The [docker compose Customisation Guide](../../docker-compose/examples/customisation-guidelines.md) provides a detailed example of how to apply an AMP in a custom image and a more advanced example of building a custom image with configuration can be found -[here](https://github.com/Alfresco/acs-packaging/blob/master/docs/create-custom-image-using-existing-docker-image.md#applying-amps-that-require-additional-configuration-advanced). +[here](https://github.com/Alfresco/acs-packaging/blob/master/docs/create-custom-image-using-existing-docker-image.md). ## Using Custom Docker Images Once you have created your custom image you can either change the default values in the appropriate values file in [this -folder](../../../helm/alfresco-content-services) or you can override the values +folder](https://github.com/Alfresco/acs-deployment/blob/master/helm/alfresco-content-services) or you can override the values via the `--set` command line option during install as shown below: ```bash diff --git a/docs/helm/examples/external-hazelcast.md b/docs/helm/examples/external-hazelcast.md index 260d1bb11..37588d7d7 100644 --- a/docs/helm/examples/external-hazelcast.md +++ b/docs/helm/examples/external-hazelcast.md @@ -1,3 +1,9 @@ +--- +title: Hazelcast +parent: Examples +grand_parent: Helm +--- + # Alfresco Content Services Helm Deployment with external Hazelcast cluster - [Alfresco Content Services Helm Deployment with external Hazelcast @@ -26,8 +32,7 @@ ## Step by step guide -1. Deploy alfresco-content-services. See [desktop - deployment](../desktop-deployment.md) section. Remember to stick to one +1. Deploy alfresco-content-services. See [desktop deployment](../desktop-deployment.md) section. Remember to stick to one namespace in next steps. 2. Prepare a valid Hazelcast xml configuration, which also must include @@ -92,13 +97,13 @@ Now copy generated xml configuration into manifest file. (Remember to correctly indent copied text) -7. Deploy created [manifest](external-hazelcast_files/configmap-hazelcast.yaml) +7. Deploy created [manifest](https://github.com/Alfresco/acs-deployment/blob/master/docs/helm/examples/external-hazelcast_files/configmap-hazelcast.yaml) ```bash kubectl apply -f configmap-hazelcast.yaml ``` -8. Deploy hazelcast with [values](external-hazelcast_files/hazelcast.yaml) +8. Deploy hazelcast with [values](https://github.com/Alfresco/acs-deployment/blob/master/docs/helm/examples/external-hazelcast_files/hazelcast.yaml) presented below ```yaml @@ -119,7 +124,7 @@ ``` 9. Now change the config of alfresco-repository by adding another [values - file](external-hazelcast_files/acs-hazelcast.yaml). In below file specify + file](https://github.com/Alfresco/acs-deployment/blob/master/docs/helm/examples/external-hazelcast_files/acs-hazelcast.yaml). In below file specify properties that will make repository use external hazelcast cluster deployed in previous step. Remember to accordingly change the values if needed. @@ -170,8 +175,8 @@ You should get empty response. -4. Login into [Alfresco - UI](http://localhost/alfresco/s/enterprise/admin/admin-clustering) and after +4. Login into Alfresco UI on + `http://localhost/alfresco/s/enterprise/admin/admin-clustering` and after that repeat commands from previous step. You should see response from all nodes similar to this: diff --git a/docs/helm/examples/search-services.md b/docs/helm/examples/search-services.md index bb5195820..66b9e76bc 100644 --- a/docs/helm/examples/search-services.md +++ b/docs/helm/examples/search-services.md @@ -1,3 +1,9 @@ +--- +title: Search Services +parent: Examples +grand_parent: Helm +--- + # Dealing with Search service deployment Solr has some internal behavior that make it a not so great fit for orchestrated @@ -73,7 +79,7 @@ api, so it doesn't make much sense to use external access. ### Install ACS Helm Chart With Search External Access Follow the [EKS deployment](../eks-deployment.md) guide up until the -[ACS](../eks-deployment.md#acs) section, once the docker registry secret is +[ACS](../eks-deployment.md#development-version-of-charts) section, once the docker registry secret is installed come back here. Deploy the latest version of ACS Enterprise by running the command below diff --git a/docs/helm/examples/with-ai.md b/docs/helm/examples/with-ai.md index be0c0b926..4bb2669a4 100644 --- a/docs/helm/examples/with-ai.md +++ b/docs/helm/examples/with-ai.md @@ -1,3 +1,9 @@ +--- +title: Intelligence Services +parent: Examples +grand_parent: Helm +--- + # ACS Helm Deployment with Intelligence Services By default, [Alfresco Intelligence diff --git a/docs/helm/examples/with-aws-services.md b/docs/helm/examples/with-aws-services.md index e72f171ae..e2b51451a 100644 --- a/docs/helm/examples/with-aws-services.md +++ b/docs/helm/examples/with-aws-services.md @@ -1,3 +1,9 @@ +--- +title: AWS Services +parent: Examples +grand_parent: Helm +--- + # Alfresco Content Services Helm Deployment with AWS Services - [Alfresco Content Services Helm Deployment with AWS Services](#alfresco-content-services-helm-deployment-with-aws-services) @@ -21,7 +27,7 @@ The diagram below shows the deployment produced by this example: ## Prerequisites Follow the [EKS deployment](../eks-deployment.md) guide up until the -[ACS](../eks-deployment.md#acs) section, once the docker registry secret is +[ACS](../eks-deployment.md#development-version-of-charts) section, once the docker registry secret is installed return to this page. :information_source: In the EKS installation documentation mentioned above, the diff --git a/docs/helm/examples/with-external-infrastructure.md b/docs/helm/examples/with-external-infrastructure.md index b2e35bd4c..c01b8871e 100644 --- a/docs/helm/examples/with-external-infrastructure.md +++ b/docs/helm/examples/with-external-infrastructure.md @@ -1,3 +1,10 @@ +--- +title: External infrastructure +parent: Examples +grand_parent: Helm +--- + + # Alfresco Content Services Helm Deployment with external infrastructure - [Alfresco Content Services Helm Deployment with external infrastructure](#alfresco-content-services-helm-deployment-with-external-infrastructure) diff --git a/docs/helm/examples/with-keycloak.md b/docs/helm/examples/with-keycloak.md index 52abb236e..b1bc582e9 100644 --- a/docs/helm/examples/with-keycloak.md +++ b/docs/helm/examples/with-keycloak.md @@ -1,3 +1,9 @@ +--- +title: Keycloak server +parent: Examples +grand_parent: Helm +--- + # ACS Helm Deployment with an external Keycloak server In this section we are going to describe how to install Alfresco with Helm on diff --git a/docs/helm/examples/with-ms-teams.md b/docs/helm/examples/with-ms-teams.md index 7649d7a2d..5c1875265 100644 --- a/docs/helm/examples/with-ms-teams.md +++ b/docs/helm/examples/with-ms-teams.md @@ -1,3 +1,9 @@ +--- +title: Microsoft Teams Connector +parent: Examples +grand_parent: Helm +--- + # ACS Helm Deployment with Microsoft Teams Connector The [Alfresco Microsoft Teams Connector](https://docs.alfresco.com/) enables diff --git a/docs/helm/examples/with-ooi.md b/docs/helm/examples/with-ooi.md index db309ce88..731a8e49c 100644 --- a/docs/helm/examples/with-ooi.md +++ b/docs/helm/examples/with-ooi.md @@ -1,3 +1,9 @@ +--- +title: Microsoft 365 Connector +parent: Examples +grand_parent: Helm +--- + # ACS Helm Deployment with Microsoft 365 Connector The [Alfresco Microsoft 365 diff --git a/docs/helm/ingress-nginx.md b/docs/helm/ingress-nginx.md index 9d84aa95c..4467eb328 100644 --- a/docs/helm/ingress-nginx.md +++ b/docs/helm/ingress-nginx.md @@ -1,3 +1,9 @@ +--- +title: Ingress guide +parent: Guides +grand_parent: Helm +--- + # Install ingress-nginx We currently support and test only diff --git a/docs/helm/kind-deployment.md b/docs/helm/kind-deployment.md index f51efed8b..62ba37975 100644 --- a/docs/helm/kind-deployment.md +++ b/docs/helm/kind-deployment.md @@ -1,3 +1,9 @@ +--- +title: Kind +parent: Deployment +grand_parent: Helm +--- + # Alfresco Content Services Helm Deployment on KinD cluster This page describe how to get ACS up and running on a [Kubernetes In diff --git a/docs/helm/registry-authentication.md b/docs/helm/registry-authentication.md index 25c0e7257..e28557136 100644 --- a/docs/helm/registry-authentication.md +++ b/docs/helm/registry-authentication.md @@ -1,3 +1,9 @@ +--- +title: Registry authentication +parent: Guides +grand_parent: Helm +--- + # Private registry authentication For pulling images served by a registry that requires authentication, you have diff --git a/docs/helm/security.md b/docs/helm/security.md index f4889e24a..e4853bab6 100644 --- a/docs/helm/security.md +++ b/docs/helm/security.md @@ -1,3 +1,9 @@ +--- +title: Security +parent: Guides +grand_parent: Helm +--- + # Security This pages focuses on providing information on making a secure ACS installation diff --git a/docs/helm/storage.md b/docs/helm/storage.md index 56ac2b475..4e5337259 100644 --- a/docs/helm/storage.md +++ b/docs/helm/storage.md @@ -1,3 +1,9 @@ +--- +title: Storage +parent: Guides +grand_parent: Helm +--- + # ACS Storage persistence in kubernetes ACS platform in order to serve users' requests, needs to persist several type diff --git a/docs/helm/upgrades.md b/docs/helm/upgrades.md index 82e60efdf..bfa409052 100644 --- a/docs/helm/upgrades.md +++ b/docs/helm/upgrades.md @@ -1,3 +1,9 @@ +--- +title: Upgrades +parent: Guides +grand_parent: Helm +--- + # Upgrading the helm charts Our helm charts are continuously improved and sometimes arise the need to @@ -13,8 +19,7 @@ version in which they have been released. ## 8.0.0 * Search Enterprise is now the default search engine when installing Enterprise - version. For production it's suggested to use an [external elaticsearch - index](examples/with-external-infrastructure.md#elasticsearch-index). + version. For production it's suggested to use an [external elaticsearch index](examples/with-external-infrastructure.md#elasticsearch-index). ## 8.0.0-M.1 @@ -123,12 +128,12 @@ that using this values has always required and still requires using a custom image embedding the Alfresco S3 connector. Please refer to the [alfresco-repository chart -documentation](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-repository/docs/properties.md) +documentation](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-repository/docs/repository-properties.md) ### Chart modularization: Alfresco repository Repository is now deployed as part of an independent subchart. Checkout -[alfresco-repository](https://github.com/Alfresco/alfresco-helm-charts/charts/alfresco-repository/README.md) +[alfresco-repository](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-repository/README.md) for details on how to use that new chart. This `alfresco-content-services` chart is now essentially a wrapper of subcharts @@ -398,7 +403,7 @@ according to the standard [kubernetes resources management](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes). For example, in the [alfresco-content-services values -file](../../helm/alfresco-content-services/values.yaml) you can find: +file](https://github.com/Alfresco/acs-deployment/blob/master/helm/alfresco-content-services/values.yaml) you can find: ```yaml repository: diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 000000000..d246c0b86 Binary files /dev/null and b/docs/images/favicon.ico differ diff --git a/docs/images/hyland-alfresco-logos.png b/docs/images/hyland-alfresco-logos.png new file mode 100644 index 000000000..0fd08dda5 Binary files /dev/null and b/docs/images/hyland-alfresco-logos.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..efa4111d0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,124 @@ +--- +title: ACS Deployment +layout: home +nav_order: 1 +permalink: /index.html +--- +# Alfresco Content Services Containerized Deployment + +[![release](https://img.shields.io/github/v/release/Alfresco/acs-deployment?display_name=release)](https://github.com/Alfresco/acs-deployment/releases/latest) +![kubernetes tested version](https://img.shields.io/badge/k8s%20version-v1.29-blue) +[![Helm release](https://github.com/Alfresco/acs-deployment/actions/workflows/helm-release.yml/badge.svg)](https://github.com/Alfresco/acs-deployment/actions/workflows/helm-release.yml) + +[![helm charts (enterprise)](https://github.com/Alfresco/acs-deployment/actions/workflows/helm-enterprise.yml/badge.svg)](https://github.com/Alfresco/acs-deployment/actions/workflows/helm-enterprise.yml) +[![helm charts (community)](https://github.com/Alfresco/acs-deployment/actions/workflows/helm-community.yml/badge.svg)](https://github.com/Alfresco/acs-deployment/actions/workflows/helm-community.yml) + +[![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 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). + +> Automated tests for helm charts are running on KinD cluster v1.29 and EKS v1.28. + +## 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](https://github.com/Alfresco/acs-deployment/blob/master/helm/alfresco-content-services/values.yaml) +carefully and adapt any custom configuration you may have. You can read the +[upgrades guide](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 + +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 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). + +The Community Edition can be installed without the need of a license or quay.io +account. + +## Versioning + +As of version 8.0.0 of the chart we have changed the release policy. +Previously, the chart was released together with the ACS product and we were +delivering additional values files for each major release of ACS (e.g. 7.3, +7.4, ...) and chart version were bumped with a similar increment as ACS. +With version 6.0.0, we started applying major versions bumps to reflect +breaking changes in the chart, despite only minor ACS release happened. + +With 8.0.0 onward, the release pace of the chart is completely independent from +the product versions. We will also stick to Semver principles when choosing +next version number, meaning that: + +* patch version will be used for bug fixes (last digit) +* minor version will be used for new features and modifications which do not + introduce breaking changes in the configuration interface. +* major version will be used for changes which involve breaking changes in the + configuration interface. + +The `alfresco-content-services` chart has always provided the ability to deploy +any currently supported version of ACS and its components and will continue to +do so. You are encoraged to always use the latest version of the chart to +deploy your ACS version, using the appropriate values file. For that reason we +stop providing the table mapping chart versions with the ACS version they +deploy (by default). Instead we'll just maintain the list of deprecated versions +versions mapped with the latest versions of the charts we tested deployment +with, so you can use that version to deploy older ACS version on Kubernetes. +Check the [ACS End of Life'd versions](#acs-end-of-lifed-versions) paragraph. + +You are encouraged to always use the latest version of the chart to deploy your +currently supported ACS version, using the appropriate values file. + +Finally, the master branch of this repository used to contain the latest +versions, including non-released versions! +We're also moving away from this pattern and the chart will now only ever +deploy released versions of our products. + +Should you want to try our latest dev versions, we now provide an additional +values file called `pre-release_values.yaml` which will be bumped on a regular +basis. + +This also means we will not produce `-M*` versions of the chart anymore. + +Check the [Release page](https://github.com/Alfresco/acs-deployment/releases) for the list of existing versions. + +### ACS End of Life'd versions + +While our latest version of the charts should be able to deployment any version +of ACS (theoretically), we only ever test deployment of _currently_ supported +versions. Also we do not provide values files for older unsupported version. If +you need to deploy old version we provide a reference table below to allow you +find the older values files and charts. You can either try using the values +file for a version with the latest charts or using the old charts. + +| unsupported ACS version | Last chart version providing it | +|-------------------------|---------------------------------| +| 7.0 | 8.0.1 | +| 6.2 | 5.3.0 | +| 6.1 | 5.1.1 | + +> These charts should not be used for any new deployment but just for reference. + +## Getting Started + +To get started please refer to the [Docker Compose](compose.md) and [Helm Chart](helm.md) documentation. diff --git a/helm/acs-sso-example/Chart.yaml b/helm/acs-sso-example/Chart.yaml index 9fb183533..16f8f203a 100644 --- a/helm/acs-sso-example/Chart.yaml +++ b/helm/acs-sso-example/Chart.yaml @@ -10,7 +10,7 @@ description: | * Composing your ACS from individual component charts we provide. Check the [step by step documentation](./docs/step-by-step-guide.md) * SSO integration, to add keycloak and configure Alfresco applications - accordingly: [SSO guide](./docs/step-by-step-guide.md) + accordingly: [SSO guide](./docs/sso-guide.md) > Note: this chart is just an example that can run on a localhost only. > It ships ACS repo, the repository database, the message broker, the @@ -25,7 +25,7 @@ version: 0.1.0 appVersion: 23.2.0-A12 home: https://www.alfresco.com sources: - - https://github.com/Alfresco/acs-deployment/helm/acs-sso-example + - https://github.com/Alfresco/acs-deployment dependencies: - name: postgresql repository: oci://registry-1.docker.io/bitnamicharts diff --git a/helm/acs-sso-example/README.md b/helm/acs-sso-example/README.md index 32b12b905..a3e3d54c3 100644 --- a/helm/acs-sso-example/README.md +++ b/helm/acs-sso-example/README.md @@ -1,3 +1,9 @@ +--- +title: acs-sso-example +parent: Charts +grand_parent: Helm +--- + # acs-sso-example ![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 23.2.0-A12](https://img.shields.io/badge/AppVersion-23.2.0--A12-informational?style=flat-square) @@ -11,7 +17,7 @@ be enough but the principals are also documented in two differents steps: * Composing your ACS from individual component charts we provide. Check the [step by step documentation](./docs/step-by-step-guide.md) * SSO integration, to add keycloak and configure Alfresco applications - accordingly: [SSO guide](./docs/step-by-step-guide.md) + accordingly: [SSO guide](./docs/sso-guide.md) > Note: this chart is just an example that can run on a localhost only. > It ships ACS repo, the repository database, the message broker, the @@ -25,7 +31,7 @@ deployment is destroyed or rolled back! ## Source Code -* +* ## Requirements @@ -40,171 +46,17 @@ deployment is destroyed or rolled back! ## Values - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyTypeDefaultDescription
activemqobject
-check values.yaml
-
-
Configure the ACS ActiveMQ message broker as per https://github.com/Alfresco/alfresco-helm-charts/tree/activemq-3.4.1/charts/activemq
alfresco-content-appobject
-check values.yaml
-
-
Configure the Alfresco Conent-app as per https://github.com/Activiti/activiti-cloud-common-chart/tree/8.2.0/charts/common
alfresco-repositoryobject
-check values.yaml
-
-
Configure the ACS repository as per https://github.com/Alfresco/alfresco-helm-charts/tree/alfresco-repository-0.1.3/charts/alfresco-repository
alfresco-shareobject
-check values.yaml
-
-
Configure the Alfresco Share as per https://github.com/Alfresco/alfresco-helm-charts/tree/alfresco-share-0.3.0/charts/alfresco-share
global.known_urlslist
-[
-  "http://localhost"
-]
-
-
list of trusted URLs. URLs a re used to configure Cross-origin protections Also the first entry is considered the main hosting domain of the platform.
keycloakxobject
-check values.yaml
-
-
Configure the ACS Keycloak Identity provider as per https://github.com/codecentric/helm-charts/tree/keycloakx-2.3.0
keycloakx.admin.passwordstring
-random ascii string
-
-
Keycloak admin password. By default generated on first deployment, to get its value use:
kubectl get secrets keycloak -o jsonpath='{@.data.KEYCLOAK_ADMIN_PASSWORD}' | base64 -d
keycloakx.admin.realm[0]object
-{
-  "clients": [
-    {
-      "clientId": "alfresco",
-      "enabled": true,
-      "implicitFlowEnabled": true,
-      "publicClient": true,
-      "redirectUris": "{{- $redirectUris := list }} {{- range (index (include \"alfresco-common.known.urls\" $ | mustFromJson) \"known_urls\") }} {{- $redirectUris = append $redirectUris (printf \"%s/*\" .) }} {{- end }} {{- $redirectUris }}",
-      "standardFlowEnabled": true,
-      "webOrigins": "{{ index (include \"alfresco-common.known.urls\" $ | mustFromJson) \"known_urls\" }}"
-    }
-  ],
-  "defaultLocale": "en",
-  "enabled": true,
-  "id": "alfresco",
-  "internationalizationEnabled": true,
-  "loginTheme": "alfresco",
-  "realm": "alfresco",
-  "sslRequired": "none",
-  "supportedLocales": [
-    "ca",
-    "de",
-    "en",
-    "es",
-    "fr",
-    "it",
-    "ja",
-    "lt",
-    "nl",
-    "no",
-    "pt-BR",
-    "ru",
-    "sv",
-    "zh-CN"
-  ],
-  "users": [
-    {
-      "credentials": [
-        {
-          "type": "password",
-          "value": "secret"
-        }
-      ],
-      "enabled": true,
-      "username": "admin"
-    }
-  ]
-}
-
-
Alfresco Realm definition
keycloakx.admin.realm[0].users[0].credentials[0].valuestring
-"secret"
-
-
default Alfresco admin password
keycloakx.admin.realm[0].users[0].usernamestring
-"admin"
-
-
default Alfresco admin user
keycloakx.admin.usernamestring
-"admin"
-
-
Keycloak admin username
repository-databaseobject
-check values.yaml
-
-
Configure the ACS repository Postgres database as per https://github.com/bitnami/charts/tree/002c752f871c8fa068a770dc80fec4cf798798ab/bitnami/postgresql
- +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| activemq | object | check values.yaml | Configure the ACS ActiveMQ message broker as per https://github.com/Alfresco/alfresco-helm-charts/tree/activemq-3.4.1/charts/activemq | +| alfresco-content-app | object | check values.yaml | Configure the Alfresco Conent-app as per https://github.com/Activiti/activiti-cloud-common-chart/tree/8.2.0/charts/common | +| alfresco-repository | object | check values.yaml | Configure the ACS repository as per https://github.com/Alfresco/alfresco-helm-charts/tree/alfresco-repository-0.1.3/charts/alfresco-repository | +| alfresco-share | object | check values.yaml | Configure the Alfresco Share as per https://github.com/Alfresco/alfresco-helm-charts/tree/alfresco-share-0.3.0/charts/alfresco-share | +| global.known_urls | list | `["http://localhost"]` | list of trusted URLs. URLs a re used to configure Cross-origin protections Also the first entry is considered the main hosting domain of the platform. | +| keycloakx | object | check values.yaml | Configure the ACS Keycloak Identity provider as per https://github.com/codecentric/helm-charts/tree/keycloakx-2.3.0 | +| keycloakx.admin.password | string | random ascii string | Keycloak admin password. By default generated on first deployment, to get its value use:
kubectl get secrets keycloak -o jsonpath='{@.data.KEYCLOAK_ADMIN_PASSWORD}' | base64 -d | +| keycloakx.admin.realm[0] | object | `{"clients":[{"clientId":"alfresco","enabled":true,"implicitFlowEnabled":true,"publicClient":true,"redirectUris":"{{- $redirectUris := list }} {{- range (index (include \"alfresco-common.known.urls\" $ | mustFromJson) \"known_urls\") }} {{- $redirectUris = append $redirectUris (printf \"%s/*\" .) }} {{- end }} {{- $redirectUris }}","standardFlowEnabled":true,"webOrigins":"{{ index (include \"alfresco-common.known.urls\" $ | mustFromJson) \"known_urls\" }}"}],"defaultLocale":"en","enabled":true,"id":"alfresco","internationalizationEnabled":true,"loginTheme":"alfresco","realm":"alfresco","sslRequired":"none","supportedLocales":["ca","de","en","es","fr","it","ja","lt","nl","no","pt-BR","ru","sv","zh-CN"],"users":[{"credentials":[{"type":"password","value":"secret"}],"enabled":true,"username":"admin"}]}` | Alfresco Realm definition | +| keycloakx.admin.realm[0].users[0].credentials[0].value | string | `"secret"` | default Alfresco admin password | +| keycloakx.admin.realm[0].users[0].username | string | `"admin"` | default Alfresco admin user | +| keycloakx.admin.username | string | `"admin"` | Keycloak admin username | +| repository-database | object | check values.yaml | Configure the ACS repository Postgres database as per https://github.com/bitnami/charts/tree/002c752f871c8fa068a770dc80fec4cf798798ab/bitnami/postgresql | diff --git a/helm/acs-sso-example/README.md.gotmpl b/helm/acs-sso-example/README.md.gotmpl index 4ce76be30..532775f03 100644 --- a/helm/acs-sso-example/README.md.gotmpl +++ b/helm/acs-sso-example/README.md.gotmpl @@ -1,3 +1,9 @@ +--- +title: {{ template "chart.name" . }} +parent: Charts +grand_parent: Helm +--- + {{ template "chart.header" . }} {{ template "chart.deprecationWarning" . }} @@ -13,4 +19,4 @@ {{ template "chart.requirementsSection" . }} -{{ template "chart.valuesSectionHtml" . }} +{{ template "chart.valuesSection" . }} diff --git a/helm/acs-sso-example/docs/sso-guide.md b/helm/acs-sso-example/docs/sso-guide.md index dcd0d22cc..925e6b28d 100644 --- a/helm/acs-sso-example/docs/sso-guide.md +++ b/helm/acs-sso-example/docs/sso-guide.md @@ -1,7 +1,12 @@ +--- +title: SSO +parent: Examples +grand_parent: Helm +--- + # SSO integration with Keycloak (vanilla) -This is an extension of the base setup presented in the [step by step -guide](./step-by-step-guide.md). Make sure you have it running before reading +This is an extension of the base setup presented in the [step by step guide](./step-by-step-guide.md). Make sure you have it running before reading further (unless you just want to look at how to integrate Keycloak with ACS component without trying it on your local machine). diff --git a/helm/acs-sso-example/docs/step-by-step-guide.md b/helm/acs-sso-example/docs/step-by-step-guide.md index 936948936..1fc3c09ea 100644 --- a/helm/acs-sso-example/docs/step-by-step-guide.md +++ b/helm/acs-sso-example/docs/step-by-step-guide.md @@ -1,3 +1,9 @@ +--- +title: Step by step +parent: Guides +grand_parent: Helm +--- + # Anatomy of the example chart (and how you can build your own) This document explains the mechanisms used in this chart to build a Alfresco @@ -5,7 +11,7 @@ platform to deploy on [Kubernetes](https://kubernetes.io/). ## Why an example charts when there is already the alfresco-content-services? -With [alfresco-content-services chart](../../alfrescocontent-services/) we +With [alfresco-content-services chart](../../alfresco-content-services/README.md) we tried to provide something that can deploy most of our software components - still not all of them are included - but also serves as a basis for customization for real world scenarios. These two paradigms have actually @@ -18,7 +24,7 @@ including third party ones (database, message broker, Identity provider, ...). For that reason we have started creating individual charts for Alfresco components in the [alfresco-helm-charts -repository](https://github.com/Alfresco/alfreso-helm-charts/charts/) (more to +repository](https://github.com/Alfresco/alfresco-helm-charts/tree/main/charts) (more to come and PR are welcome). ## High overview of the example chart @@ -311,7 +317,7 @@ approach we prefer using to configure Alfresco component charts. #### Configuring the repository subchart The [Alfresco repository chart -documentation](ihttps://github.com/Alfresco/alfresco-helm-charts/tree/main/charts/alfresco-repository) +documentation](https://github.com/Alfresco/alfresco-helm-charts/tree/main/charts/alfresco-repository) shows how to configure the repo db and message broker using configmaps and secrets: ```yaml @@ -407,7 +413,7 @@ Now we can create configmaps to compute the services URL: The URL is built dynamically using string concatenation and the very same [named template](https://helm.sh/docs/chart_template_guide/named_templates/) that's used in the postgresql subchart to define the postgresql service name: see the -[code](https://github.com/bitnami/charts/blob/fc36e80c9ae42fd6a423a567c7fa1f6dab44ffd3/bitnami/postgresql/templates/primary/svc.yaml#L9). +[code](https://github.com/bitnami/charts/blob/fc36e80c9ae42fd6a423a567c7fa1f6dab44ffd3/bitnami/postgresql/templates/primary/svc.yaml). > Note we are building a `$dbCtx` to mimic the context the subchart uses when > evaluating `postgresql.v1.primary.fullname`. This is where it's important to @@ -455,7 +461,7 @@ helm dep build # pull dependencies helm install --generate-name --atomic . ``` -You can now open your browser on [http://localhost/alfresco](http://localhost/alfresco) +You can now open your browser on `http://localhost/alfresco` ## Next steps diff --git a/helm/alfresco-content-services/README.md b/helm/alfresco-content-services/README.md index 240ada0fe..d31db3720 100644 --- a/helm/alfresco-content-services/README.md +++ b/helm/alfresco-content-services/README.md @@ -1,3 +1,9 @@ +--- +title: alfresco-content-services +parent: Charts +grand_parent: Helm +--- + # alfresco-content-services ![Version: 8.1.1](https://img.shields.io/badge/Version-8.1.1-informational?style=flat-square) ![AppVersion: 23.2.1](https://img.shields.io/badge/AppVersion-23.2.1-informational?style=flat-square) diff --git a/helm/alfresco-content-services/README.md.gotmpl b/helm/alfresco-content-services/README.md.gotmpl index 82698597d..1d5d3c9f7 100644 --- a/helm/alfresco-content-services/README.md.gotmpl +++ b/helm/alfresco-content-services/README.md.gotmpl @@ -1,3 +1,9 @@ +--- +title: {{ template "chart.name" . }} +parent: Charts +grand_parent: Helm +--- + {{ template "chart.header" . }} {{ template "chart.deprecationWarning" . }}