Add FIPS migration guide for existing deployments

[ewwollesen]

Summary

• Adds source/deployment-guide/server/containers/fips-migration.rst — a step-by-step guide for migrating an existing Docker or Kubernetes Mattermost deployment to the mattermost/mattermost-enterprise-fips-edition image.
• Links the new page from the existing FIPS overview (fips-stig.rst), which previously only said "existing deployments can change the image" without procedure.
• Registers the new page in a hidden toctree on deploy-containers.rst so Sphinx picks it up and search indexes it.

This is a rough draft. Scope was intentionally kept narrow: Mattermost Server image swap only, on Docker/Compose and Kubernetes (Mattermost Operator). The Operator container's own FIPS variant and Push Proxy migration are mentioned in the intro but procedures are out of scope for this first pass.

The page covers a new v11.7 prerequisite (minimum 14-character Postgres password) as a bullet in "Before you begin", flagged with the v11.7+ version requirement.

Test plan

• gmake html succeeds with no new warnings on the changed files (pre-existing 46 warnings are all in unrelated files)
• New page renders at build/html/deployment-guide/server/containers/fips-migration.html
• Reviewer spot-checks the rendered FIPS/STIG tab on deploy-containers.html to confirm the new "see migration guide" link resolves
• Reviewer confirms the prerequisite framing for the v11.7 14-char Postgres password requirement matches what release notes will say
• Reviewer confirms Operator/Push Proxy out-of-scope framing in the intro is acceptable for this first pass

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a new FIPS migration guide for Mattermost containers and updates navigation and an existing FIPS doc to link to it. The new guide details prerequisites, downtime planning, Kubernetes and Docker/Docker Compose migration steps, post-migration checks, and rollback procedures.

Changes

FIPS Container Migration Documentation

Layer / File(s)	Summary
Core Migration Guide source/deployment-guide/server/containers/fips-migration.rst	New file: comprehensive migration guide covering prerequisites, version alignment, downtime planning, Kubernetes (Mattermost Operator) and Docker/Docker Compose migration steps, post-migration verification, and rollback instructions.
Cross-Reference source/deployment-guide/server/containers/fips-stig.rst	Existing FIPS image variant bullet updated to append a link referencing the new migration guide.
Navigation / Toctree source/deployment-guide/server/deploy-containers.rst	Added a toctree entry exposing the new "Migrate an existing deployment to FIPS-compliant containers" page in documentation navigation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding a FIPS migration guide for existing deployments.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining what was added, why, and the scope of the changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/fips-migration-guide

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA a0f380e

[Copilot]

Pull request overview

Adds a new documentation page that provides step-by-step instructions for migrating existing Docker/Compose and Kubernetes (Operator-managed) Mattermost deployments to the FIPS-compliant Enterprise container image, and wires that page into the existing containers/FIPS documentation so it’s discoverable and indexed by Sphinx.

Changes:

• Adds a new FIPS migration guide page for existing deployments.
• Updates the FIPS/STIG overview to link to the new migration guide.
• Registers the new page via a hidden toctree so it’s included in the Sphinx build/search index.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
source/deployment-guide/server/deploy-containers.rst	Adds a hidden toctree entry so the new FIPS migration page is included in Sphinx output/search.
source/deployment-guide/server/containers/fips-stig.rst	Adds a direct link from the FIPS/STIG overview note to the new migration guide.
source/deployment-guide/server/containers/fips-migration.rst	Introduces a new migration procedure doc for swapping existing deployments to the FIPS Enterprise image (Kubernetes Operator + Docker/Compose).

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA b30d4f4

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 0edcf76

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 4ec3a6e

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

source/deployment-guide/server/containers/fips-migration.rst (2)

80-80: ⚡ Quick win

Break up long introductory sentence for readability.

This 79-word sentence is difficult to scan and may overwhelm Novice Nate. Consider breaking it into two sentences or using a structured list to separate the context (official deployment) from the customization note.

Suggested revision

