diff --git a/source/guides/deployment.rst b/source/guides/deployment.rst index 8d1d1200ad7..6ba2da00140 100644 --- 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 ` - Learn how to migrate from MySQL to PostgreSQL. * :doc:`Prepare your Mattermost database ` - Learn how to prepare and configure a database for Mattermost. * :doc:`Deploy on Ubuntu ` - Signed packages direct from Mattermost featuring a single command for install and upgrades. -* :ref:`Deploy using Docker ` - The fastest way to try Mattermost and a great single server installation option. +* :doc:`Deploy using Docker ` - The fastest way to try Mattermost and a great single server installation option. * :doc:`Deploy with a tarball ` - Support for any Linux distribution. * :doc:`Deploy using Omnibus ` - An entire Mattermost installation on a single server. * :doc:`Deploy using 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 new file mode 100644 index 00000000000..bf8a8aca2f4 --- /dev/null +++ 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:@:5432/mattermost?sslmode=disable&connect_timeout=10"`` replacing ``mmuser``, ````, ```` 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 index 0bfec1af776..267126f35a5 100644 --- 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 `. If you're exceeding 200 concurrent users, you'll need :doc:`a 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 new file mode 100644 index 00000000000..d51ab96fbf0 --- /dev/null +++ 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 `_ 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`` \ No newline at end of file diff --git a/source/install/common-omnibus-tip.rst b/source/install/common-omnibus-tip.rst new file mode 100644 index 00000000000..479b748de9d --- /dev/null +++ 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 ` 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 new file mode 100644 index 00000000000..ebc40ee836a --- /dev/null +++ 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 ` documentation for details on this prerequisite. diff --git a/source/install/install-docker.rst b/source/install/install-docker.rst index 91558fac037..9dad5bce00d 100644 --- 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 `__ and `Docker Compose `_ (release 1.28 or later). .. tab:: macOS - Install `Docker for Mac `_. + Follow the `Install Docker Engine on Mac `_ documentation. .. tab:: Windows 10 - Install `Docker for Windows `_. + Follow the `Install Docker Engine on Windows `_ documentation. .. tab:: Ubuntu - Follow the `Install Docker Engine on Ubuntu `_ documentation, or you can use the Docker package from the Ubuntu repositories: + Follow the `Install Docker Engine on 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 `_ documentation. -.. tab:: Fedora +.. _Deploy Mattermost on Docker: - Follow the `Install Docker Engine on 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 ` instead. -Deploy Mattermost on Docker for production use ----------------------------------------------- +Deploy Mattermost on Docker (Quick Start) +----------------------------------------- -You'll need `Docker Engine `__ and `Docker Compose `_ (release 1.28 or later). +This section provides a quick start guide for deploying Mattermost on Docker. Leveraging `Docker Compose `_, 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 ` 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=/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 `, 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 ` 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 ` 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 ` 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://: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 `, 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=/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 `__ GitHub repository is deprecated. Visit the `mattermost/docker `_ GitHub repository to access the official Docker deployment solution for Mattermost. +Visit the `mattermost/docker `_ GitHub repository to access the official Docker deployment solution for Mattermost. + +.. note:: + + The `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 `__. -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 `_ 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 `_ to install Mattermost in Preview Mode. See the :doc:`trial Mattermost using Docker ` documentation for details. \ No newline at end of file diff --git a/source/install/install-rhel.rst b/source/install/install-rhel.rst index 8e6c928d918..324cd52a2f8 100644 --- 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 index 74d80a900d4..eba2460aa52 100644 --- 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 ` 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 ` 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:: diff --git a/source/install/install-ubuntu.rst b/source/install/install-ubuntu.rst index f2ee13dfb7f..c7498345484 100644 --- a/source/install/install-ubuntu.rst +++ b/source/install/install-ubuntu.rst @@ -36,32 +36,19 @@ Install Mattermost Server on Ubuntu You can install the Mattermost Server using our ``.deb`` signed packages using the Mattermost PPA (Personal Package Archive). Using the Mattermost Personal Package Archive (PPA) not only provides the quickest way to install a Mattermost Server, but also provides automatic updates. This install method is used for both single and clustered installations. -.. tip:: - - - If you are running the Mattermost Server and database on a single system, we recommend the :doc:`Mattermost Omnibus install method ` as this greatly reduces setup and ongoing maintenance. +.. include:: common-omnibus-tip.rst + :start-after: :nosearch: - - You need a PostgreSQL database. See the :doc:`database preparation ` documentation for details on this prerequisite. +.. include:: common-postgres-database-important.rst + :start-after: :nosearch: -A Mattermost deployment includes 4 steps: `add the PPA repository <#add-the-mattermost-server-ppa-repository>`__, `install <#install>`__, `setup <#setup>`__, and `update <#updates>`__. +This Mattermost deployment includes 4 steps: `add the PPA repository <#add-the-mattermost-server-ppa-repository>`__, `install <#install>`__, `setup <#setup>`__, and `update <#updates>`__. Add the Mattermost Server PPA repository ---------------------------------------- -.. important:: - - The GPG public key has changed. You can `import the new public key `_ 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`` +.. include:: common-gpg-public-key-changed.rst + :start-after: :nosearch: In a terminal window, run the following repository setup command to add the Mattermost Server repositories: @@ -80,7 +67,7 @@ Ahead of installing the Mattermost Server, it's good practice to update all your sudo apt update -After any updates, and any system reboots, are complete, installing the Mattermost Server is now a single command: +After any updates and system reboots are complete, you can install the Mattermost Server by running: .. code-block:: sh @@ -105,11 +92,8 @@ Rename this configuration file with correct permissions: sudo install -C -m 600 -o mattermost -g mattermost /opt/mattermost/config/config.defaults.json /opt/mattermost/config/config.json -Configure the following properties in this file: - -* Set ``DriverName`` to ``"postgres"``. This is the default and recommended database for all Mattermost installations. -* Set ``DataSource`` to ``"postgres://mmuser:@:5432/mattermost?sslmode=disable&connect_timeout=10"`` replacing ``mmuser``, ````, ```` and ``mattermost`` with your database name. -* Set ``"SiteURL"``: The domain name for the Mattermost application (e.g. ``https://mattermost.example.com``). +.. include:: common-default-config-changes.rst + :start-after: :nosearch: After modifying the ``config.json`` configuration file, you can now start the Mattermost Server: @@ -132,7 +116,7 @@ When a new Mattermost version is released, run: ``sudo apt update && sudo apt up .. note:: - When you run the ``sudo apt upgrade`` command, ``mattermost-server`` will be updated along with any other packages. We strongly recommend you stop the Mattermost Server before running the ``apt`` command using ``sudo systemctl stop mattermost-server``. + When you run the ``sudo apt upgrade`` command, ``mattermost-server`` will be updated along with any other packages. We strongly recommend you stop the Mattermost Server before running the ``apt`` command using ``sudo systemctl stop mattermost``. Remove Mattermost ------------------ diff --git a/source/install/installing-mattermost-omnibus.rst b/source/install/installing-mattermost-omnibus.rst index bbc203030fc..8f2c1a936c7 100644 --- a/source/install/installing-mattermost-omnibus.rst +++ b/source/install/installing-mattermost-omnibus.rst @@ -38,26 +38,13 @@ Install Mattermost Omnibus Omnibus supports Ubuntu distributions only. -Mattermost Omnibus packages the free, unlicensed Mattermost Enterprise version of Mattermost, a PostgreSQL database, and when required, NGINX as the application proxy. A custom CLI (``mmomni``) and ansible recipes link the components together and configures them. Mattermost Omnibus is only supported on Ubuntu distributions. +Mattermost Omnibus packages together all required components: the Enterprise Edition of Mattermost (free version), PostgreSQL database, and NGINX as the application proxy. It uses a custom CLI (``mmomni``) and ansible recipes to configure and connect these components. Add the Mattermost PPA repositories ----------------------------------- -.. important:: - - The GPG public key has changed. You can `import the new public key `_ 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, 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`` +.. include:: common-gpg-public-key-changed.rst + :start-after: :nosearch: In a terminal window, run the following repository setup command: @@ -65,26 +52,37 @@ In a terminal window, run the following repository setup command: curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash -This command configures the repositories needed for a PostgreSQL database, configures an NGINX web server to act as a proxy, configures certbot to issue and renew the SSL certificate, and configures the Mattermost Omnibus repository so that you can run the install command. +This command sets up all required repositories and configures: + +- PostgreSQL database +- NGINX web server as a proxy +- Certbot for SSL certificate management +- Mattermost Omnibus repository Install Mattermost Omnibus --------------------------- -In a terminal window, run the following command to install Omnibus. +When installing Mattermost Omnibus, SSL is enabled by default to provide a secure connection between the Mattermost server and the Mattermost client. To install with SSL, run the following command: .. code-block:: sh + // Install Mattermost Omnibus with SSL enabled sudo apt install mattermost-omnibus -y -.. note:: +You're prompted to specify a domain name and email address that will be used to generate the SSL certificate, and deliver related communications. + +Just looking to try out Mattermost? Run the following command to install Omnibus without SSL: + +.. code-block:: sh - We recommend installing and configuring Omnibus with SSL enabled; however, you can run the following command to disable SSL: ``sudo MMO_HTTPS=false apt install mattermost-omnibus``. + // Install Mattermost Omnibus without SSL + sudo MMO_HTTPS=false apt install mattermost-omnibus -y -You're prompted to specify a domain name and email address to issue the certificate. This information is used to generate the certificate and deliver any related communications. After all the packages are installed, Omnibus runs ansible scripts that configure all the platform components and starts the server. +After all the packages are installed, Omnibus runs ansible scripts that configure all the platform components and starts the server. Next steps: -1. Open a browser and navigate to your Mattermost domain either by domain name (e.g. ``mymattermostserver.com``), or by the server’s IP address if you’re not using a domain name. +1. Open a browser and navigate to your Mattermost domain either by domain name (e.g. ``mymattermostserver.com``), or by the server's IP address if you're not using a domain name. 2. Create your first Mattermost user, invite more users, and explore the Mattermost platform. @@ -95,17 +93,17 @@ Configure Mattermost Omnibus Plugin uploads, local mode, and HTTPS are enabled by default. These settings are modified in the ``yaml`` file as described below. -With Mattermost Omnibus, the Mattermost ``config.json`` file isn't used because Omnibus stores configuration in the database. The Omnibus platform itself requires a configuration of its own stored in ``/etc/mattermost/mmomni.yml``. This file contains the data that Omnibus needs to configure the platform, and connect all the services together. +Unlike traditional Mattermost installations, Omnibus stores its configuration directly in a database, eliminating the need for a ``config.json`` file. However, Omnibus itself requires a configuration file located at ``/etc/mattermost/mmomni.yml`` to manage its own settings and service interconnections. -You’ll need to use ``mmctl`` to make changes to your Mattermost server configuration using ``mmctl --local config edit``. See the :ref:`mmctl ` documentation for additional command details. +To modify Mattermost server settings within an Omnibus environment (with the exception of those listed below), you'll need to utilize the ``mmctl`` command-line tool. Specifically, the ``mmctl --local config edit`` command allows you to make the necessary adjustments. For detailed instructions and options, refer to the :doc:`mmctl ` documentation. -For Omnibus to work properly, some configuration parameters must remain unchanged, such as the port that Mattermost uses to run. +Please note that certain configuration parameters, such as the Mattermost server port, must remain unchanged to ensure optimal Omnibus functionality. The following parameters must be configured directly using the ``mmomni.yml`` file: * ``db_user``: The PostgreSQL database user. This value is generated during the Omnibus installation and should not be changed. * ``db_password``: The PostgreSQL database password. This value is generated during the Omnibus installation and should not be changed. -* ``fqdn``: The domain name for the Mattermost application. This is the value you're prompted for during the install process, and it’s used to populate the ``ServiceSettings.SiteURL`` Mattermost configuration property, as well as to retrieve and configure the SSL certificate for the server. +* ``fqdn``: The domain name for the Mattermost application. This is the value you're prompted for during the install process, and it's used to populate the ``ServiceSettings.SiteURL`` Mattermost configuration property, as well as to retrieve and configure the SSL certificate for the server. * ``email``: The email address used for certificate communications. This is the value you're prompted for during the install process, and it won't used if HTTPS is disabled. * ``https``: This indicates whether the platform should be configured to use HTTPS or HTTP with values ``true`` or ``false``. The recommended way to install Mattermost is to use HTTPS, but you can disable it if necessary. * ``data_directory``: This is the directory where Mattermost stores its data. @@ -113,7 +111,7 @@ The following parameters must be configured directly using the ``mmomni.yml`` fi * ``enable_local_mode``: This setting can be ``true`` or ``false`` and is used to configure the ``ServiceSettings.EnableLocalMode`` Mattermost configuration property. * ``nginx_template``: Optional path to a custom NGINX template. -After modifying the ``mmomni.yml`` configuration file, you need to run ``mmomni reconfigure`` for Omnibus to apply the changes, and then you need to restart the Mattermost server. +After modifying the ``mmomni.yml`` configuration file, run ``mmomni reconfigure`` to apply the changes, and then restart the Mattermost server with ``systemctl restart mattermost``. Update Mattermost Omnibus ------------------------- @@ -126,12 +124,12 @@ Mattermost Omnibus is integrated with the apt package manager. When a new Matter .. note:: - When you run the ``sudo apt upgrade`` command, mattermost-server will be updated along with any other packages. Before running the ``apt`` command, we strongly recommend stopping the Mattermost server by running the command ``sudo systemctl stop mattermost-server``. + When you run the ``sudo apt upgrade`` command, Mattermost will be updated along with any other packages. Before running the ``apt`` command, we strongly recommend stopping the Mattermost server by running the command ``sudo systemctl stop mattermost``. Backup and restore ------------------ -The Mattermost Omnibus CLI tool ``mmomni`` is used for both backups and restores. Server and domain migration, as well as backup and restore, is now much easier. You can take snapshots of all content in your Mattermost server. This includes all content, users, plugins, configurations, and databases. You can restore on the same server, or move to another server at any time. +The Mattermost Omnibus CLI tool ``mmomni`` simplifies server and domain migration, as well as backup and restore. You can easily create snapshots of your entire Mattermost server, including all content, users, plugins, configurations, and databases. These snapshots can be restored to the same server or a different one. To back up the contents of your Mattermost server, run the following command: diff --git a/source/install/prepare-mattermost-database.rst b/source/install/prepare-mattermost-database.rst index 10d66909d0e..1e147e02daa 100644 --- a/source/install/prepare-mattermost-database.rst +++ b/source/install/prepare-mattermost-database.rst @@ -4,11 +4,11 @@ Prepare your Mattermost database .. include:: ../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -You need a PostgreSQL database. See the :ref:`database software ` and the `minimum supported version policy <#minimum-supported-version-policy>`__ documentation for version support details, and see the :doc:`Migrate from MySQL to PostgreSQL ` documentation to learn more about migrating from MySQL to PostgreSQL. +You need a PostgreSQL database. See the :ref:`database software ` documentation for details on database version support. Looking for information on migrating from MySQL to PostgreSQL? See the :doc:`Migrate from MySQL to PostgreSQL ` documentation for details. .. tip:: - Looking for information on working with a MySQL database? See the :doc:`prepare your Mattermost MySQL database ` documentation for details. + We recommend using a managed PostgreSQL database service, such as Amazon RDS, Google Cloud SQL, or Azure Database for PostgreSQL. Set up a PostgreSQL database ---------------------------- diff --git a/source/install/setup-mattermost-server.rst b/source/install/setup-mattermost-server.rst index d830ae5e4df..31e2f7c8d2d 100644 --- a/source/install/setup-mattermost-server.rst +++ b/source/install/setup-mattermost-server.rst @@ -11,11 +11,8 @@ We recommend taking a backup of this default config ahead of making changes: sudo cp /opt/mattermost/config/config.json /opt/mattermost/config/config.defaults.json -Configure the following properties in this file: - -* Set ``DriverName`` to ``"postgres"``. This is the default and recommended database for all Mattermost installations. -* Set ``DataSource`` to ``"postgres://mmuser:@:5432/mattermost?sslmode=disable&connect_timeout=10"`` replacing ``mmuser``, ````, ````, and ``mattermost`` with your database name. -* Set your ``"SiteURL"``: The domain name for the Mattermost application (e.g. ``https://mattermost.example.com``). +.. include:: common-default-config-changes.rst + :start-after: :nosearch: After modifying the ``config.json`` configuration file, you can now start the Mattermost server: diff --git a/source/install/troubleshooting.rst b/source/install/troubleshooting.rst index 1bedc05c57c..ea865d81149 100644 --- a/source/install/troubleshooting.rst +++ b/source/install/troubleshooting.rst @@ -25,14 +25,12 @@ Deployment troubleshooting Docker deployments ~~~~~~~~~~~~~~~~~~ -If you're deploying the Mattermost server using Docker on an M1 Mac and encountering permission issues in the Docker container, :ref:`re-create the required directories and set their permissions `, then skip the following command: +If you're deploying the Mattermost server using Docker on an M1 Mac and encountering permission issues in the Docker container, :ref:`re-create the required directories and set their permissions `, then skip the following command because it causes the deploy to stop working. .. code-block:: sh sudo chown -R 2000:2000 ./volumes/app/mattermost -On M1 systems, this permission change causes the deploy to stop working, so we recommend skipping this step altogether. - If you're experiencing issues deploying on Docker generally, ensure the docker daemon is enabled and running: .. code-block:: sh diff --git a/source/preferences/manage-your-plugin-preferences.rst b/source/preferences/manage-your-plugin-preferences.rst index 6693839bd78..76ebd3c9daa 100644 --- a/source/preferences/manage-your-plugin-preferences.rst +++ b/source/preferences/manage-your-plugin-preferences.rst @@ -14,7 +14,7 @@ Microsoft Teams plugin preferences Select **MS Teams** to connect your Mattermost and Microsoft Teams accounts, and manage notification preferences for Microsoft Teams chats and group chats. -See the :ref:`connect your account ` and :ref:`enable notifications ` documentation for details. +See the :ref:`manage notifications ` documentation for details. .. tip::