Deployment documentation updates #7731
Conversation
|
Newest code from mattermost has been published to preview environment for Git SHA 7e0a17e |
|
Newest code from mattermost has been published to preview environment for Git SHA 39bb3de |
|
This is a great docs PR, @nickmisasi! I pulled your branch down and applied fixes to build errors and warnings where needed. Remind me: what's the goal of this docs update? What are we trying to achieve? That will help me formulate potential next step recommendations. |
|
Newest code from mattermost has been published to preview environment for Git SHA a77022b |
|
@cwarnermm High level, this is intended to make it easier to deploy Mattermost. The main focus was on clarity, as well as making sure that our recommendations are not only correct, but actually work (without prior knowledge of deploying Mattermost itself) |
|
@nickmisasi - Thank you! From my perspective, the content of this docs PR is excellent. No concerns at all. I know our structure and navigation needs work, but that's beyond the scope of this lift. Does it make sense to add customer-facing stakeholders as additional technical reviewers at this time? Are there specific perspectives you're looking for prior to us publishing these details? |
|
@nickmisasi - One outstanding thing we'll need to address in this docs PR is H2 redirects. This is something we'll do last, once all stakeholder input is incorporated. I can help with this final step. |
|
@cwarnermm I think it's a good idea to get some stakeholders to view this. Particularly I'd like eyes from @mrckndt, as he has some past work on Docker docs and is probably most familiar with RHEL. I'm open to others if you have anyone in mind. I'll also loop in @toninis as we discussed the Docker docs updates in Hub. |
|
Newest code from mattermost has been published to preview environment for Git SHA e669e4e |
|
Newest code from mattermost has been published to preview environment for Git SHA e6b0c1c |
|
Newest code from mattermost has been published to preview environment for Git SHA 9d7c374 |
|
Adding @gabrieljackson as I've pushed an overhaul to the Kubernetes documentation |
There was a problem hiding this comment.
Overall looks good . Once small consideration around docker for production ...
cc: @spirosoik @stylianosrigas
source/install/install-docker.rst
Outdated
| @@ -150,16 +141,106 @@ 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) | |||
There was a problem hiding this comment.
I do not think we should even consider this as an option for Production use .
It's best to redirect them to omnibus documentation and clearly specify that this is a deprecated way to deploy Mattermost and unmaintained .
Below we have a note stating that the repo is deprecated , we should not provide this as a viable production solution.
The `mattermost-docker <https://github.com/mattermost/mattermost-docker>`__ GitHub repository is deprecated.
There was a problem hiding this comment.
I've had some discussions around this as well, and I tend to agree with you. That being said, I'm wondering if we should keep it (but perhaps add a "this is no longer recommended" note) as there are likely a bunch of customers using this method right now?
There was a problem hiding this comment.
Below we have a note stating that the repo is deprecated , we should not provide this as a viable production solution.
@toninis that's not the up-to-date docker repo, that's the old one which caused tons of issues, hence the deprecation and complete rewrite. the very much not deprecated docker repo is at https://github.com/mattermost/docker
imo we should get rid of that note to avoid confusion, like here, and possibly even just get rid of the repo altogether. at this point it's been years since it was archived/deprecated.
There was a problem hiding this comment.
Docker can be for production only in cases like ECS (AWS) and Azure Container Apps. Do we have any idea if there's any deployment like this?
There was a problem hiding this comment.
@spirosoik @toninis @svelle -- what's the right way forward here? We need a decision to unblock this section of the docs.
There was a problem hiding this comment.
Docker can be for production only in cases like ECS (AWS) and Azure Container Apps. Do we have any idea if there's any deployment like this?
We have one VERY big customer running on ECS/Docker (with High Availability)... but I only know of this one in the "Super Large" end of the spectrum. Something to note on this, that should probably go in these Docker docs, is that we went through a very challenging upgrade exercise with them in 2023, and one of the key changes we had them make was to NOT use Elastic/Dynamic scaling features with the MM App Servers (and I believe for the DB as well).
Personally, there's very low chance I'd lead a customer down the path of Docker, but I'm in agreement with keeping the docs around.
There was a problem hiding this comment.
Thanks @sadohert super useful. Let's remove it from production deployment completely and put it only for testing purposes.
There was a problem hiding this comment.
^ @nickmisasi - Can you update this docs PR based on Spiros' direction, please? Once the updates are in, I'll add the last couple redirects for the Docker page, approve the PR and we can merge it.
There was a problem hiding this comment.
I've removed the production route for docker and updated references to it. I've also closed the accompanying PR in mattermost/docker
There was a problem hiding this comment.
adding @gabrieljackson to cross-check and @coltoneshaw, @victorehernandez who may have some more feedback for customers before we close this PR. What's your thoughts guys about the docker deployment in production?
From your experience with customers so far what's the number #1 install method from higher priority to lower priority?
lastl @sadohert from the top 100 customers is this the only customer who uses it? also could you give us the why behind this below? I don't really understand why not to use the autoscale features.
and one of the key changes we had them make was to NOT use Elastic/Dynamic scaling features with the MM App Servers (and I believe for the DB as well).
|
Newest code from mattermost has been published to preview environment for Git SHA d3f229e |
|
Newest code from mattermost has been published to preview environment for Git SHA 9bf8a5a |
|
Newest code from mattermost has been published to preview environment for Git SHA 40823d2 |
|
Newest code from mattermost has been published to preview environment for Git SHA ddff5a0 |
|
Newest code from mattermost has been published to preview environment for Git SHA 31e3535 |
|
|
||
| Install Mattermost on Kubernetes | ||
| -------------------------------- | ||
| 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. |
There was a problem hiding this comment.
I like how we are more opinionated of how to install and run Mattermost via the operator, but I think it would be good to walk back some of this wording a bit. In particular generally not recommended for production deployments should probably be clarified so our customers that want to own all of their data know they are using a supported setup.
|
Newest code from mattermost has been published to preview environment for Git SHA 240257a |
|
Newest code from mattermost has been published to preview environment for Git SHA 98198ef |
|
@cwarnermm I think I've addressed everything here. Let me know if there's anything else you need from me! |
Summary
I took a pass of each of the main installation methods, and performed a dry run on a new EC2 instance for each. I have made some documentation updates. For most of these updates, it's primarily for clarity. I also made some adjustments to split out some things that are repeatedly written between the various deployment methods to be more DRY.
The most major change was the overhaul of the Docker deployment. The current docs "for production use" have the reader deploy Mattermost and its database on the same instance. This isn't the best advice in production. I've split the documentation into 2 paths here - Quick Start (essentially the existing docs), and Production Use (adjustments to only deploy the Mattermost application container, suggesting external hosting for db and storage). These changes require
Ticket Link
https://mattermost.atlassian.net/browse/CLD-8785
https://mattermost.atlassian.net/browse/CLD-8848
https://mattermost.atlassian.net/browse/CLD-8849
https://mattermost.atlassian.net/browse/CLD-8850
https://mattermost.atlassian.net/browse/CLD-8851
https://mattermost.atlassian.net/browse/CLD-8852
https://mattermost.atlassian.net/browse/CLD-8853