-These steps are written for the official `Mattermost Docker deployment <https://github.com/mattermost/docker>`_, which selects the Mattermost image and tag through ``.env`` variables (``MATTERMOST_IMAGE`` and ``MATTERMOST_IMAGE_TAG``) referenced from ``docker-compose.yml`` as ``mattermost/${MATTERMOST_IMAGE}:${MATTERMOST_IMAGE_TAG}``. If you're using a custom Docker setup that hardcodes the image in ``docker-compose.yml`` or uses different variable names, adapt these steps accordingly.
+These steps are written for the official `Mattermost Docker deployment <https://github.com/mattermost/docker>`_. That deployment selects the Mattermost image and tag through ``.env`` variables (``MATTERMOST_IMAGE`` and ``MATTERMOST_IMAGE_TAG``) referenced from ``docker-compose.yml`` as ``mattermost/${MATTERMOST_IMAGE}:${MATTERMOST_IMAGE_TAG}``.
+
+If you're using a custom Docker setup that hardcodes the image in ``docker-compose.yml`` or uses different variable names, adapt these steps accordingly.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@source/deployment-guide/server/containers/fips-migration.rst` at line 80,
Split the long introductory sentence in the fips-migration.rst paragraph into
two clearer sentences (or a short list): first state that the steps target the
official Mattermost Docker deployment and how the image/tag are selected via
.env variables, and then add a separate sentence explaining that if a custom
Docker setup hardcodes the image in docker-compose.yml or uses different
variable names (notably MATTERMOST_IMAGE and MATTERMOST_IMAGE_TAG) the reader
should adapt the steps accordingly; update the text around the references to
docker-compose.yml, MATTERMOST_IMAGE and MATTERMOST_IMAGE_TAG to keep them
intact but move them into the second, shorter sentence for readability.

---

71-75: ⚡ Quick win

Add expected output example for verification command.

The jsonpath command in step 6 is useful but complex. Novice Nate would benefit from knowing what successful output looks like to confirm the FIPS image is running.

Consider adding a brief example of expected output, such as:

 6. Verify the running pods are using the FIPS image:

    .. code-block:: sh

       kubectl -n [namespace] get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'
+
+   You should see output showing your Mattermost pods running the ``mattermost-enterprise-fips-edition`` image.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@source/deployment-guide/server/containers/fips-migration.rst` around lines 71
- 75, Add a short example of the expected command output immediately after the
kubectl jsonpath command so readers can verify success; show the output format
is "pod-name<TAB>container-image" and include a sample line such as:
my-app-xxxx<TAB>myrepo/myapp:fips (or my-app-xxxx<TAB>myrepo/myapp:fips-1.0) to
indicate the FIPS-tagged image is being used; update the text near the command
invocation (the kubectl -n [...] get pods -o jsonpath=... line) to include this
example output for clarity.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@source/deployment-guide/server/containers/fips-migration.rst`:
- Line 26: Split the dense prerequisite into short ordered steps: state the
requirement (PostgreSQL password must be ≥14 chars for FIPS), then give explicit
sub-steps: (1) rotate the DB password in PostgreSQL using your DB admin tool or
psql; (2) update the stored credential in your deployment (update
POSTGRES_PASSWORD in .env for the Docker deployment or the Secret referenced by
spec.database.external.secret for Operator/Kubernetes); and (3) ensure
Mattermost loads the new credential — either restart Mattermost after updating
the secret to make the server pick up the new password, or skip a separate
restart if you plan to perform the migration immediately because the migration
will recreate the container and apply the image swap; mention updating
credentials before migration to avoid connectivity failures. Reference
POSTGRES_PASSWORD, .env, spec.database.external.secret and Mattermost in the
steps.

---

Nitpick comments:
In `@source/deployment-guide/server/containers/fips-migration.rst`:
- Line 80: Split the long introductory sentence in the fips-migration.rst
paragraph into two clearer sentences (or a short list): first state that the
steps target the official Mattermost Docker deployment and how the image/tag are
selected via .env variables, and then add a separate sentence explaining that if
a custom Docker setup hardcodes the image in docker-compose.yml or uses
different variable names (notably MATTERMOST_IMAGE and MATTERMOST_IMAGE_TAG) the
reader should adapt the steps accordingly; update the text around the references
to docker-compose.yml, MATTERMOST_IMAGE and MATTERMOST_IMAGE_TAG to keep them
intact but move them into the second, shorter sentence for readability.
- Around line 71-75: Add a short example of the expected command output
immediately after the kubectl jsonpath command so readers can verify success;
show the output format is "pod-name<TAB>container-image" and include a sample
line such as: my-app-xxxx<TAB>myrepo/myapp:fips (or
my-app-xxxx<TAB>myrepo/myapp:fips-1.0) to indicate the FIPS-tagged image is
being used; update the text near the command invocation (the kubectl -n [...]
get pods -o jsonpath=... line) to include this example output for clarity.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7ce1e735-3a0d-4edc-bfe1-8fd5b46767b4

