mattermost · nickmisasi · Jan 30, 2025 · Feb 6, 2025 · Feb 6, 2025 · Feb 6, 2025
diff --git a/source/guides/deployment.rst b/source/guides/deployment.rst
@@ -40,7 +40,7 @@ Learn how to install, deploy, and scale Mattermost for teams and organizations o
 * :doc:`Migrate from MySQL to PostgreSQL </deploy/postgres-migration>` - Learn how to migrate from MySQL to PostgreSQL. 
 * :doc:`Prepare your Mattermost database </install/prepare-mattermost-database>` - Learn how to prepare and configure a database for Mattermost.
 * :doc:`Deploy on Ubuntu </install/install-ubuntu>` - Signed packages direct from Mattermost featuring a single command for install and upgrades.
-* :ref:`Deploy using Docker <install/install-docker:deploy mattermost on docker for production use>` - The fastest way to try Mattermost and a great single server installation option.
+* :doc:`Deploy using Docker </install/install-docker>` - The fastest way to try Mattermost and a great single server installation option.
 * :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.

diff --git a/source/install/common-default-config-changes.rst b/source/install/common-default-config-changes.rst
@@ -0,0 +1,8 @@
+:orphan:
+:nosearch:
+
+Configure the following properties in this file:
+
+* Under ``SqlSettings``, set ``DriverName`` to ``"postgres"``. This is the default and recommended database for all Mattermost installations.
+* Under ``SqlSettings``, set ``DataSource`` to ``"postgres://mmuser:<mmuser-password>@<host-name-or-IP>:5432/mattermost?sslmode=disable&connect_timeout=10"`` replacing ``mmuser``, ``<mmuser-password>``, ``<host-name-or-IP>`` and ``mattermost`` with your database name.
+* Under ``ServiceSettings``, set ``"SiteURL"``: The domain name for the Mattermost application (e.g. ``https://mattermost.example.com``).
diff --git a/source/install/common-deploy-faq.rst b/source/install/common-deploy-faq.rst
@@ -6,7 +6,7 @@
 Why doesn't Mattermost start at system boot?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To have the Mattermost Server start at system boot, the systemd until file needs to be enabled. Run the following command:
+To have the Mattermost Server start at system boot, the systemd unit file needs to be enabled. Run the following command:
 
 .. code-block:: sh
 
@@ -29,3 +29,9 @@ Yes. Mattermost binds to 443 instead of 8065. The Mattermost binary requires the
 .. note::
 
   - We highly recommend using a proxy in front of Mattermost server for up to 200 concurrent users. If you have fewer than 200 concurrent users, you can :doc:`set up TLS </install/setup-tls>`. If you're exceeding 200 concurrent users, you'll need :doc:`a proxy </install/setup-nginx-proxy>`, such as NGINX, in front of Mattermost to manage the traffic.
+
+Where can I access Mattermost Server logs?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mattermost Server logs are located in the ``logs`` directory of wherever you installed Mattermost. By default, this is ``/opt/mattermost/logs``, inside the ``mattermost.log`` file.
+
diff --git a/source/install/common-gpg-public-key-changed.rst b/source/install/common-gpg-public-key-changed.rst
@@ -0,0 +1,18 @@
+:orphan:
+:nosearch:
+
+.. important::
+
+  The GPG public key has changed. You can `import the new public key <https://deb.packages.mattermost.com/pubkey.gpg>`_ or run the automatic Mattermost PPA repository setup script provided below. Depending on your setup, additional steps may also be required, particularly for installations that didn't rely on the repository setup script. We recommend deleting the old key from ``/etc/apt/trusted.gpg.d`` before adding the apt repository.
+
+  - For Ubuntu Focal - 20.04 LTS:
+
+    ``sudo apt-key del A1B31D46F0F3A10B02CF2D44F8F2C31744774B28``
+
+    ``curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg | gpg --dearmor | sudo apt-key add``
+
+  - For Ubuntu Jammy - 22.04 LTS and Ubuntu Noble - 24.04 LTS:
+
+    ``sudo rm /usr/share/keyrings/mattermost-archive-keyring.gpg``
+
+    ``curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg |  gpg --dearmor | sudo tee /usr/share/keyrings/mattermost-archive-keyring.gpg > /dev/null``
diff --git a/source/install/common-omnibus-tip.rst b/source/install/common-omnibus-tip.rst
@@ -0,0 +1,7 @@
+:orphan:
+:nosearch:
+
+.. tip::
+
+  If you are running the Mattermost Server and database on a single system, we recommend the :doc:`Mattermost Omnibus install method </install/installing-mattermost-omnibus>` as this greatly reduces setup and ongoing maintenance.
+
diff --git a/source/install/common-postgres-database-important.rst b/source/install/common-postgres-database-important.rst
@@ -0,0 +1,6 @@
+:orphan:
+:nosearch:
+
+.. important::
+
+  You need a PostgreSQL database. See the :doc:`database preparation </install/prepare-mattermost-database>` documentation for details on this prerequisite.
diff --git a/source/install/install-docker.rst b/source/install/install-docker.rst
@@ -7,45 +7,47 @@ Deploy Mattermost via Docker
 Install Docker
 ---------------
 
-If you don't have Docker installed, follow the instructions below based on your operating system:
+If you don't have Docker installed, follow the instructions below based on your operating system. You'll need `Docker Engine <https://docs.docker.com/engine/install/>`__ and `Docker Compose <https://docs.docker.com/compose/install/>`_ (release 1.28 or later).
 
 .. tab:: macOS
 
-  Install `Docker for Mac <https://docs.docker.com/desktop/setup/install/mac-install/>`_.
+  Follow the `Install Docker Engine on Mac <https://docs.docker.com/desktop/setup/install/mac-install/>`_ documentation.
 
 .. tab:: Windows 10
 
-  Install `Docker for Windows <https://docs.docker.com/desktop/setup/install/windows-install/>`_.
+  Follow the `Install Docker Engine on Windows <https://docs.docker.com/desktop/setup/install/windows-install/>`_ documentation.
 
 .. tab:: Ubuntu
 
-  Follow the `Install Docker Engine on Ubuntu <https://docs.docker.com/engine/install/ubuntu/>`_ documentation, or you can use the Docker package from the Ubuntu repositories:
+  Follow the `Install Docker Engine on Ubuntu <https://docs.docker.com/engine/install/ubuntu/>`_ documentation.
 
-  .. code-block:: sh
+.. tab:: Fedora
 
-    sudo apt update
-    sudo apt install docker.io
-    sudo systemctl start docker
+  Follow the `Install Docker Engine on Fedora <https://docs.docker.com/engine/install/fedora/>`_ documentation.
 
-.. tab:: Fedora
+.. _Deploy Mattermost on Docker:
 
-  Follow the `Install Docker Engine on Fedora <https://docs.docker.com/engine/install/fedora/>`_ documentation, or you can use the Moby package (Moby is the FOSS upstream project to Docker) from the Fedora repositories:
+Before you begin
+----------------
 
-  .. code-block:: sh
+Mattermost's Docker deployment solution is one of the best ways to get started with Mattermost. Before you get begin, think about what type of Mattermost deployment you want to create as the instructions below are designed for different use cases.
 
-    sudo dnf install moby-engine
-    sudo systemctl start docker
+- If you're looking to try out Mattermost, see the `Docker (Quick Start) <#deploy-mattermost-on-docker-quick-start>`__ section below.
+- If you're looking to deploy Mattermost on Docker in production, see the `Docker for production use <#deploy-mattermost-on-docker-for-production-use>`__ section below.
 
-.. _Deploy Mattermost on Docker:
+.. note::
+
+   Intending to deploy a production Mattermost instance for more than 100 users? Consider :doc:`deploying Mattermost on Kubernetes </install/install-kubernetes>` instead.
 
-Deploy Mattermost on Docker for production use
-----------------------------------------------
+Deploy Mattermost on Docker (Quick Start)
+-----------------------------------------
 
-You'll need `Docker Engine <https://docs.docker.com/engine/install/>`__ and `Docker Compose <https://docs.docker.com/compose/install/>`_ (release 1.28 or later).
+This section provides a quick start guide for deploying Mattermost on Docker. Leveraging `Docker Compose <https://docs.docker.com/compose/install/>`_, this deployment solution is designed to get Mattermost up and running quickly. 
 
 .. important::
 
-   - The production configuration results in two separate containers: one for the database and one for the application. An optional third container results when using NGINX for reverse proxy.
+   - This deployment solution is not recommended for production use. See the `Docker for production use <#deploy-mattermost-on-docker-for-production-use>`__ section instead.
+   - The quick-start configuration results in two separate containers: a container for the database and a container for the application. An optional third container results when using NGINX for reverse proxy.
    - Encountering issues with your Docker deployment? See the :ref:`Docker deployment troubleshooting <install/troubleshooting:docker deployments>` documentation for details.
 
 To deploy Mattermost on Docker:
@@ -74,7 +76,7 @@ To deploy Mattermost on Docker:
       mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}
       sudo chown -R 2000:2000 ./volumes/app/mattermost
 
