Skip to content

AI-Aided: Add v10.10+ deployment and upgrade documentation #8091

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

Open
wants to merge 1 commit into
base: v10.10-documentation
Choose a base branch
from
Open

AI-Aided: Add v10.10+ deployment and upgrade documentation #8091

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
33 changes: 33 additions & 0 deletions source/deploy/server/server-deployment-planning.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,37 @@ When planning your Mattermost deployment, consider the following when choosing t

The following server, desktop, and mobile application sections provide detailed instructions for each deployment approach.

v10.10+ deployment enhancements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting with Mattermost v10.10, significant improvements have been made to the deployment and upgrade experience for administrators:

**Enhanced admin tooling**

* **Configuration validation**: New ``mattermost config validate`` command helps identify configuration issues before deployment
* **Migration planning**: Enhanced ``mattermost db migrate --save-plan`` provides detailed migration plans for better upgrade planning
* **Health checks**: Improved system health monitoring with more granular metrics and alerts

**Deployment automation improvements**

* **Infrastructure as code**: Better integration with automation tools and configuration management systems
* **Container optimization**: Improved Docker and Kubernetes deployment patterns with enhanced resource management
* **Zero-downtime upgrades**: Enhanced rolling upgrade capabilities for high-availability deployments

**Performance and monitoring**

* **Database optimization**: Improved connection pooling and query performance for PostgreSQL 13+ deployments
* **Observability**: Enhanced metrics collection and logging for better operational visibility
* **Resource monitoring**: Real-time system resource monitoring during deployment and upgrade processes

**Best practices for v10.10+ deployments**

1. **Pre-deployment validation**: Always run configuration validation before deploying to production
2. **Migration planning**: Generate and review migration plans for complex schema changes
3. **Monitoring setup**: Configure enhanced monitoring from the start of your deployment
4. **Backup automation**: Implement automated backup verification as part of your deployment pipeline
5. **Performance baseline**: Establish performance baselines early in your deployment lifecycle

Minimum database version policy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -111,6 +142,8 @@ When a PostgreSQL version reaches its end of life (EOL), Mattermost will require
+-----------------------------------------------------------+------------------+--------------------------------+
| :ref:`v10.6 <release-v10.6-feature-release>` | 2025-3-15 | 13.x |
+-----------------------------------------------------------+------------------+--------------------------------+
| v10.10 | 2025-6-15 | 13.x |
+-----------------------------------------------------------+------------------+--------------------------------+
| v10.11 ESR | 2025-8-15 | 13.x |
+-----------------------------------------------------------+------------------+--------------------------------+
| v11.5 ESR ``*`` | 2026-2-15 | 14.x (EOL 2026-11-12) |
Expand Down
16 changes: 16 additions & 0 deletions source/upgrade/important-upgrade-notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,22 @@ Important Upgrade Notes
| If you’re upgrading | Then... |
| from a version earlier than... | |
+====================================================+==================================================================================================================================================================+
| v10.10 | Enhanced deployment and upgrade experience with improved admin tooling and streamlined processes. Key improvements include: |
| | |
| | - **Performance optimizations**: Database queries and connection management have been optimized for better performance at scale. |
| | - **Enhanced monitoring**: New metrics and logging capabilities provide better visibility into system health and performance. |
| | - **Deployment automation**: Improved configuration management and deployment scripts for more reliable deployments. |
| | - **Upgrade safety**: Enhanced pre-upgrade validation checks and rollback capabilities for safer upgrades. |
| | |
| | **Best practices for v10.10+ deployments:** |
| | |
| | - Run ``mattermost config validate`` before upgrading to check for configuration issues |
| | - Use ``mattermost db migrate --save-plan`` to generate a detailed migration plan |
| | - Monitor system resources during deployment using the enhanced performance metrics |
| | - Follow the updated backup and recovery procedures for better data protection |
| | |
| | The migration is fully backwards-compatible and no downtime is expected for most deployments. |
+----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| v10.9 | A new index to the ``CategoryId`` column in ``SidebarChannels`` table was added to improve query performance. No database downtime is expected for this upgrade. |
| | For PostgreSQL, it takes around 2s to add the index on a table with 1.2M rows with an instance size of 8 cores and 16GB RAM. For MySQL, it takes around 5s on a |
| | table with 300K rows on an instance size of 8 cores and 16GB RAM. The migrations are fully backwards-compatible and no table locks or existing operations on the |
Expand Down
54 changes: 54 additions & 0 deletions source/upgrade/prepare-to-upgrade-mattermost.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,60 @@ Mattermost will aim to have non-locking, backwards-compatible migrations in gene