📥 Commits

Reviewing files that changed from the base of the PR and between 560c09f and 4ec3a6e.

📒 Files selected for processing (3)

• source/deployment-guide/server/containers/fips-migration.rst
• source/deployment-guide/server/containers/fips-stig.rst
• source/deployment-guide/server/deploy-containers.rst

[coderabbitai]

🧹 Nitpick comments (1)

source/deployment-guide/server/containers/fips-migration.rst (1)

26-37: ⚡ Quick win

Promote the v11.7+ password constraint to an important admonition.

Line 26 contains a hard prerequisite that can break migration if missed; surfacing it as .. important:: will make it easier for admins to spot before executing steps.

Suggested minimal diff

-5. **PostgreSQL password length.** Beginning with Mattermost v11.7, the Postgres password used by the Mattermost server must be at least 14 characters when running the FIPS image. If your current password is shorter, complete these steps before swapping the image:
+.. important::
+   **PostgreSQL password length (v11.7+).** Beginning with Mattermost v11.7, the Postgres password used by the Mattermost server must be at least 14 characters when running the FIPS image. If your current password is shorter, complete these steps before swapping the image:
 
-   a. Rotate the password in PostgreSQL. For example, connecting as a Postgres superuser and replacing ``mmuser`` and ``<new password>`` to match your deployment:
+   1. Rotate the password in PostgreSQL. For example, connecting as a Postgres superuser and replacing ``mmuser`` and ``<new password>`` to match your deployment:
 
       .. code-block:: sql
 
          ALTER USER mmuser WITH PASSWORD '<new password>';
 
-   b. Update the password where your deployment stores it: in the official Docker deployment, the ``POSTGRES_PASSWORD`` value in ``.env``; in Operator-managed Kubernetes deployments, the database Secret referenced by your ``Mattermost`` custom resource (commonly under ``spec.database.external.secret``).
+   2. Update the password where your deployment stores it: in the official Docker deployment, the ``POSTGRES_PASSWORD`` value in ``.env``; in Operator-managed Kubernetes deployments, the database Secret referenced by your ``Mattermost`` custom resource (commonly under ``spec.database.external.secret``).
 
-   c. Proceed to the image swap procedure for your deployment type below. Recreating the container as part of the migration applies the new credentials — no separate restart is required.
+   3. Proceed to the image swap procedure for your deployment type below. Recreating the container as part of the migration applies the new credentials — no separate restart is required.

As per coding guidelines, use important admonition for prerequisites, constraints, or high-impact information that materially affects correctness, supportability, compliance, or success.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@source/deployment-guide/server/containers/fips-migration.rst` around lines 26
- 37, Convert the "5. **PostgreSQL password length.**" prerequisite paragraph
(the paragraph and its sub-steps a–c) into an important admonition by replacing
the plain paragraph with a reST ".. important::" block containing the same text
and the SQL code-block; ensure the heading text ("PostgreSQL password length.")
and the three steps (a. ALTER USER..., b. Update the password..., c. Proceed to
the image swap...) are preserved verbatim inside that admonition so the
constraint is highlighted to admins.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@source/deployment-guide/server/containers/fips-migration.rst`:
- Around line 26-37: Convert the "5. **PostgreSQL password length.**"
prerequisite paragraph (the paragraph and its sub-steps a–c) into an important
admonition by replacing the plain paragraph with a reST ".. important::" block
containing the same text and the SQL code-block; ensure the heading text
("PostgreSQL password length.") and the three steps (a. ALTER USER..., b. Update
the password..., c. Proceed to the image swap...) are preserved verbatim inside
that admonition so the constraint is highlighted to admins.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 82b24583-9546-4d82-bade-911837c10857

📥 Commits

Reviewing files that changed from the base of the PR and between 4ec3a6e and ff5f1e5.

📒 Files selected for processing (1)

• source/deployment-guide/server/containers/fips-migration.rst

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA ff5f1e5