-4. Configure TLS for NGINX *(optional)*. If you're not using the included NGINX reverse proxy, you can skip this step.
+4. *(Optional)* Configure TLS for NGINX. If you're not using the included NGINX reverse proxy, you can skip this step.
 
    **If creating a new certificate and key:**
 
@@ -104,20 +106,6 @@ To deploy Mattermost on Docker:
             CERT_PATH=./volumes/web/cert/cert.pem
             KEY_PATH=./volumes/web/cert/key-no-password.pem
 
-5. 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
-
-      #GITLAB_PKI_CHAIN_PATH=<path_to_your_gitlab_pki>/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
-
-      # - ${GITLAB_PKI_CHAIN_PATH}:/etc/ssl/certs/pki_chain.pem:ro
-
 6. Deploy Mattermost.
 
    **Without using the included NGINX:**
@@ -150,16 +138,103 @@ To deploy Mattermost on Docker:
 
 7. Create your first Mattermost system admin user, :doc:`invite more users </collaborate/manage-channel-members>`, and explore the Mattermost platform. 
 
+Deploy Mattermost on Docker (Production)
+-----------------------------------------
+
+The production deployment solution is designed to deploy Mattermost on Docker in a production environment. This deployment solution only deploys a single application container for Mattermost, and expects an external database and reverse proxy.
+
+.. important::
+
+   - Mattermost recommends the use of an external, managed PostgreSQL database like AWS RDS, Google Cloud SQL, or Azure Database for production deployments. See the :doc:`Database preparation </install/prepare-mattermost-database>` documentation for details.
+   - Mattermost recommends the use of an external storage solution like AWS S3, Google Cloud Storage, or Azure Blob Storage for production deployments.
+   - Mattermost recommends the use of an external reverse proxy for production deployments.
+   - Encountering issues with your Docker deployment? See the :ref:`Docker deployment troubleshooting <install/troubleshooting:docker deployments>` documentation for details.
+
+1. In a terminal window, clone the repository and enter the directory.
+
+   .. code-block:: sh
+
+      git clone https://github.com/mattermost/docker
+      cd docker
+
+2. Create your ``.env`` file by copying and adjusting the ``env.example`` file.
+
+   .. code-block:: sh
+
+      cp env.example .env
+
+   If you're using an external database as is recommended for production deployments, ensure you've followed the :doc:`database preparation </install/prepare-mattermost-database>` documentation. When completed you'll need to set the following environment variables in your ``.env`` file: 
+
+   - ``POSTGRES_USER``
+   - ``POSTGRES_PASSWORD``
+   - ``POSTGRES_HOST``
+   - ``POSTGRES_PORT``
+   - ``POSTGRES_DB``
+   - ``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.
+
+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://<YOUR_MM_DOMAIN>:8065/`` in your browser.
+
+   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 </collaborate/manage-channel-members>`, and explore the Mattermost platform. 
+
+
+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
+
+      #GITLAB_PKI_CHAIN_PATH=<path_to_your_gitlab_pki>/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
+
+      # - ${GITLAB_PKI_CHAIN_PATH}:/etc/ssl/certs/pki_chain.pem:ro
+
 Upgrade from ``mattermost-docker``
 -----------------------------------
 
-The `mattermost-docker <https://github.com/mattermost/mattermost-docker>`__ GitHub repository is deprecated. Visit the `mattermost/docker <https://github.com/mattermost/docker>`_ GitHub repository to access the official Docker deployment solution for Mattermost.
+Visit the `mattermost/docker <https://github.com/mattermost/docker>`_ GitHub repository to access the official Docker deployment solution for Mattermost.
+
+.. note::
+
+   The `mattermost-docker <https://github.com/mattermost/mattermost-docker>`__ GitHub repository is deprecated. 
 
 To migrate from an existing ``mattermost/mattermost-prod-app`` image, we recommend migrating to either ``mattermost/mattermost-enterprise-edition`` or ``mattermost/mattermost-team-edition`` images, which are the official images supported by Mattermost. These images support PostgreSQL 11+ databases, which we know has been a long-running challenge for the community, and you will not lose any features or functionality by moving to these new images.
 
 For additional help or questions, please refer to `this issue <https://github.com/mattermost/mattermost-docker/issues/489>`__.
 
