Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updated configuration in the DB to incorporate reviewer feedback. #7209

Merged
merged 2 commits into from
Jun 13, 2024
Merged

Updated configuration in the DB to incorporate reviewer feedback. #7209

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
651c703
Incorporated reviewer updates to clarify key points for success
cwarnermm Jun 13, 2024
ed2f67c
Incorporated reviewer feedback
cwarnermm Jun 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 28 additions & 31 deletions source/configure/configuration-in-your-database.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,29 @@ Store configuration in your database
.. include:: ../_static/badges/allplans-selfhosted.rst
:start-after: :nosearch:

You can use your database as the single source of truth for the active configuration of your Mattermost installation. This changes the Mattermost binary from reading the default ``config.json`` file to reading the configuration settings stored within a configuration table in the database.
You can use your database as the single source of truth for the active configuration of your Mattermost installation. This changes the Mattermost binary from reading the default ``config.json`` file to reading the configuration settings stored within a configuration table in the database. Mattermost has been running our `community server <https://community.mattermost.com>`__ on this option since the feature was released, and recommends its use for those on :doc:`High Availability deployments <../scale/high-availability-cluster>`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0/5 but mentioning it's on community feels like overkill.

Mattermost has been running our community server <https://community.mattermost.com>__ on this option since the feature was released


Mattermost has been running our `community server <https://community.mattermost.com>`__ on this option since the feature was released, and recommends its use for those on :doc:`High Availability deployments <../scale/high-availability-cluster>`.
.. tip::

The Mattermost configuration database and Mattermost application database are 2 different entities. It's possible to store Mattermost configuration in one database and Mattermost data in another database.

To do so, you must update the :ref:`Datasource <configure/environment-configuration-settings:data source>` configuration setting to a new data source name, which can be done while the application is running. Explicitly setting the ``MM_SQLSETTINGS_DATASOURCE`` environment variable to override what has been defined in the configuration, whether it's in a database, or in a file, allows the correct data source name to be passed to the Mattermost application.

Benefits to using this option:

* Conveniently manage configuration changes directly from the System Console, even in High Availability deployments and read-only containerized environments.
* Ensure all servers in a High Availability deployment have the same configuration, even when new servers are added to the cluster.
* Automatically deploy SAML certificates and keys to all servers in the cluster.

Note that once you start using configuration in the database, you shouldn't manually edit the active configuration row. You should edit or update the configuration in one of the following ways:
.. important::

Once you start using configuration in the database, you shouldn't manually edit the active configuration row. You should edit or update the configuration in one of the following ways:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This says we should never manually edit the config row, but we say that as an option below. Should we edit the row or not?

Honestly, I'd veer people away from editing it since it's so easy to put invalid json.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great point. Will remove.


* Use the System Console to make changes to the configuration.
* Use ``mmctl`` to make changes to the configuration.
* Stop any of the running mattermost-server instances and edit the active configuration row directly in the ``Configurations`` table.
* Use the System Console to make changes to the configuration.
* Use ``mmctl`` to make changes to the configuration.
* Stop any of the running mattermost-server instances and edit the active configuration row directly in the ``Configurations`` table.

The Mattermost server keeps active configuration in memory and writes new ones to the database only when there is a change. This way we avoid polling the database to process changes to the configuration. Publishing the changes to the cluster are handled by the application itself.
The Mattermost server keeps active configuration in memory and writes new ones to the database only when there is a change. This way we avoid polling the database to process changes to the configuration. Publishing the changes to the cluster are handled by the application itself.

How to migrate configuration to the database
--------------------------------------------
Expand All @@ -33,27 +39,17 @@ These instructions cover migrating the Mattermost configuration to the database
Get your database connection string
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The first step is to get your master database connection string. We recommend accessing your ``config.json`` file to make a copy of the value in ``SqlSettings.DataSource`` or your equivalent environment variable, ``MM_SQLSETTINGS_DATASOURCE``.

If ``SqlSettings.DataSource`` does not start with ``postgres://``, then you have to add this line to the beginning based on the database in use. Also, if you see ``\u0026``, replace it with ``&``.

Here is an example connection string:
The first step is to get your master database connection string. We recommend accessing your ``config.json`` file to make a copy of the value in ``SqlSettings.DataSource``, or your equivalent environment variable, ``MM_SQLSETTINGS_DATASOURCE``.

.. code-block:: text

postgres://mmuser:really_secure_password@localhost:5432/mattermost?sslmode=disable&connect_timeout=10
.. important::

**MySQL**

.. code-block:: text

mysql://mmuser:really_secure_password@tcp(127.0.0.1:3306)/mattermost?charset=utf8mb4,utf8&writeTimeout=30s

- If ``SqlSettings.DataSource`` doesn't start with ``postgres://``, you have to add it to the beginning based on the database in use. For example: ``postgres://mmuser:really_secure_password@localhost:5432/mattermost?sslmode=disable&connect_timeout=10``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

iirc it should ALWAYS start with postgres:// or mysql://

- If you see ``\u0026``, replace it with ``&``. For example: ``mysql://mmuser:really_secure_password@tcp(127.0.0.1:3306)/mattermost?charset=utf8mb4,utf8&writeTimeout=30s``

Create an environment file
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note::
.. important::

If you're running Mattermost in a High Availability cluster, this step must be done on all servers in the cluster.

Expand Down Expand Up @@ -119,17 +115,18 @@ Here's a complete ``mattermost.service`` file with the ``EnvironmentFile`` line
Migrate configuration from ``config.json``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can use the :ref:`mmctl config migrate <manage/mmctl-command-line-tool:mmctl config migrate>` command to migrate the configuration.
You can use the :ref:`mmctl config migrate <manage/mmctl-command-line-tool:mmctl config migrate>` command to migrate the configuration by running command:

.. note::

If you're using a High Availability cluster, you only need to run this on a single server in the cluster.
.. code-block: none

.. warning::

When migrating config, Mattermost will incorporate configuration from any existing ``MM_*`` environment variables set in the current shell. See :doc:`Environment Variables </configure/configuration-settings>`

As with the environment file, you'll have to escape any single quotes in the database connection string. Also, any existing SAML certificates will be migrated into the database as well so they are available for all servers in the cluster.
mmctl config migrate path/to/config.json "postgres://mmuser:mostest@localhost:5432/mattermost_test?sslmode=disable&connect_timeout=10" --local

.. important::

- If you're using a High Availability cluster, you only need to run this command on 1 server in the cluster.
- When migrating configuration, Mattermost incorporates configuration from any existing ``MM_*`` environment variables set in the current shell. See :doc:`Environment Variables </configure/configuration-settings>` documentation for details.
- As with the environment file, you'll have to escape any single quotes in the database connection string.
- Any existing SAML certificates will be migrated into the database as well so they are available for all servers in the cluster. When the certificates expire, you can upload new certificates using the System Console or mmctl, which triggers a database update. Replacing the certificate files manually requires a reload of the Mattermost server to repull the certificates.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should note that files stored for config are stored in the configurationfiles table on the database where the config is stored


When configuration in the database is enabled, any changes to the configuration are recorded to the ``Configurations`` and ``ConfigurationFiles`` tables. Furthermore, ``ClusterSettings.ReadOnlyConfig`` is ignored, enabling full use of the System Console.

Expand Down
Loading