From 9bf8a5a9985f4ac8f5e1a7b74773417d10723ff2 Mon Sep 17 00:00:00 2001 From: "Carrie Warner (Mattermost)" <74422101+cwarnermm@users.noreply.github.com> Date: Tue, 18 Feb 2025 16:42:57 -0500 Subject: [PATCH] Added redirects, editorial pass --- source/conf.py | 11 ++ source/configure/calls-deployment.rst | 2 +- source/install/install-docker.rst | 37 ++++--- source/install/install-kubernetes.rst | 139 ++++++++++++++------------ 4 files changed, 104 insertions(+), 85 deletions(-) diff --git a/source/conf.py b/source/conf.py index 48b5ade0e87..4ff6732d773 100644 --- a/source/conf.py +++ b/source/conf.py @@ -2545,6 +2545,17 @@ def setup(_: Sphinx): "https://docs.mattermost.com/install/install-rhel.html#remove-mattermost", "install/install-rhel-8.html#frequently-asked-questions": "https://docs.mattermost.com/install/install-rhel.html#frequently-asked-questions", +"install/install-rhel-8.html#set-the-correct-contexts-for-opt-mattermost": + "https://docs.mattermost.com/install/install-rhel.html#set-bin-contexts-for-opt-mattermost-bin", +"install/install-kubernetes.html#install-mattermost-on-kubernetes": + "https://docs.mattermost.com/install/install-kubernetes.html#intended-outcome-and-deployment-recommendations", +"install/install-kubernetes.html#install-the-operators": + "https://docs.mattermost.com/install/install-kubernetes.html#installation-steps", +"install/install-kubernetes.html#mattermost-cloudnative-bootstrapper-sneak-peek": + "https://docs.mattermost.com/install/install-kubernetes.html", +"install/install-kubernetes.html#does-the-mattermost-operator-replace-the-mattermost-helm-chart": + "https://docs.mattermost.com/install/install-kubernetes.html#frequently-asked-questions", + # Integrations redirects. # The integrations directory and its contents have been archived in FY23 Q2 and all applicable content has been moved from docs.mm.com to developers.mm.com. diff --git a/source/configure/calls-deployment.rst b/source/configure/calls-deployment.rst index 4f59724a74c..09144dc224e 100644 --- a/source/configure/calls-deployment.rst +++ b/source/configure/calls-deployment.rst @@ -449,7 +449,7 @@ This is a sample diagram showing how the ``rtcd`` standalone service can be depl .. image:: ../images/calls-deployment-kubernetes.png :alt: A diagram of calls deployed in a Kubernetes cluster. -If Mattermost isn't deployed in a Kubernetes cluster, and you want to use this deployment type, visit the :ref:`Kubernetes operator guide `. +If Mattermost isn't deployed in a Kubernetes cluster, and you want to use this deployment type, see the :doc:`Deploy Mattermost on Kubernetes ` documentation. Helm Charts ~~~~~~~~~~~ diff --git a/source/install/install-docker.rst b/source/install/install-docker.rst index 703197b04df..b7a40c86c24 100644 --- a/source/install/install-docker.rst +++ b/source/install/install-docker.rst @@ -98,16 +98,16 @@ To deploy Mattermost on Docker: .. code-block:: sh - mkdir -p ./volumes/web/cert - cp .pem ./volumes/web/cert/cert.pem - cp .pem ./volumes/web/cert/key-no-password.pem + mkdir -p ./volumes/web/cert + cp .pem ./volumes/web/cert/cert.pem + cp .pem ./volumes/web/cert/key-no-password.pem To include the certificate and key, ensure the following lines in your ``.env`` file points to the appropriate files. .. code-block:: sh - CERT_PATH=./volumes/web/cert/cert.pem - KEY_PATH=./volumes/web/cert/key-no-password.pem + CERT_PATH=./volumes/web/cert/cert.pem + KEY_PATH=./volumes/web/cert/key-no-password.pem 6. Deploy Mattermost. @@ -176,27 +176,25 @@ The production deployment solution is designed to deploy Mattermost on Docker in - ``POSTGRES_HOST`` .. important:: - - At a minimum, you must edit the ``DOMAIN`` value in the ``.env`` file to correspond to the domain for your Mattermost server. -.. note:: - We recommend configuring the `Support Email `_ via ``MM_SUPPORTSETTINGS_SUPPORTEMAIL``. This is the email address your users will contact when they need help. + - At a minimum, you must edit the ``DOMAIN`` value in the ``.env`` file to correspond to the domain for your Mattermost server. + - We recommend configuring the `Support Email `_ via ``MM_SUPPORTSETTINGS_SUPPORTEMAIL``. This is the email address your users will contact when they need help. 3. Create the required directories and set their permissions. .. important:: - + If you're using an external storage solution, you'll need to mount the storage to the ``volumes`` directory now. .. code-block:: sh - + mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes} sudo chown -R 2000:2000 ./volumes/app/mattermost 4. Deploy Mattermost. .. code-block:: sh - + sudo docker compose -f docker-compose.yml up -d To access your new Mattermost deployment, navigate to ``http://:8065/`` in your browser. @@ -204,28 +202,27 @@ The production deployment solution is designed to deploy Mattermost on Docker in To shut down your deployment: .. code-block:: sh - + sudo docker compose -f docker-compose.yml down 5. Create your first Mattermost system admin user, :doc:`invite more users `, and explore the Mattermost platform. - -Configure SSO With GitLab (Optional) +Configure SSO with GitLab (Optional) ------------------------------------- If you want to use SSO with GitLab, and you're using a self-signed certificate, you have to add the PKI chain for your authority. This is required to avoid the ``Token request failed: certificate signed by unknown authority`` error. To add the PKI chain, uncomment this line in your ``.env`` file, and ensure it points to your ``pki_chain.pem`` file: - .. code-block:: sh +.. code-block:: sh + + #GITLAB_PKI_CHAIN_PATH=/pki_chain.pem - #GITLAB_PKI_CHAIN_PATH=/pki_chain.pem - Then uncomment this line in your ``docker-compose.yml`` file, and ensure it points to the same ``pki_chain.pem`` file: - .. code-block:: sh +.. code-block:: sh - # - ${GITLAB_PKI_CHAIN_PATH}:/etc/ssl/certs/pki_chain.pem:ro + # - ${GITLAB_PKI_CHAIN_PATH}:/etc/ssl/certs/pki_chain.pem:ro Upgrade from ``mattermost-docker`` ----------------------------------- diff --git a/source/install/install-kubernetes.rst b/source/install/install-kubernetes.rst index a4588d9bb65..c56bd6db03b 100644 --- a/source/install/install-kubernetes.rst +++ b/source/install/install-kubernetes.rst @@ -5,28 +5,33 @@ Deploy Mattermost on Kubernetes :start-after: :nosearch: -Intended Outcome and Deployment Recommendations ----------------------------------------------- +This document provides a guide to deploying Mattermost on Kubernetes using the Mattermost Kubernetes Operator. -This document provides a guide to deploying Mattermost on Kubernetes using the Mattermost Kubernetes Operator. The goal is to enable you to quickly and reliably deploy a production-ready Mattermost instance. While the operator supports a range of configurations, we strongly recommend using a cloud-native approach for production environments. This typically involves leveraging: +Intended outcome and deployment recommendations +------------------------------------------------- -* **Object Storage:** An S3-compatible object storage service, such as Amazon S3, or similar. This is ideal for storing Mattermost file uploads and attachments. While other storage solutions are possible, S3-compatible storage offers the best scalability, reliability, and cost-effectiveness in most cloud and on-premise Kubernetes deployments. -* **Managed Database:** A managed database service, such as Amazon RDS for PostgreSQL, Azure Database for PostgreSQL, or Google Cloud SQL for PostgreSQL. These services provide automated backups, high availability, and simplified database administration. -* **Ingress Controller:** An Ingress controller, such as NGINX, to route external traffic to your Mattermost instance. This is essential for enabling external access to your Mattermost deployment. +The goal of this documentation is to enable you to quickly and reliably deploy a production-ready Mattermost instance. While the operator supports a range of configurations, we strongly recommend using a cloud-native approach for production environments. This typically involves leveraging: -While this guide focuses on using external, managed services for your database and file storage, the Mattermost Operator *does* offer the flexibility to use other solutions. For example, you could choose to deploy a PostgreSQL database within your Kubernetes cluster using the CloudNative PG operator, or use a self-hosted MinIO instance for object storage. However, managing these components yourself adds complexity and is generally not recommended for production deployments unless you have specific operational requirements. This guide will primarily focus on the recommended approach of using S3-compatible storage and a managed database service. If you choose to use self-managed components, you will need to adapt the instructions accordingly. +* **Object Storage:** An S3-compatible object storage service, such as Amazon S3, or similar. This is ideal for storing Mattermost file uploads and attachments. While other storage solutions are possible, S3-compatible storage offers the best scalability, reliability, and cost-effectiveness in most cloud and on-premise Kubernetes deployments. +* **Managed Database:** A managed database service, such as Amazon RDS for PostgreSQL, Azure Database for PostgreSQL, or Google Cloud SQL for PostgreSQL. These services provide automated backups, high availability, and simplified database administration. +* **Ingress Controller:** An Ingress controller, such as NGINX, to route external traffic to your Mattermost instance. This is essential for enabling external access to your Mattermost deployment. + +While this guide focuses on using external, managed services for your database and file storage, the Mattermost Operator *does* offer the flexibility to use other solutions. For example, you could choose to deploy a PostgreSQL database within your Kubernetes cluster using the CloudNative PG operator, or use a self-hosted MinIO instance for object storage. + +However, managing these components yourself adds complexity and is generally not recommended for production deployments unless you have specific operational requirements. This guide will primarily focus on the recommended approach of using S3-compatible storage and a managed database service. If you choose to use self-managed components, you will need to adapt the instructions accordingly. Prerequisites ------------- Before you begin, ensure you have the following: -* A functioning Kubernetes cluster (see the `Kubernetes setup guide `__). Your cluster should be running a `supported Kubernetes version `__. +* A functioning Kubernetes cluster (see the `Kubernetes setup guide `__). Your cluster should be running a `supported Kubernetes version `__. * The `kubectl` command-line tool installed on your local machine (see the `kubectl installation guide `__). * A fundamental understanding of Kubernetes concepts, such as deployments, pods, and applying manifests. -* Sufficient Kubernetes resources allocated based on your expected user load. Consult the :ref:`Mattermost Kubernetes Operator documentation ` for resource requirements at different scales. +* Sufficient Kubernetes resources allocated based on your expected user load. Consult the `Mattermost Kubernetes Operator <#install-the-mattermost-operator>`__ documentation for resource requirements at different scales. .. tip:: + * If you're new to Kubernetes or prefer a managed solution, consider using a service like `Amazon EKS `_, `Azure Kubernetes Service `_, `Google Kubernetes Engine `_, or `DigitalOcean Kubernetes `_. * To customize your production deployment, refer to the :doc:`configuration settings documentation `. * If you encounter issues during deployment, consult the :ref:`deployment troubleshooting guide `. @@ -46,27 +51,27 @@ Install the Mattermost Operator The Mattermost Kubernetes Operator can be installed using Helm. -1. Install Helm (version 3.13.0 or later). See the `Helm quickstart documentation `_ for installation instructions. +1. Install Helm (version 3.13.0 or later). See the `Helm quickstart documentation `_ for installation instructions. -2. Add the Mattermost Helm repository: +2. Add the Mattermost Helm repository: .. code-block:: sh helm repo add mattermost https://helm.mattermost.com -3. Create a file named ``config.yaml`` and populate it with the contents of the `Mattermost operator values file `_. This file allows for customization of the operator. +3. Create a file named ``config.yaml`` and populate it with the contents of the `Mattermost operator values file `_. This file allows for customization of the operator. -4. Create a namespace for the Mattermost Operator: +4. Create a namespace for the Mattermost Operator: .. code-block:: sh - kubectl create ns mattermost-operator + kubectl create ns mattermost-operator -5. Install the Mattermost Operator: +5. Install the Mattermost Operator: .. code-block:: sh - helm install mattermost/mattermost-operator -n + helm install mattermost/mattermost-operator -n For example: @@ -78,15 +83,16 @@ The Mattermost Kubernetes Operator can be installed using Helm. .. code-block:: sh - helm install mattermost-operator mattermost/mattermost-operator -n mattermost-operator -f config.yaml + helm install mattermost-operator mattermost/mattermost-operator -n mattermost-operator -f config.yaml - .. tip:: - If you don't specify a version, the latest version of the Mattermost Operator will be installed. +.. tip:: + + If you don't specify a version, the latest version of the Mattermost Operator will be installed. Deploy Mattermost ----------------- -1. **(Mattermost Enterprise only)** Create a Mattermost license secret. Create a file named ``mattermost-license-secret.yaml`` with the following content, replacing ``[LICENSE_FILE_CONTENTS]`` with your actual license: +1. **(Mattermost Enterprise only)** Create a Mattermost license secret. Create a file named ``mattermost-license-secret.yaml`` with the following content, replacing ``[LICENSE_FILE_CONTENTS]`` with your actual license: .. code-block:: yaml @@ -98,43 +104,46 @@ Deploy Mattermost stringData: license: - .. note:: - A Mattermost Enterprise license is required for multi-server deployments. For single-server deployments without an Enterprise license, add ``Replicas: 1`` to the ``spec`` section in step 2. See the :doc:`high availability documentation ` for more on highly-available deployments. +.. note:: + + A Mattermost Enterprise license is required for multi-server deployments. For single-server deployments without an Enterprise license, add ``Replicas: 1`` to the ``spec`` section in step 2. See the :doc:`high availability documentation ` for more on highly-available deployments. -2. Create a Mattermost installation manifest file named ``mattermost-installation.yaml``. Use the following template, adjusting the values as needed: +2. Create a Mattermost installation manifest file named ``mattermost-installation.yaml``. Use the following template, adjusting the values as needed: .. code-block:: yaml - apiVersion: installation.mattermost.com/v1beta1 - kind: Mattermost - metadata: - name: # Example: mm-example-full - spec: - size: # Example: 5000users - ingress: - enabled: true - host: # Example: example.mattermost-example.com - annotations: - kubernetes.io/ingress.class: nginx - version: # Example: 9.3.0 - licenseSecret: "" # If you created a license secret, put the name here + apiVersion: installation.mattermost.com/v1beta1 + kind: Mattermost + metadata: + name: # Example: mm-example-full + spec: + size: # Example: 5000users + ingress: + enabled: true + host: # Example: example.mattermost-example.com + annotations: + kubernetes.io/ingress.class: nginx + version: # Example: 9.3.0 + licenseSecret: "" # If you created a license secret, put the name here + +.. note:: - .. note:: - File names in this guide are suggestions; you can use different names. + File names in this guide are suggestions; you can use different names. - Key fields in the manifest include: - * ``metadata.name``: The name of your Mattermost deployment in Kubernetes. - * ``spec.size``: The size of your installation (e.g., "100users", "1000users", etc.). - * ``spec.ingress.host``: The DNS name for your Mattermost installation. - * ``spec.version``: The Mattermost version. See the :doc:`server version archive ` for available versions. - * ``spec.licenseSecret``: The name of the Kubernetes secret containing your license (required for Enterprise). + Key fields in the manifest include: - For a full list of configurable fields, see the `example manifest `_ and the `Custom Resource Definition `_. + * ``metadata.name``: The name of your Mattermost deployment in Kubernetes. + * ``spec.size``: The size of your installation (e.g., "100users", "1000users", etc.). + * ``spec.ingress.host``: The DNS name for your Mattermost installation. + * ``spec.version``: The Mattermost version. See the :doc:`server version archive ` for available versions. + * ``spec.licenseSecret``: The name of the Kubernetes secret containing your license (required for Enterprise). -3. Create a file named ``mattermost-database-secret.yaml`` for database credentials. This secret must be in the same namespace as the Mattermost installation. + For a full list of configurable fields, see the `example manifest `_ and the `Custom Resource Definition `_. - .. code-block:: yaml +3. Create a file named ``mattermost-database-secret.yaml`` for database credentials. This secret must be in the same namespace as the Mattermost installation. + + .. code-block:: yaml apiVersion: v1 data: @@ -166,6 +175,7 @@ Create the Filestore Secret Create a file named ``mattermost-filestore-secret.yaml`` to store the credentials for your object storage service (e.g., AWS S3, MinIO). This secret must be created in the same namespace where you intend to install Mattermost. The file should contain the following YAML structure: .. code-block:: yaml + apiVersion: v1 kind: Secret metadata: @@ -182,12 +192,14 @@ Create a file named ``mattermost-filestore-secret.yaml`` to store the credential "secretkey", "Base64-encoded secret key for your storage service.", "Yes" "metadata.name", "The name of the Kubernetes secret.", "Yes" +.. important:: -**Important:** The ``accesskey`` and ``secretkey`` values must be **base64-encoded**. Do not enter the raw keys directly. Use a command-line tool or online encoder to generate the base64 strings. + The ``accesskey`` and ``secretkey`` values must be **base64-encoded**. Do not enter the raw keys directly. Use a command-line tool or online encoder to generate the base64 strings. **Example (AWS S3):** .. code-block:: yaml + apiVersion: v1 kind: Secret metadata: @@ -205,7 +217,8 @@ Now, modify the ``mattermost-installation.yaml`` file (created in step 2) to con .. tip:: Refer to the supported fields in step 2 for guidance on where to add these configurations within the YAML structure. -**Connect to the Database:** +Connect to the Database +^^^^^^^^^^^^^^^^^^^^^^^ Add the following to the ``spec`` section of your manifest: @@ -216,7 +229,8 @@ Add the following to the ``spec`` section of your manifest: external: secret: # The name of the database secret (e.g., my-postgres-connection) -**Connect to Object Storage:** +Connect to Object Storage +^^^^^^^^^^^^^^^^^^^^^^^^^ Add the following to the ``spec`` section of your manifest: @@ -229,7 +243,8 @@ Add the following to the ``spec`` section of your manifest: bucket: # The name of your storage bucket secret: # The name of the filestore secret (e.g., my-s3-credentials) -**S3-Specific Settings:** +S3-specific settings +^^^^^^^^^^^^^^^^^^^^^ If you are using Amazon S3, it's recommended to enable server-side encryption (SSE) and SSL. Add the following environment variables to the ``mattermostEnv`` section: @@ -282,19 +297,19 @@ a. Create the Mattermost Namespace: .. code-block:: sh - kubectl create ns mattermost + kubectl create ns mattermost b. Apply the License Secret (Mattermost Enterprise only): .. code-block:: sh - kubectl apply -n mattermost -f # Replace with the actual path + kubectl apply -n mattermost -f # Replace with the actual path c. Apply the Mattermost Installation Manifest: .. code-block:: sh - kubectl apply -n mattermost -f # Replace with the actual path + kubectl apply -n mattermost -f # Replace with the actual path **Monitor the Deployment:** @@ -302,7 +317,7 @@ You can track the deployment's progress using either the Kubernetes dashboard or .. code-block:: sh - kubectl -n mattermost get mm -w + kubectl -n mattermost get mm -w The Mattermost installation is complete when the Custom Resource reaches the ``stable`` state. @@ -315,25 +330,21 @@ a. Get the Ingress Address: .. code-block:: sh - kubectl -n mattermost get ingress + kubectl -n mattermost get ingress -b. Connect to Mattermost: - -Copy the address from the ``ADDRESS`` column of the ingress output. Open your web browser and navigate to this address. +b. Connect to Mattermost: Copy the address from the ``ADDRESS`` column of the ingress output. Open your web browser and navigate to this address. c. Configure DNS (Recommended): For production environments, configure your DNS to point your domain (specified in the `ingress.host` field of your manifest) to the ingress address obtained in the previous step. This is typically done through your domain registrar or cloud DNS provider (e.g., Route53 on AWS). -d. Local Testing (Optional): - -If you are testing locally and haven't configured DNS, you can use port-forwarding to access Mattermost: +d. Local Testing (Optional): If you are testing locally and haven't configured DNS, you can use port-forwarding to access Mattermost: .. code-block:: sh - kubectl -n mattermost port-forward svc/ 8065:8065 # Replace with the name of your Mattermost service + kubectl -n mattermost port-forward svc/ 8065:8065 # Replace with the name of your Mattermost service -Then, navigate to ``http://localhost:8065`` in your browser. You can determine the service name by running: `kubectl get svc -n mattermost`. + Then, navigate to ``http://localhost:8065`` in your browser. You can determine the service name by running: `kubectl get svc -n mattermost`. **Congratulations!** You have successfully deployed Mattermost on Kubernetes.