OPSEXP-2621 Generate documentation website with jekyll (#1144)

Co-authored-by: Giovanni Toraldo <giovanni.toraldo@hyland.com>

.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

.gitignore

@@ -35,3 +35,5 @@ hs_err_pid*
 # updatecli workflow
 alfresco-updatecli
 merged.yaml
+
+_site

.markdownlint.yaml

@@ -1,3 +1,4 @@
 ---
 default: true
 MD013: false
+MD025: false

.ruby-version

@@ -0,0 +1 @@
+3.1.4

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"

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

_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"

_includes/head_custom.html

@@ -0,0 +1,3 @@
+<style>
+    @import url('https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap')
+</style>

_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;
+}

docs/compose.md

@@ -0,0 +1,6 @@
+---
+title: Docker Compose
+has_children: true
+---
+
+This section contains available guides for docker-compose deployment

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://<machine_ip>:8080/alfresco](http://localhost:8080/alfresco)
-   * Control Center: [http://<machine_ip>:8080/admin](http://localhost:8080/admin)
-   * Alfresco Digital Workspace: [http://<machine_ip>:8080/workspace](http://localhost:8080/workspace)
-   * Share: [http://<machine_ip>:8080/share](http://localhost:8080/share)
-   * Search administration: [http://<machine_ip>:8083/solr](http://localhost:8083/solr)
+   * Administration and REST APIs: `http://<machine_ip>:8080/alfresco`
+   * Control Center: `http://<machine_ip>:8080/admin`
+   * Alfresco Digital Workspace: `http://<machine_ip>:8080/workspace`
+   * Share: `http://<machine_ip>:8080/share`
+   * Search administration: `http://<machine_ip>:8083/solr`
 6. If you requested an extended trial license navigate to the Admin Console and
    apply your license:
-   * [http://<machine_ip>:8080/alfresco/service/enterprise/admin/admin-license](http://localhost:8080/alfresco/service/enterprise/admin/admin-license) (`<machine_ip>` will usually just be `localhost`)
+   * `http://<machine_ip>:8080/alfresco/service/enterprise/admin/admin-license` (`<machine_ip>` 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)