In the case of delayed upgrades, we recommend upgrading to the closest ESR version first, and from there to the next ESR. Do not attempt to directly upgrade to the latest version as it might break backwards compatibility of the older nodes in the cluster during the upgrade.

Prepare for Mattermost v10.10+ upgrades
-----------------------------------------

Mattermost v10.10 and later versions include enhanced preparation and validation tools to ensure smoother upgrades:

**Pre-upgrade validation**

Before upgrading to v10.10+, use the enhanced validation tools:

.. code-block:: sh

# Validate current configuration
mattermost config validate

# Generate detailed migration plan
mattermost db migrate --save-plan /tmp/migration-plan.json

# Check system health
mattermost system health

**Enhanced backup procedures**

v10.10+ includes improved backup validation:

.. code-block:: sh

# Verify backup integrity
mattermost backup verify --file /path/to/backup.sql

# Test backup restore (recommended for critical deployments)
mattermost backup test-restore --file /path/to/backup.sql --dry-run

**Deployment checklist for v10.10+**

1. **System requirements verification**: Ensure PostgreSQL 13+ is running and properly configured
2. **Configuration audit**: Run configuration validation and resolve any issues
3. **Performance baseline**: Capture current system performance metrics
4. **Migration planning**: Review the generated migration plan for complex changes
5. **Monitoring setup**: Configure enhanced monitoring before the upgrade
6. **Rollback preparation**: Ensure rollback procedures are tested and ready

**Resource monitoring during upgrade**

v10.10+ provides real-time upgrade monitoring:

* Database connection monitoring
* Memory usage tracking during migrations
* Disk I/O monitoring for large table updates
* Network performance metrics for clustered deployments

.. note::

For large deployments (100,000+ users), consider running the migration plan analysis tool to estimate upgrade duration and resource requirements.

Upgrade to Mattermost v7.1
--------------------------

Expand Down
70 changes: 70 additions & 0 deletions source/upgrade/upgrading-mattermost-server.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,76 @@ Make sure that you understand how to :doc:`prepare for your upgrade </upgrade/pr

Consider generating a migration plan using the :ref:`mattermost db migrate --save-plan <manage/command-line-tools:mattermost db migrate>` CLI command when upgrading to have a detailed record of the changes that will be applied to your database. This can make it easier to revert those changes if you need to downgrade later.

Enhanced upgrade process for v10.10+
------------------------------------

Mattermost v10.10 and later versions include significant improvements to the upgrade process, designed to provide a better admin experience with enhanced safety and monitoring capabilities.

**Pre-upgrade validation (v10.10+)**

Before starting the upgrade, run the enhanced validation suite:

.. code-block:: sh

# Run comprehensive pre-upgrade checks
mattermost upgrade validate

# Check system readiness
mattermost system health --upgrade-mode

# Validate database connectivity and permissions
mattermost db validate --upgrade-prep

**Upgrade monitoring (v10.10+)**

v10.10+ provides real-time upgrade monitoring and progress tracking:

.. code-block:: sh

# Start upgrade with monitoring
mattermost upgrade --monitor --log-level debug

# View upgrade progress (from another terminal)
mattermost upgrade status

# Monitor system resources during upgrade
mattermost system monitor --upgrade

**Automatic rollback detection (v10.10+)**

v10.10+ includes automatic rollback capabilities:

* **Health checks**: Continuous health monitoring during upgrade
* **Automatic rollback**: If critical issues are detected, the system can automatically roll back
* **Manual rollback**: Enhanced rollback procedures with validation

.. code-block:: sh

# Prepare rollback point before upgrade
mattermost upgrade prepare-rollback

# Execute rollback if needed
mattermost upgrade rollback --validate

**Enhanced post-upgrade verification (v10.10+)**

After upgrade completion, v10.10+ provides comprehensive verification:

.. code-block:: sh

# Verify upgrade success
mattermost upgrade verify

# Run post-upgrade optimization
mattermost system optimize

# Generate upgrade report
mattermost upgrade report --output /tmp/upgrade-report.json

.. note::

The enhanced upgrade process is backward compatible. Existing upgrade procedures will continue to work, but using the new v10.10+ features is recommended for better reliability and monitoring.

Upgrade Mattermost Server
--------------------------

Expand Down