feat: Create Azure Container Offer docs

.github/workflows/cd.yml

@@ -1,30 +1,35 @@
 name: CD
+
 on:
   workflow_run:
-    workflows: ["CI"]
+    workflows: 
+      - CI
     types:
       - completed
-    branches: ["master"]
+    branches: 
+      - master
+
 permissions:
   contents: read
+
 jobs:
   s3-release-prod:
     runs-on: ubuntu-latest
     steps:
+    - name: cd/Download artifacts
+      uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+      with:
+        run-id: ${{ github.event.workflow_run.id }}
+        name: docs
+        path: build/html
+
     - name: cd/Configure AWS
-      uses: aws-actions/configure-aws-credentials@07c2f971bac433df982ccc261983ae443861db49 # v1-node16
+      uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502 # v4.0.2
       with:
         aws-region: us-east-1
         aws-access-key-id: ${{ secrets.DOCS_BUILDS_BUCKET_AWS_ACCESS_KEY_ID }}
         aws-secret-access-key: ${{ secrets.DOCS_BUILDS_BUCKET_AWS_SECRET_ACCESS_KEY }}
-    - name: cd/Download artifacts
-      uses: dawidd6/action-download-artifact@0c49384d39ceb023b8040f480a25596fd6cf441b # v2.26.0
-      with:
-        workflow: ${{ github.event.workflow_run.workflow_id }}
-        run_id: ${{ github.event.workflow_run.id }}
-        workflow_conclusion: success
-        name: docs
-        path: build/html
+
     - name: cd/Upload artifacts to S3
       run: |
-        aws s3 sync build/html s3://docs.mattermost.com/ --delete --cache-control no-cache --acl public-read --no-progress
+        aws s3 sync build/html s3://docs.mattermost.com/ --delete --cache-control no-cache --acl public-read --no-progress  

.github/workflows/ci.yml

@@ -12,23 +12,33 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ci/Checkout code
-        uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c  # v3.3.0
-      - uses: actions/setup-python@db9987b4c1f10f0404fa60ee629f675fafbd6763  # v4.6.0
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871  # v4.2.1
+
+      - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3  # v5.2.0
         with:
-          python-version: 3.9
+          python-version: 3.12
+
       - name: ci/Install dependencies
         run: make python-deps
+
       - name: ci/Run tests
-        run: TZ=UTC make test
+        env:
+          TZ: UTC
+        run: make test
+
       - name: ci/Build docs
-        run: TZ=UTC make html
+        env:
+          TZ: UTC
+        run: make html
+
       - name: ci/Persist docs artifacts
-        uses: actions/upload-artifact@65d862660abb392b8c4a3d1195a2108db131dd05  # v3.1.2
+        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882  # v4.4.3
         with:
           name: docs
           path: build/html
+
       - name: ci/Persist doc logs artifacts
-        uses: actions/upload-artifact@65d862660abb392b8c4a3d1195a2108db131dd05  # v3.1.2
+        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882  # v4.4.3
         with:
           name: doc-logs
           path: build/*.log

.github/workflows/preview-env-template.yml

@@ -26,13 +26,10 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
         with:
-          python-version: "3.9"
+          python-version: 3.12
 
-      - name: Install pipenv
-        run: pip install pipenv
-
-      - name: Install dependencies
-        run: pipenv install --dev
+      - name: ci/Install dependencies
+        run: make python-deps
 
       - name: Build
         run: make SPHINXOPTS="-j auto -D html_baseurl=http://mattermost-docs-preview-pulls.s3-website-us-east-1.amazonaws.com/${{ inputs.PR_NUMBER }}" html
@@ -42,7 +39,7 @@ jobs:
         with:
           aws_key_id: ${{ secrets.AWS_KEY_ID }}
           aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-          aws_bucket: ${{ secrets.AWS_BUCKET }}
+          aws_bucket: mattermost-docs-preview-pulls
           source_dir: ./build/html
           destination_dir: ${{ inputs.PR_NUMBER }}
 

.gitignore

@@ -4,7 +4,8 @@ logs
 node_modules
 dist
 npm-debug.log
-
+.venv
+extensions/**/__pycache__/
 web/static/js/bundle*.js
 web/static/js/libs*.js
 model/version.go