-Installing a different version of Mattermost
+Install a different version of Mattermost
 --------------------------------------------
 
 1. Shut down your deployment.
@@ -197,7 +272,7 @@ To remove all data and settings for your Mattermost deployment:
 PostgreSQL
 ~~~~~~~~~~~
 
-You can change the Postgres username and/or password (recommended) in the ``.env`` file.
+For quick start deployments, you can change the Postgres username and/or password (recommended) in the ``.env`` file. If your database is managed externally, you'll need to change the password in your database management tool. Then, update the ``.env`` file with the new credentials.
 
 TLS & NGINX
 ~~~~~~~~~~~~
@@ -212,6 +287,6 @@ If you encounter other problems while installing Mattermost, please refer to our
 Trial Mattermost using Docker Preview
 --------------------------------------
 
-Looking to a way to evaluate Mattermost in a non-production environment using Docker? We recommend using the `Mattermost Docker Preview Image <https://github.com/mattermost/mattermost-docker-preview>`_ to install Mattermost in Preview Mode. 
+Looking for a way to evaluate Mattermost in a non-production environment using Docker? We recommend using the `Mattermost Docker Preview Image <https://github.com/mattermost/mattermost-docker-preview>`_ to install Mattermost in Preview Mode. 
 
 See the :doc:`trial Mattermost using Docker </install/trial-mattermost-using-docker>` documentation for details.