Makefile

@@ -35,8 +35,8 @@ endif
 # Install necessary dependencies for the CI build pipeline.
 # NOTE: if the version of Python used to build the docs changes, update the `pipenv` command below accordingly.
 python-deps:
-	pip install pipenv==2023.11.15
-	pipenv install --dev --clear --deploy --python 3.9
+	pip install pipenv==2024.1.0
+	pipenv install --dev --clear --deploy --python 3.12
 
 test:
 	pipenv run pytest

source/guides/deployment.rst

@@ -18,6 +18,7 @@ Learn how to install, deploy, and scale Mattermost for teams and organizations o
     Deploy with a tarball </install/install-tar>
     Deploy using Omnibus </install/installing-mattermost-omnibus>
     Deploy using Kubernetes </install/install-kubernetes>
+    Deploy Mattermost on Azure AKS </install/install-kubernetes-aks>
     Deploy on Red Hat </install/install-rhel-8>
     Set up an NGINX proxy </install/setup-nginx-proxy>
     Set up TLS </install/setup-tls>
@@ -41,6 +42,7 @@ Learn how to install, deploy, and scale Mattermost for teams and organizations o
 * :doc:`Deploy with a tarball </install/install-tar>` - Support for any Linux distribution.
 * :doc:`Deploy using Omnibus </install/installing-mattermost-omnibus>` - An entire Mattermost installation on a single server.
 * :doc:`Deploy using Kubernetes </install/install-kubernetes>` - Install using the Mattermost Helm Chart or Operator and simplified updates.
+* :doc:`Deploy Mattermost on Azure AKS </install/install-kubernetes-aks>` - Deploy Mattermost on Azure AKS.
 * :doc:`Deploy on Red Hat </install/install-rhel-8>` - Support for all current Red Hat Enterprise Linux platforms with a tarball.
 * :doc:`Set up NGINX proxy </install/setup-nginx-proxy>` - Learn how to configure Mattermost for HTTPS for deployments of more than 200 users.
 * :doc:`Set up TLS </install/setup-tls>` - Learn how to configure Mattermost for HTTPS for deployments of fewer than 200 concurrent users.

source/install/install-kubernetes-aks.rst

@@ -0,0 +1,114 @@
+Install Mattermost on Azure AKS
+================================
+
+.. include:: ../_static/badges/allplans-selfhosted.rst
+  :start-after: :nosearch:
+
+You can use a supported `Azure Marketplace Container Offer <https://azuremarketplace.microsoft.com/en-us/marketplace/apps/mattermost.mattermost-operator>`__ to install Mattermost on your existing Azure infrastructure.
+
+Infrastructure pre-requisites
+-----------------------------
+
+Deploying Mattermost on Azure AKS requires the following database and cluster prerequisites.
+
+PostgreSQL v13.0+ database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mattermost requires a pre-existing PostgreSQL database within your infrastructure. We recommend using `Azure Database for PostgreSQL - Flexible Server <https://learn.microsoft.com/en-us/azure/postgresql/>`_. Deploy one by following `this Microsoft quick start guide <https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/quickstart-create-server-portal>`_.
+
+.. tip::
+  We recommend using Private Access for your database.
+
+Running AKS cluster
+~~~~~~~~~~~~~~~~~~~
+
+Mattermost Azure Container Offer requires a pre-existing Kubernetes Cluster with an Ingress Controller pre-installed. We recommend creating a new AKS cluster with the `AGIC add-on enabled <https://learn.microsoft.com/en-us/azure/application-gateway/ingress-controller-overview>`_. 
+
+Follow `this tutorial <https://learn.microsoft.com/en-us/azure/application-gateway/tutorial-ingress-controller-add-on-new>`_ to create a new AKS cluster with the add-on enabled.
+
+.. tip::
+
+  - Connectivity should be already in place between the AKS cluster and the PostgreSQL database.
+  - Any pre-installed Ingress Controller within the cluster that supports the Ingress Kubernetes resource and TLS termination should work out of the box.
+
+Deployment pre-requisites
+-------------------------
+
+Deploying Mattermost on Azure AKS requires the following deployment prerequisites.
+
+Valid DNS name and TLS certificates 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mattermost relies on strong TLS certification in order to provide all the features to users. You need to have access to a DNS zone and be able to provide a valid TLS key and certificate for the Ingress Controller.
+
+Mattermost License and AKS Capacity  
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: ../_static/badges/ent-only.rst
+  :start-after: :nosearch:
+
+If your deployment option is for more than ``100 users``, you must have more than 2 nodes on your AKS cluster to support High Availability, and you must provide a valid Mattermost License file.
+
+.. note:: 
+
+  Providing a license is optional at this stage. You can enable a **30 day** Mattermost trial once the server is deployed.
+
+Deploy Mattermost
+-----------------
+
+1. Navigate to our `Azure Marketplace Container Offer <https://azuremarketplace.microsoft.com/en-us/marketplace/apps/mattermost.mattermost-operator>`_ and get the offer.
+
+  Alternatively, you can go to the ``Extensions + Applications`` section of your AKS cluster and install the Mattermost offering from there. Visit the `Microsoft cluster extensions documentation <https://learn.microsoft.com/en-gb/azure/aks/cluster-extensions?tabs=azure-cli>`_ to learn more.
+
+2. Choose the **Resource Group** and the **Region** of your installed AKS and PostgreSQL database.
+
+    .. image:: ../_static/images/azure/basics.png
+      :alt: An example of the Azure AKS Project details screen.
+
+3. Choose your AKS cluster.
+
+    .. image:: ../_static/images/azure/aks-cluster.png
+      :alt: An example of the Azure AKS cluster setup screen.
+
+4. Fill in the details for your PostgreSQL database.
+
+    .. image:: ../_static/images/azure/postgreSQL.png
+      :alt: An example of the Azure AKS Database setup screen.
+
+    .. note::
+
+      - Connectivity should be already in place between the AKS cluster and the database.
+      - Database should already exist and the user specified must have full access.
+
+5. Adjust deployment details.
+
+    .. image:: ../_static/images/azure/deployment-details.png
+      :alt: An example of the Azure AKS Deployment Details setup screen.
+
+.. note:: 
+  You can define a Deployment size to automatically adjust the installation. A valid Mattermost license is required for deployments of more than 100 users.
+
+6. Configure Mattermost installation hostname and Ingress details. The AGIC add-on is used in the following example to show the ingress annotations required.
+
+    .. code-block:: yaml
+
+      kubernetes.io/ingress.class: azure/application-gateway
+      appgw.ingress.kubernetes.io/ssl-redirect: "true"
+
+Upload yor own TLS certificates at this stage to take advantage of all Mattermost features.
+
+    .. image:: ../_static/images/azure/networking-details.png
+      :alt: An example of the Azure AKS Networking Details setup screen.
+
+7. Ensure that everything is running. You should be able to check the installed plugin from the **AKS Extensions + Applications** page under the **Settings** menu.
+
+  a. When the deployment is complete, obtain the hostname or IP address of your Mattermost deployment using the following command:
+
+    .. code-block:: sh
+
+      kubectl -n mattermost-operator get ingress
+
+  b. Get the resulting IP address from the ``ADDRESS`` column, and use your domain registration service to create a DNS record.
+  c. You should be good to go.
+
+Learn more about managing your Mattermost server by visiting the :doc:`Managing Mattermost </guides/self-hosted-administration>` documentation.