diff --git a/source/install/install-rhel.rst b/source/install/install-rhel.rst
@@ -66,6 +66,9 @@ Setup
 
 .. include:: setup-mattermost-server.rst
     :start-after: :nosearch:
+
+.. important::
+  If you don't receive an error when starting Mattermost after the previous step, you are good to go. If you did receive an error, continue on
 
 Modify SELinux settings
 -----------------------
@@ -74,7 +77,28 @@ When deploying Mattermost from RHEL9, which has SELinux running with enforceing
 
 First, ensure that SELinux is enabled and in enforcing mode by running the ``sestatus`` command. If it's ``enforcing``, you'll need to configure it properly.
 
-Set the correct contexts for ``/opt/mattermost``
+Set bin contexts for ``/opt/mattermost/bin``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SELinux enforces security contexts for binaries. To label the Mattermost binaries as safe, you'll need to set them to the below SELinux context.
+
+.. code-block:: sh
+
+  sudo semanage fcontext -a -t bin_t "/opt/mattermost/bin(/.*)?"
+  sudo restorecon -RF /opt/mattermost/bin
+
+Now, try starting Mattermost again with 
+
+.. code-block:: sh
+
+  sudo systemctl start mattermost
+
+If you don't receive an error, verify that Mattermost is running: curl ``http://localhost:8065``. You should see the HTML that's returned by the Mattermost Server. You're all set!
+
+.. important::
+  If on starting Mattermost you receive an error, before moving on, check for the existence of a file in ``/opt/mattermost/logs`` - if ``mattermost.log`` exists in that directory, it's more likely you're dealing with a configuration issue in  ``config.json``. Double check the previous steps before continuing
+
+Try different contexts for ``/opt/mattermost``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 SELinux enforces security contexts for files and directories. To label your Mattermost directory as safe, you'll need to set an appropriate SELinux context.

diff --git a/source/install/install-tar.rst b/source/install/install-tar.rst
@@ -38,15 +38,13 @@ You can install the Mattermost Server on any 64-bit Linux system using the tarba
 .. include:: ../_static/badges/academy-tarball-deployment.rst
   :start-after: :nosearch:
 
-.. tip::
-
-  If you are running the Mattermost Server and database on a single system, we recommend the :doc:`Mattermost Omnibus install method </install/installing-mattermost-omnibus>` as this greatly reduces setup and ongoing maintenance, and uses the Mattermost PPA for updates. More modern installation methods such as the Mattermost Helm Chart or Kubernetes Operator are available and are highly recommended.
-
-.. note::
+.. include:: common-omnibus-tip.rst
+  :start-after: :nosearch:
 
-  You need a PostgreSQL database. See the :doc:`database preparation </install/prepare-mattermost-database>` documentation for details on this prerequisite.
+.. include:: common-postgres-database-important.rst
+  :start-after: :nosearch:
 
-A Mattermost deployment includes 3 steps: `download <#download>`__, `install <#install>`__, and `setup <#setup>`__.
+This Mattermost deployment includes 3 steps: `download <#download>`__, `install <#install>`__, and `setup <#setup>`__.
 
 Download
 --------
@@ -78,7 +76,7 @@ If you wish to remove the Mattermost Server for any reason, you must stop the Ma
 
 .. code-block:: sh
 
-   sudo rm /opt/mattermost
+   sudo rm - rf /opt/mattermost
 
 .. note::