AI Agents · Infrastructure · Cost

Using AI Agents
to Migrate Off Slack.

Two paired skills. One focused weekend. Roughly a 99% cut in ongoing cost — and your whole chat history on hardware you own.

Slack → Mattermost

Public · private · DMs · threads

Agent-driven cutover

Scroll to Explore

For operators who want to run this

Download the full guide as Markdown

for feeding to an AI agent · ~185 KB · 2.5k lines

.md

The 2.5k-line source guide — paste the path into Claude Code or Codex and the agent drives the migration from there.

There is a tweet from April 2026 that I keep coming back to. It is a founder named Alex Cohen — 40 employees, paying Slack about six thousand dollars a year, just quoted twenty-one thousand a year to move onto the Business+ tier so he can get a BAA for a customer contract. A three-and-a-half-times price hike to keep using the same software he’s already using.

That is the moment, more or less, when almost every growing company decides it is done with Slack. Not because the product is bad — Slack is a genuinely polished piece of software — but because the pricing is designed to make the decision for you, and because the thing you get back when you cancel is a pile of JSON files with dead links to your own attachments. You never really owned your history. You were renting it, on a meter that keeps going up.

For as long as I can remember, the reason most companies didn’t migrate off Slack onto something self-hosted was that the migration itself was a project. Someone had to write a script, chase expiring file links, rebuild per-channel membership lists, reconcile message counts, stand up a Postgres, configure Nginx with the right WebSocket upgrade, and get SMTP working well enough that password-reset emails would actually land in inboxes. Then keep it all running, every week, forever.

What changed, very recently, is that a sufficiently capable coding agent — Claude Code or Codex — can do every single one of those things in the background while you drink coffee. Not with you writing bash. With you reading a handful of reports, clicking approve on twenty or thirty prompts spread over a week, and pasting a short English sentence when the agent is ready for the next stage.

The thing that actually encodes the migration is not a fragile custom script. It is a pair of agent skills — one for extraction, one for setup and import — each a directory of prompts, references, and scripts that the agent loads into its context and drives on your behalf. Those two skills (plus a third that runs ongoing maintenance) are the subject of this article: how they decompose the problem, how the agent drives them, and every operational detail an operator will need in front of them on cutover day.

Part 0 · Why bother

Why bother with any of this?

Honest answer: to save a lot of money without losing your history. Alex Cohen’s tweet is just one data point. The pattern underneath it is universal: Slack’s Pro plan keeps you hooked with decent features, and when you grow past the point where Pro’s limits hurt — or you need a BAA, or you need to export private channels, or you want SSO, or you simply want a saner admin — the vendor hands you a quote that makes your eyes water.

Self-hosting Mattermost for the same 40-person workspace comes out to roughly $71/month for the whole stack. Against Alex’s $21,000/year Slack Business+ quote, that’s a 96% cost reduction, about $20,150 saved per year. Against the $6,000/year Slack Pro bill he was already paying, it’s still an 86% cost reduction, about $5,150 saved per year. Both include compliance features Slack would charge extra for: you own the server, so you can sign your own BAA, configure retention your own way, and audit the data at the byte level.

At 1,000 users, the numbers get even less forgiving for Slack. Business+ at $12.50/user/month is $150,000/year. The same Hetzner AX52 + Cloudflare + Postmark + R2 stack serves 1,000 users for about $90/month, or $1,080/year. A 99.3% cost reduction, roughly $149,000 saved annually, and the data sits on hardware you own and can put in any jurisdiction you want.

Other reasons, in rough order of how often they matter

Why else self-host?

Reason	What it unlocks
You own your history	Slack's 90-day retention on Free, plus dead-link exports, means the moment you stop paying, your history is effectively gone. Self-hosted Mattermost keeps data in a Postgres you can back up, restore, inspect, and re-import.
Compliance without the BAA premium	You're the data custodian; you sign your own BAA, DPA, SCCs. Mattermost Team Edition (free) supports SSO via OAuth/SAML with the Professional Edition upgrade at $10/user/month if needed — still well below Slack Business+.
AI features, your way	Slack's enterprise tier bundles AI into the price. With Mattermost you pick: OpenAI, Anthropic, Groq, your own Llama-on-a-GPU, or no AI at all. Cost scales with actual usage, not per-seat.
No vendor price hikes	Your costs are fixed infrastructure rented by the month; no one quietly raises the seat price or changes the retention policy overnight.
Works on a locked-down network	Useful for regulated industries, field teams on unreliable internet, or a deliberate “no cloud” policy.
No seat counting	No guest-user surcharge, no “inactive user” rebuilds. Mattermost Team Edition doesn't have the same SKU inventory Slack does.

What this article does not try to convince you of: that Mattermost is more polished than Slack for every end-user scenario. Slack has spent a decade on UX details Mattermost is still catching up on (huddles have no drop-in equivalent; some channel-management ergonomics are less clicky). If you’re 5 people and pay $0/month on Slack’s Free tier and love it, this whole exercise is a waste of time. The migration pays off when your Slack bill is a real line item and the vendor’s next price-hike email is about to hit your inbox.

The 60-second version

Read this first, even if you never run a command.

Slack charges $7.25–$12.50 per user per month. A 1,000-person workspace pays $87k–$150k per year, and the export you get at the end is JSON with dead links. Mattermost is open-source, self-hosted, and feels nearly identical to Slack — same channels, DMs, threads, reactions, emoji, file sharing, voice/video calls, slash commands — plus official tooling for importing Slack exports. A Hetzner AX52 + Cloudflare (free) runs the whole thing for about $75/month. ~99% cost reduction. The hard part is moving your history without losing anything; the two skills this article describes encode the safe path.

The overall flow:

You decide a few things (plan tier, domain, server size, cutover date, rollback owner).
An AI agent runs Phase 1 on your laptop — downloads Slack history, pulls every file while the link still works, resolves user emails, packages it into one zip.
The agent runs Phase 2 — SSHes into an Ubuntu server, installs Mattermost behind Cloudflare, rehearses on a throwaway copy, runs the real cutover once the fail-closed readiness gate says green.
Users activate their accounts at https://chat.yourdomain.com/reset_password with their Slack email.

You will spend most of the elapsed wall-clock time waiting (for Slack to email the export, for the server to provision, for the import to finish). The skills are structured so waiting stays waiting and doesn’t turn into operator attention.

For non-technical operators

Can a non-technical person do this?

Yes, and it’s genuinely less work than the length of this article might suggest. The article is long because it covers the whole problem space so you have an answer for whatever you hit. In practice, most operators spend a handful of hours of actual attention spread across 1 to 2 weeks, and the agent is doing the rest in the background.

What you actually do:

Action	Effort
Paste tokens the agent asks for (Slack admin, Cloudflare, Postmark).	One browser-tab fetch per token.
Click “Approve” on permission prompts before the agent does something destructive.	~20–40 approvals, 5 seconds each.
Read a few reports (readiness score, reconciliation output, cutover status).	5–15 minutes per report.
Send user comms at cutover (copy-paste from templates).	5 minutes total.

What you do not do: write Bash, edit config files by hand, install software, configure Nginx, tune Postgres, write Cloudflare API calls, run mmctl commands, or SSH into the server. The agent does all of that.

Two things the agent cannot do for you:

Order the server at Hetzner (or OVH, Contabo). Hetzner requires ID verification on the human paying. You sign up, ID-verify (~2 hours clearance during business hours), and click “Order”; the agent does everything from there.
Pick a named rollback owner for cutover. This is you, or someone you designate, who has pre-committed to making the call to abort if cutover goes sideways. Phase 2 refuses to run cutover without ROLLBACK_OWNER set, on purpose.

When you’re done

What you end up with

A self-hosted Mattermost 10.11+ server behind Cloudflare with Origin CA TLS and proper WebSocket upgrade.
All your Slack history (public, private, DMs, group DMs, threads, reactions) imported and searchable.
File attachments either in local storage or Cloudflare R2 — preserved, not linked.
Custom emoji, canvases (as sidecar HTML posts), lists (as sidecar JSON posts), and admin audit CSVs (as sidecar posts in a dedicated channel). Nothing Slack-native gets silently dropped.
User accounts pre-created, matched by email. Users activate via /reset_password with their Slack email.
A complete evidence pack: SHA-256 hashes of every raw ZIP, enriched ZIP, import ZIP; reconciliation reports; cutover status JSON; activation proof.

How long this takes

Timeline and effort expectations

A single operator driving the agent can take a small workspace (fewer than 50 users, under 1 GB of Slack history) start-to-finish in a single weekend. A 1,000-user workspace with a few years of history typically runs 1 to 2 weeks of calendar time if the operator rehearses twice, but the operator’s actual attention is still just a few hours spread over that window.

Phase	Duration	Your attention
Slack export approval (Business+)	1–7 days, out of your control	none while waiting
Download + enrich + transform	1–6 hours, scales with data	5–15 min to kick off
Server provisioning + deploy	20–60 min	approve SSH/install prompts
Staging rehearsal	1–4 hours	10 min kick-off + read report
Production cutover window	15–45 min after staging green	full attention (approvals, comms)
Activation week	3–7 days	respond to help-desk questions

The skills are structured so waiting is waiting, not operator time. The agent kicks off a long download, watches it, and pings you when it finishes or gets stuck. During a 6-hour enrich stage your laptop can be asleep; resume the agent session when you come back and it picks up where it left off.

Before you start

Which path through this guide is for you?

There are three supported paths. Pick one now and stay with it — they produce the exact same result, the only difference is how the skills get onto your machine and how you drive the agent.

Path	Who it’s for	Where skills live	What you install
A: Desktop app + jsm	Prefers clicking over typing; Mac or Windows laptop. Recommended for most.	jsm manages ~/.claude/skills/ (and ~/.codex/skills/) for you.	Claude Code desktop app or Codex desktop app, plus the jsm CLI.
B: CLI only	Comfortable with terminals; wants the leanest install.	Manual symlink or jsm install.	Claude Code CLI or Codex CLI.
C: CLI + jsm	Wants the CLI but wants skills auto-synced across machines.	jsm-managed.	CLI plus jsm.

Decision tree

Quick routing before you commit

┌────────────────────────────────────────────────────────────────┐
│ What Slack plan are you on?                                    │
└────────────────────────────────────────────────────────────────┘
    │
    ├── Free or Pro ──────→ Track B (slackdump-primary). See §3.
    │                       Expect: public + accessible private channels
    │                       and DMs only. Other people's DMs are invisible.
    │
    ├── Business+ ───────→ Track A (official admin export). See §3.
    │                       Expect: full workspace content.
    │
    └── Enterprise Grid ─→ Track C (grid split). See §Grid-migration.
                            Either grid-wide export + split, or
                            per-workspace exports.

┌────────────────────────────────────────────────────────────────┐
│ Where will Mattermost live?                                    │
└────────────────────────────────────────────────────────────────┘
    │
    ├── Hetzner AX42/AX52 dedicated (recommended) ─→ §2.3 sizing
    ├── OVH Advance / Contabo VPS ─────────────────→ same table, cheaper
    └── Existing infra you run ─────────────────────→ supply SSH target

┌────────────────────────────────────────────────────────────────┐
│ How do you want to drive the agent?                            │
└────────────────────────────────────────────────────────────────┘
    │
    ├── Click, don't type ───→ Path A (Desktop app). See §Part 1.
    ├── Terminal-native ────→ Path B (CLI-only).
    └── Multi-machine ──────→ Path C (CLI + jsm for cross-device sync).

┌────────────────────────────────────────────────────────────────┐
│ Where is your Mattermost database going to live?               │
└────────────────────────────────────────────────────────────────┘
    │
    ├── Same box as Mattermost (default)  →  POSTGRES_DSN=postgres://…@localhost:5432
    │                                         Skill provisions local PG for you.
    ├── Supabase (managed)                →  Supabase session pooler on 5432
    │                                         (NOT the transaction pooler on 6543).
    └── Your own managed PG               →  Provide the DSN; skill is hands-off.

If any branch surprises you, read its linked section before continuing. The skills themselves detect which path the operator is on and route accordingly — the Slack plan tier alone changes validators downstream.

The math

The money math.

Start with the arithmetic, because everything else follows from it. Slack's list prices are $7.25/user/month for Pro and $12.50/user/month for Business+. A thousand-person company is paying somewhere between ninety and a hundred and fifty thousand dollars a year just to have a chat window. A forty-person company is paying between thirty-five hundred and six thousand — modest in absolute terms, but a reliable target for the next compliance-triggered price jump.

Self-hosted Mattermost is not close in price. A single Hetzner AX42 with NVMe and 64 GB of RAM serves a couple hundred users for roughly fifty dollars a month. An AX52 handles a thousand. Add Cloudflare's free plan in front, Postmark for password-reset emails, a little R2 for files, and an off-site backup target, and the total bill for a 340-person company rounds to $90/month. At 1,000 users it is still under $100/month, against Slack's six-figure ARR.

Run the slider below. The interesting thing is less the absolute savings — which are large — than how the curve shape changes with scale. Slack compounds linearly with headcount. The Mattermost bill barely moves until you need a second box.

Why now

Why this wasn’t practical before.

Every piece of the migration has existed in open source for years. slackdump can walk an authenticated Slack session and pull messages. mmetl turns a Slack export ZIP into Mattermost's bulk-import JSONL. mmctl uploads the ZIP and runs the import. Mattermost itself is a production-grade server you can apt-install on a plain Ubuntu box. None of this is new.

What was new, and genuinely painful, was the glue. The Slack export's file links expire in a few hours. mmctl needs a JSONL with lines in a very specific order (version, emoji, team, channel, user, post, direct_channel, direct_post) or it rejects the whole import. Thread replies must reference their parent before the parent is redefined. Custom emoji objects must appear before the team line, not after. Mattermost's default MaxPostSize of 4,000 characters will truncate every long-form Slack message silently, so you have to set it to 16,383 before import, via a config.json value that has to match the server's apt-installed layout exactly. Nginx in front of it needs a WebSocket upgrade block or your client disconnects every few minutes without any visible error.

In the old world, one senior engineer spent two or three weeks figuring all of that out, writing a pile of bespoke scripts that worked for their workspace and no one else's, and then the migration happened. In the new world, a skill encodes the whole procedure once, and anyone who installs the skill inherits everything that senior engineer learned. The agent reads the skill, follows the runbook, and narrates what it is doing. You read the reports.

The specific pair of skills this whole piece is about:

slack-migration-to-mattermost-phase-1-extraction runs on your laptop. Picks Track A / Track B / Track C based on your Slack plan, pulls the content, downloads every file before the link expires, resolves users to emails, extracts canvases and lists as sidecar content, transforms through mmetl, patches the JSONL, packages the ZIP, runs five validators, and emits a hash-anchored evidence pack.
slack-migration-to-mattermost-phase-2-setup-and-import runs from the same laptop over SSH to a fresh Ubuntu VPS. Provisions the server, installs Mattermost and Nginx, wires up Cloudflare, rehearses the import on a throwaway staging target, computes a fail-closed readiness gate, and executes the production cutover with explicit rollback semantics.

Together they are about eight thousand lines of scripts and references, hash-verified at install time via jsm, updated on a subscription cadence. The thing you type, when it is time to run them, is “Use the slack-migration-to-mattermost-phase-1-extraction skill to run the setup stage.”

Part 1 · one-time setup

Workstation setup: day zero to first skill call.

You do this once per laptop. The skills install themselves via Claude Code’s plugin / skills mechanism; the tooling they call (slackdump, mmetl, mmctl, etc.) is installed by a bootstrap script that ships with the skill.

§1.0

Day zero — order a server and wire up SSH

Phase 2 installs Mattermost on an Ubuntu server that you rent. Order it before you install the skill so the IP address and SSH access are ready when you need them. Takes about 2 hours wall-clock (most of it Hetzner’s ID verification) and ~15 minutes of attention.

1.0.1

Order a Hetzner dedicated server

Go to hetzner.com/dedicated-rootserver and click Server Auction. The auction has the same specs at lower prices.
Sign up with company email. Hetzner requires government-ID upload for first-time verification; usually clears in 1–2 hours during German business hours.
Pick an AX42 (up to ~250 users) or AX52 (250–1,000 users) from the auction. Prefer NVMe storage. Datacenter: Falkenstein or Helsinki for EU, Ashburn for US.
OS: Ubuntu 24.04 LTS (noble). If 24.04 isn’t offered, pick 22.04 LTS and upgrade post-provision.
Leave Rescue System and KVM on defaults. Do not set a root password. Paste your SSH public key (from §1.0.3 below) into the “SSH keys” field.
Submit. You’ll receive a “Server installed” email with the IP and confirmation the key was installed.

OVH (US operators preferring a North American provider) and Contabo (small workspaces under 50 users at ~$10/mo) work the same way. OVH uses the Bare Metal Cloud → Advance series; Contabo uses VPS M (under 50 users), L (up to 250), XL (up to 1,000).

1.0.2

I don’t have a domain yet

Cloudflare Registrar — at-cost ~$10/year for .com, auto-adds the zone to Cloudflare. Fastest path.
Any existing registrar (GoDaddy, Namecheap, Porkbun, Route 53) — update nameservers to Cloudflare later. See §Cloudflare walkthrough.

Buy the domain now. DNS propagation after nameserver update takes 15 minutes to 24 hours; you want that clock running in parallel with ID-verification.

1.0.3

Generate an SSH keypair on your laptop

An SSH keypair is two files: a private key that stays on your laptop (treat it like a password) and a public key you paste into the server. They unlock the server together; without the private file on your laptop, nobody can log in as you.

macOS

ssh-keygen -t ed25519 -C "your_email@example.com"
# press Enter to accept default path (~/.ssh/id_ed25519)
# passphrase is optional; empty is acceptable if your disk is encrypted

cat ~/.ssh/id_ed25519.pub
# copy the ssh-ed25519 AAAAC3... line into Hetzner's order form

Windows 10/11 (PowerShell)

ssh-keygen -t ed25519 -C "your_email@example.com"
# files land in C:\Users\<you>\.ssh\
Get-Content $HOME\.ssh\id_ed25519.pub

1.0.4

First SSH login after the server is installed

ssh root@95.217.12.34     # replace with your real IP
# SSH prints a host-key fingerprint — type 'yes' to record it in ~/.ssh/known_hosts
# you should land at root@Ubuntu-...#
# type 'exit' to return

If it asks for a password instead of logging in directly, Hetzner didn’t install the SSH key. Go to robot.hetzner.com → your server → add key under Linux rescue system, use Reset root password, SSH in with the temp password, and manually append your public key to /root/.ssh/authorized_keys; then chmod 600 /root/.ssh/authorized_keys.

If you lose your private SSH key (recoverable)

Boot into Hetzner’s rescue system (robot UI → server → Rescue → activate Linux rescue → reboot). Get a temp root password by email, SSH in, mount the installed filesystem (mount /dev/sda1 /mnt), paste a new public key into /mnt/root/.ssh/authorized_keys, umount, reboot. Works for every provider with a rescue console.
Re-order the server and start fresh. If you’re at day zero and nothing is installed yet, this is faster than rescue-system diagnosis.

Sidebar: Windows-specific notes

PowerShell, not Command Prompt — this article’s commands assume a POSIX-ish shell. On Windows, PowerShell 7+ or Git Bash.
Install Git for Windows (git-scm.com/downloads/win). Provides git plus Git Bash.
Chocolatey is the Windows equivalent of Homebrew — install from chocolatey.org/install in an Admin PowerShell.
WSL2 is optional but convenient: wsl --install -d Ubuntu-24.04, then wsl.
Paths: Mac-style ~/.claude/skills/ = Windows %USERPROFILE%\.claude\skills\.
Symlinks need Admin PowerShell (New-Item -ItemType SymbolicLink) or Git Bash with Developer Mode.
SSH built into Windows 10 (1809+) and 11. Run ssh -V; if missing, Settings → Apps → Optional Features → OpenSSH Client.

§1.1

Pick an agent harness (GUI app or CLI)

You need one of the following. Either can run the skills end to end. Both Claude Code and Codex ship as GUI desktop apps and as CLIs.

Option	Requires	Install
1a · Claude Code desktop	Anthropic Pro, Max, Team, or Enterprise plan	Download from claude.ai/download · sign in · open Code tab · Select folder
1b · Codex desktop	ChatGPT Plus/Pro/Business/Edu/Enterprise, or OpenAI API key with Codex access	Download from developers.openai.com/codex/app · sign in · pick project folder
1c · Claude Code CLI	Anthropic plan	npm install -g @anthropic-ai/claude-code · claude login · claude in your workdir
1d · Codex CLI	ChatGPT plan or API key	Install from github.com/openai/codex · codex login · codex in workdir

What “running the skill” looks like

In all four options, running a skill means opening a session in your working directory and asking the agent, in plain English, to use it. Examples:

Desktop app: type / in the prompt box to see slash commands, pick slack-migration-to-mattermost-phase-1-extraction. Or just say “Use the Phase 1 Slack-to-Mattermost skill to run the setup stage.”
CLI: claude (or codex) in the workdir, then the same plain-English request.

Behind the scenes the agent runs ./migrate.sh setup for you and shows the output. You’ll see commands flash by; you don’t need to memorize them.

§1.2

Install the two skills

Skill catalog pages · open in a new tab

jeffreys-skills.md/skills/slack-migration-to-mattermost-phase-1-extraction — Phase 1, the Slack-side extraction skill.
jeffreys-skills.md/skills/slack-migration-to-mattermost-phase-2-setup-and-import — Phase 2, the Mattermost-side deploy + import skill.
jeffreys-skills.md/skills/slack-migration-to-mattermost-phase-3-ongoing-mattermost-maintainance — Phase 3, the ongoing-maintenance skill (weekly sweep, auto-rollback upgrades, restore drills).

Heads up: those three URLs return a 404 unless you are signed in to a jeffreys-skills.md account with an active subscription. If you hit a 404, sign up (or log in) at jeffreys-skills.md/dashboard first, then reload — the same account is what the jsm CLI authenticates against below, so doing this step first means jsm install will already know who you are.

Three ways to install. Pick whichever matches the path you chose above.

Recommended: via jsm (Jeffrey’s Skills.md)

# macOS / Linux
curl -fsSL https://jeffreys-skills.md/install.sh | bash
# Windows (PowerShell as Admin)
irm https://jeffreys-skills.md/install.ps1 | iex

jsm setup                        # first-time wizard: creates config, picks skill dirs
jsm login                        # opens browser → sign in with Google
jsm install slack-migration-to-mattermost-phase-1-extraction
jsm install slack-migration-to-mattermost-phase-2-setup-and-import

Restart the Claude Code and/or Codex desktop app (or claude / codex) and the skills show up in the picker. jsm downloaded a verified copy of each skill, unzipped into ~/.claude/skills/ and ~/.codex/skills/, checked the hash matches what the server published, and recorded the version in a local database.

Alternative: via claude plugins

claude plugins install slack-migration-to-mattermost-phase-1-extraction
claude plugins install slack-migration-to-mattermost-phase-2-setup-and-import

Alternative: symlink from a local clone (developers only)

ln -s /path/to/je_private_skills_repo/.claude/skills/slack-migration-to-mattermost-phase-1-extraction  ~/.claude/skills/
ln -s /path/to/je_private_skills_repo/.claude/skills/slack-migration-to-mattermost-phase-2-setup-and-import ~/.claude/skills/
# mirror to Codex too:
ln -s /path/to/je_private_skills_repo/.claude/skills/slack-migration-to-mattermost-phase-1-extraction  ~/.codex/skills/
ln -s /path/to/je_private_skills_repo/.claude/skills/slack-migration-to-mattermost-phase-2-setup-and-import ~/.codex/skills/

On Windows (Git Bash or PowerShell 7+ as Admin), use mklink /D or New-Item -ItemType SymbolicLink.

Verify

jsm list                          # lists installed skills + versions
ls -la ~/.claude/skills/ | grep slack-migration
# Windows:
dir %USERPROFILE%\.claude\skills

§1.3

Bootstrap the workstation for Phase 1

Installs the underlying CLI tools the skill shells out to: slackdump does extraction, mmetl does transformation, mmctl does import upload, and so on.

cd ~/.claude/skills/slack-migration-to-mattermost-phase-1-extraction
./scripts/doctor.sh                    # what's missing?
./scripts/bootstrap-tools.sh           # install missing system + Go tools
./scripts/doctor.sh                    # confirm all required checks are green

Platforms covered automatically: macOS uses Homebrew (and installs Homebrew first if missing); Ubuntu/Debian/WSL uses apt; Windows prints a Chocolatey checklist. Installed: python3, jq, zip, unzip, curl, rsync, git, sha256sum, go, then the Go tools (slackdump, slack-advanced-exporter, mmetl, mmctl) into $(go env GOPATH)/bin, plus the Python packages requests and beautifulsoup4.

If something goes wrong

command not found: ./scripts/doctor.sh → you forgot the cd, or the skills dir is elsewhere. Find it with jsm list.
permission denied → run chmod +x scripts/*.sh inside the skill dir, then retry.
One Go install fails (bad network, yanked release) → the script warns and continues. Re-run once network cooperates.
Windows permission errors → open PowerShell as Administrator.

§1.4

Bootstrap the workstation for Phase 2

cd ~/.claude/skills/slack-migration-to-mattermost-phase-2-setup-and-import
./scripts/doctor.sh                       # what's missing?
./scripts/bootstrap-tools.sh              # install workstation-side tools
./scripts/doctor.sh --require-remote      # probe SSH to your target once TARGET_HOST is set

Phase 2 needs mmctl, jq, psql, ssh, scp, rsync, openssl, and the Python requests module. On macOS it will nudge you to add $(brew --prefix)/opt/libpq/bin to your PATH so psql is runnable after a fresh libpq install. --require-remote confirms your SSH key is on the target and ssh -o BatchMode=yes works. Run this right before ./operate.sh provision / deploy.

§1.5

Wire up MCP servers (optional but recommended)

The skills ship installers that register Slack / Playwright / Mattermost MCP servers into whichever agent CLIs you have.

# Phase 1 (workstation)
./scripts/install-mcp-servers.sh
./scripts/doctor.sh --require-mcp

# Phase 2 (workstation)
./scripts/install-mcp-servers.sh
./scripts/doctor.sh --require-mcp

MCP	When it helps	Phase
Slack MCP (Anthropic official, xoxb-)	“count channels”, “verify last message in #general”, “check user U0ABC’s email”	Phase 1
Slack MCP stealth (korotovsky, xoxc- + xoxd-)	full visibility including DMs for gap-fill verification	Phase 1
Playwright MCP	drives the Slack admin UI’s export flow, or Mattermost System Console screens that lack API equivalents	Phase 1 + 2
Mattermost MCP (community, admin PAT)	“which users are inactive”, “stamp a test post”, “list team roles”	Phase 2

You do not need any of these for the skill itself to run. They are accelerators for verification, gap-hunting, and UI steps. See the §MCP worked examples section later for concrete prompts.

Part 2 · pre-flight

Before you touch Slack.

Three things need to be decided before your first ./migrate.sh export call. Spending 20 minutes on these now saves hours downstream.

§2.1

Slack plan tier and export privileges

Log into Slack as an owner/admin and open Workspace Settings → Security → Import & export data. The export page tells you which scope you’re authorized for:

Free or Pro: public channels only. Private channels, DMs, and group DMs cannot be exported via the official path. Phase 1 routes you into Track B (slackdump as primary) and emits an explicit unresolved-gaps.md listing the private content it can’t pull.
Pro with legal exception: Workspace Owners can apply to Slack for full export under “valid legal process, consent of members, or a requirement under applicable laws.” If granted → Track A.
Business+ or Enterprise Grid: full content export of public, private, and DM is available. Track A is the default path.

Write down the answer. The value goes into config.env as SLACK_PLAN_TIER and controls several downstream validators.

§2.2

Scope of the export

Default: full history from workspace creation to now. Before you commit:

Is there content legal has told you must not be exported? (A private HR channel whose members did not consent, for example.) Exclude those channels via Slack admin before the export, or accept them and redact post-export.
Are there moribund channels older than your retention policy that you’d rather never import? Leave them in Slack and skip them in the Mattermost archive-channel mapping.
Is the export size going to blow past the server’s disk budget? Rule of thumb: plan for 3× the compressed Slack export size of free disk. For many years of heavy attachments, use split-phase1-import.py (per-year batch ZIPs).

§2.3

Server sizing

Mattermost’s official 1000-user recommendation is 4 vCPU / 8 GB RAM / 90–180 GB storage. That’s bare-minimum. Real production wants headroom:

User count	Target hardware	Hetzner	OVH	Contabo	Est. $/mo
Up to 50	2 vCPU / 4 GB / 80 GB SSD	AX21 or small VPS	VLE-4	VPS M	$10–20
50–250	4 vCPU / 16 GB / 250 GB NVMe	AX42 / CCX23	Advance-1	VPS L	$40–60
250–1000	8 cores / 64 GB / 2×1 TB NVMe RAID 1	AX52 (recommended)	Advance-2	VPS XL	$65–90
1000+	8–16 cores / 64–128 GB, separate PG	AX52 + Supabase Pro	Advance-2 + managed PG	enterprise	$100–300+

Pick AX52 at Hetzner as the default for anything 250–1,000 users — by far the cheapest dedicated-bare-metal-with-NVMe option in that class. Put Ubuntu 24.04 LTS on it. Ordering the server is the one step the agent cannot do for you.

Four values go into config.env.phase2 when the agent asks; you’re picking a name, not doing setup:

Field	What	Notes
DOMAIN	Typically chat.yourdomain.com	Add to Cloudflare if not already there (§Cloudflare walkthrough).
SMTP	Mailgun, Postmark, SES, or Google Workspace relay	Sign up for a provider; the agent wires credentials into Mattermost. Users can’t log in without password-reset emails.
ADMIN_EMAIL	A mailbox you own	The agent creates the Mattermost admin account during deploy. Password is generated; store in 1Password.
ROLLBACK_OWNER	A named human (can be yourself)	Phase 2 refuses cutover without this set, so it’s enforced.

§2.4

How you drive the skill

The rest of this guide shows commands like ./migrate.sh export or ./operate.sh cutover. Those are the scripts the skill runs; you almost never type them yourself. Ask the agent, in plain English, to run the next stage.

Shortcut: hand the agent the guide

Open your Claude Code or Codex session in your working directory and paste something like:

“Read this guide end-to-end: /slack-mattermost-migration-guide.md. Then read the Phase 1 and Phase 2 skills. I’m planning a migration for [company name, user count, Slack plan tier]. Walk me through what I need to do before we start (server, domain, SMTP, tokens), then plan the full sequence of stages with me.”

The agent produces a tailored checklist, tells you which tokens to collect, and pauses before each destructive step. Download the guide with the button near the top of this page.

§2.4 · cont.

The pause-and-confirm pattern

Both Claude Code and Codex pause before any action that touches a server (SSH, DB writes, HTTP POST to Mattermost) and ask you to approve it. Read the command carefully before you approve, especially during Phase 2 cutover.

When to say yes to a permission prompt

Non-technical operator cheat-sheet

Looks like	Decision
./migrate.sh <stage> / ./operate.sh <stage> matching the stage you asked for	Approve
ssh <user>@<your TARGET_HOST>	Approve (confirm hostname matches config.env)
mmctl <anything> --url https://<your MATTERMOST_URL>	Approve (confirm URL is yours)
curl to jeffreys-skills.md / hetzner.com / cloudflare.com / your own domain	Approve
sudo apt install <package> during bootstrap-tools.sh or provision	Approve
psql / pg_dump / pg_restore against $POSTGRES_DSN or $SCRATCH_DB_URL	Approve
rm -rf /opt/mattermost or delete outside workdir/	Deny and ask why
ssh <some unknown hostname>	Deny
Anything reading ~/.ssh/id_* and piping somewhere	Deny and investigate
git push to a remote you didn’t set up	Deny
Anything right after the agent has seemed confused	Deny and re-read prompt

When in doubt, type: “Explain what this command does and why you’re running it at this stage.” The agent will tell you.

Keep your laptop awake

During long stages

Phase 1 enrich and Phase 2 staging / cutover can run 30–120 min. If your laptop sleeps mid-run, the SSH session dies and the stage aborts.

# macOS — separate Terminal tab, leave running
caffeinate -dims

# Windows — PowerShell as Admin
powercfg /requestsoverride process powershell.exe DISPLAY SYSTEM AWAYMODE
# reverse when done
powercfg /requestsoverride process powershell.exe

# Simplest: plug in, disable sleep for the migration week, re-enable after

The two-phase pipeline

Phase 1 → handoff → Phase 2.

Both skills expose an ordered list of stages. You don’t typically run them all at once. Most operators step through stage by stage and read the reports between each, because the reports are where the decisions live — what was exported, what’s on disk, whether reconciliation counts line up, whether the staging rehearsal passed. Tap any node or edge below to see what it actually does.

Part 3 · Phase 1

Driving Phase 1 — extraction and transformation.

The canonical Phase 1 pipeline:

setup  ->  export  ->  enrich  ->  transform  ->  package  ->  verify  ->  handoff

You can run ./migrate.sh all to chain the whole thing; in practice most operators step through stage by stage and read the reports between each.

§3.1

Set up the working directory (stage: setup)

Pick a working directory with plenty of disk. For a 50-user workspace, 50 GB free is enough. For 1,000 users with heavy file attachments, assume 500 GB to 1 TB.

mkdir -p ~/slack-migration/acme
cd ~/slack-migration/acme
cp ~/.claude/skills/slack-migration-to-mattermost-phase-1-extraction/config.env.example ./config.env
$EDITOR config.env

Minimum fields for a Business+ / Track A run:

WORKSPACE_NAME="acme-slack"
SLACK_PLAN_TIER="Business+"
PHASE1_WORKSPACE_ROOT="./workdir"
MATTERMOST_TEAM_NAME="acme"
MATTERMOST_TEAM_DISPLAY_NAME="Acme Corp"

# Fill one of these two blocks:
# (A) official export — paste the path to the downloaded ZIP here.
SLACK_EXPORT_ZIP=""
SLACK_CHANNEL_AUDIT_CSV=""
SLACK_MEMBER_CSV=""
# (B) slackdump-primary — fetch tokens from a logged-in browser session.
# SLACK_TOKEN="xoxp-..."     # slack app user token, for enrichment API calls
# SLACKDUMP_PRIMARY="1"

Then run ./migrate.sh setup (or ask the agent to do it). This creates the workdir/artifacts/{raw,enriched,import-ready,reports}/ tree the rest of the pipeline expects, and re-runs doctor.sh-style tool checks so you find out now if something is missing.

§3.2

Acquire the Slack export (stage: export)

Three possible paths — work out which one you’re on, then execute.

3.2.1

Track A — official admin export (recommended when available)

Slack has no public API to trigger a workspace export; it’s a UI-only operation. Three sub-paths past that:

Agent-driven via Playwright MCP (recommended). If the Playwright MCP is registered, ask the agent: “Open the Slack admin export page and kick off an export for the full date range. Wait for the email, grab the download URL, and pull the ZIP into artifacts/raw/.” The agent opens a browser session, clicks through, waits for mail, completes intake. You approve browser-control permission once.
Automated via SLACK_EXPORT_AUTOMATION=1. Set a Slack session cookie in config.env and point the skill at an IMAP mailbox; automate-official-export.py does the POST, polls for the email, downloads the ZIP, hashes, writes provenance. This is the path for recurring baseline+delta cadences.
Fully manual. Click through the Slack admin UI yourself, wait, download, tell the agent where you saved it. The agent runs ./migrate.sh export to hash and write manifest.raw.json.

Regardless of which sub-path, the working directory ends up with:

workdir/artifacts/raw/
├── slack-export.zip           # hashed
├── channel-audit-YYYY-MM-DD.csv   # hashed
├── member-list-YYYY-MM-DD.csv     # hashed (if available)
└── manifest.raw.json          # names every file + its SHA256

3.2.2

Track B — slackdump as primary (Pro / Free, or official unavailable)

Set SLACKDUMP_PRIMARY=1 in config.env. Obtain either a Slack App xoxp- user token (preferred) or extract xoxc- / xoxd- session cookies from a logged-in browser (AUTHENTICATION.md has the Chrome DevTools steps). Then:

./migrate.sh export

This is a partial view: slackdump can only see what the logged-in account can see. Private channels the account is not a member of, DMs the account is not a party to, and messages in channels predating the account’s join date are all invisible. The skill captures this reality in unresolved-gaps.md later; your job now is to run the export and not pretend it sees more than it does.

3.2.3

Track C — Enterprise Grid with per-workspace export

Grid admins can request grid-wide (one giant file) or per-workspace exports. Per-workspace is cleaner. If you get a grid-level export, split-phase1-import.py + ENTERPRISE-GRID-WORKSPACE-SPLIT-WORKFLOW.md handles splitting it for you.

Common to all tracks

Channel-audit CSV, member list, workflows

Both CSVs are downloadable from Workspace settings → Security. Download at the same time as the ZIP and put paths into SLACK_CHANNEL_AUDIT_CSV and SLACK_MEMBER_CSV. The channel-audit CSV is what the reconciliation validator uses to cross-check channel counts; without it the validator warns but cannot block. The member-list CSV preserves SSO-linked email addresses.

Workflow Builder JSON: individually exportable from Settings → Workflows. No bulk export. For each workflow that still matters, export it and drop it into a directory referenced by PHASE1_WORKFLOW_INPUTS so extract-phase1-sidecars.py preserves it. Workflows cannot be imported to Mattermost automatically; they are preserved as archival artifacts and later rebuilt as Mattermost Playbooks or slash commands post-cutover.

§3.3

Enrich the export (stage: enrich)

Official Slack exports contain file links, not the files themselves, and those links expire. The enrich stage downloads every url_private referenced in the export and bakes the bytes into the enriched ZIP so your imported Mattermost doesn’t end up with a sea of dead attachment placeholders. The agent runs this unattended; for a typical workspace it’s 1–6 hours of background downloading.

./migrate.sh enrich

What runs under the hood:

run-slack-advanced-exporter.sh fetch-emails — resolves Slack user IDs to email addresses, rewriting users.json in place inside a copy of the ZIP. Requires xoxp- with users:read.email.
run-slack-advanced-exporter.sh fetch-attachments — walks every message’s files[] and downloads bytes into __uploads/F<id>/<filename> inside the enriched ZIP. Requires xoxp- with files:read.
export-custom-emoji.py — hits Slack’s emoji.list API, downloads every custom emoji image, writes a manifest plus an alias map.
extract-phase1-sidecars.py — pulls canvases, lists, integration_logs.json, and any admin CSV / workflow JSON from PHASE1_SIDECAR_INPUTS or PHASE1_WORKFLOW_INPUTS into a sidecar bundle.
build-artifact-manifest.py — rewrites manifest.enriched.json with hashes for all new artifacts.

The ordering matters. Emails before attachments because mmetl uses the email-rewritten users.json to generate user records. Attachments before sidecars because the sidecar extractor wants to know what was covered natively so it doesn’t duplicate.

When this stage finishes, run scripts/validate-enrichment-completeness.py --archive workdir/artifacts/enriched/slack-export.enriched.zip --output-json /tmp/enrich.json and read the report. A non-empty missing_file_references array (the operator cards call this “attachments_missing”) means a file was referenced but could not be downloaded, usually because it had already expired or the account lost access. Decide per-file whether acceptable (mark as unrecoverable gap) or worth re-running.

§3.4

Transform to Mattermost bulk-import format (stage: transform)

./migrate.sh transform

Runs mmetl check slack (which exits non-zero if the ZIP is corrupt or has a version Slack changed under you) and then mmetl transform slack with flags needed to produce JSONL output plus a data/bulk-export-attachments/ directory. Key flags the skill sets:

--team "$MATTERMOST_TEAM_NAME" — target team name.
--default-email-domain — only if MMETL_DEFAULT_EMAIL_DOMAIN is set (use when some Slack users have no email; mmetl fabricates <username>@<domain>).
--skip-empty-emails, --discard-invalid-props — passed via MMETL_EXTRA_FLAGS if needed.
--attachments-dir data/bulk-export-attachments — forces binary files into the canonical import location.

Important: mmetl is Linux and macOS only. Running it on Windows corrupts the JSONL. The bootstrap script doesn’t install a Windows binary for this reason. If you’re on Windows, either use WSL or run Phase 1 on a Mac/Linux machine and SCP the result.

§3.5

Patch and package (stage: package)

mmetl gets you close but not all the way. Three things still need patching into the JSONL:

Custom emoji objects (must go before the first team line).
Archive channels for sidecar content (slack-canvases-archive, slack-lists-archive, slack-export-admin), and a post per canvas, list, or admin artifact that attaches the sidecar file.
User membership into those archive channels (otherwise no one can see them in Mattermost).

./migrate.sh package

Runs patch-phase1-import.py (does the above) and package-phase1-import.py (zips the JSONL + attachments tree + emoji images + sidecars into mattermost-bulk-import.zip and writes manifest.import-ready.json). Archive channel names are configurable via PHASE1_SIDECAR_CHANNELS; the default is the three listed above. You can also pick a specific PHASE1_ARCHIVE_USER as the author of sidecar posts (defaults to the first admin in the export).

§3.6

Verify and build the evidence pack (stage: verify)

This is the most important stage because it catches silent data loss.

./migrate.sh verify

It runs five validators:

validate-phase1-artifacts.py — hashes in manifest.*.json match files on disk; required artifacts (ZIP, CSV, JSONL, final ZIP) all exist.
validate-phase1-jsonl.py — JSONL is well-ordered (version, emoji, team, channel, user, post, direct_channel, direct_post), every thread_ts reference is to an earlier post, every channel has at least one member, counts are non-zero.
validate-enrichment-completeness.py — every files[] entry in the enriched ZIP has a downloaded binary; every user in users.json has an email (or a documented exception).
reconcile-phase1-counts.py — message counts across raw ZIP, enriched ZIP, channel-audit CSV, and JSONL all agree within tolerance. Channels in the audit CSV but missing from the JSONL are reported as discrepancies with severity.
export-integration-inventory.py — parses integration_logs.json and emits integration-inventory.md, a concrete list of bots, webhooks, and apps that must be rebuilt in Mattermost post-cutover.

Then it assembles the evidence pack (build-migration-evidence-pack.py) and runs the secret scanner (scan-and-redact-migration-secrets.py) across workdir/artifacts/reports/ and config.env. A non-zero exit from the scanner means it found a secret somewhere in generated reports; decide whether to redact and re-share or accept.

Open workdir/artifacts/reports/verification.md and read it. If any reconciliation line item is red, stop and resolve it before handoff. Phase 2 rejects a handoff with unresolved criticals; fixing it now is easier than fixing it mid-cutover.

§3.7

Handoff (stage: handoff)

./migrate.sh handoff

Emits the three artifacts Phase 2 needs to trust your bundle:

handoff.md — human-readable summary for you and the war room.
handoff.json — the machine-readable contract. Contains schema_version, generated_at, workspace, plan_tier, export_basis, final_package.path, final_package.sha256, jsonl_path, manifests[], counts (users, channels, posts, DMs, emoji, attachments), sidecar_channels[], and known_gaps[].
unresolved-gaps.md — one entry per classified gap, each with disposition class (native-importable / sidecar-only / manual-rebuild / unrecoverable).

The final ZIP is at workdir/artifacts/import-ready/mattermost-bulk-import.zip. Its SHA-256 is in manifest.import-ready.json and, crucially, also in handoff.json.final_package.sha256. Phase 2 refuses to import a ZIP whose hash does not match the handoff’s claimed hash, no matter how close the other metadata is.

Part 4 · Phase 2

Driving Phase 2 — deploy, rehearse, cut over.

Phase 2 runs from the same workstation as Phase 1. It does not need the Phase 1 ZIP to still exist on disk as long as HANDOFF_JSON points at a readable location with the final ZIP reachable from there.

Setup

Open a fresh session, copy the config

cd ~/slack-migration/acme
cp ~/.claude/skills/slack-migration-to-mattermost-phase-2-setup-and-import/config.env.example ./config.env.phase2
echo "HANDOFF_JSON=$(pwd)/workdir/artifacts/reports/handoff.json"    >> ./config.env.phase2
echo "IMPORT_ZIP=$(pwd)/workdir/artifacts/import-ready/mattermost-bulk-import.zip" >> ./config.env.phase2
$EDITOR ./config.env.phase2

export PHASE2_CONFIG=./config.env.phase2

Minimum fields for a typical VPS deployment with self-hosted PostgreSQL on the same box:

WORKSPACE_NAME="acme-slack"
PHASE2_WORKSPACE_ROOT="./workdir-phase2"
HANDOFF_JSON="<abs path>"
IMPORT_ZIP="<abs path>"

MATTERMOST_URL="https://chat.acme.com"
MATTERMOST_ADMIN_USER="admin"
MATTERMOST_ADMIN_PASS="<strong random password>"
MATTERMOST_TEAM_NAME="acme"

TARGET_HOST="chat.acme.com"
TARGET_SSH_USER="root"
DEPLOY_METHOD="apt"          # "apt" for production, "docker" for staging
PROVISION_MODE="ssh"
DEPLOY_MODE="ssh"

POSTGRES_DSN="postgres://mmuser:<pwd>@localhost:5432/mattermost?sslmode=disable"
SMOKE_DATABASE_URL="${POSTGRES_DSN}"

SMTP_SERVER="smtp.postmarkapp.com"
SMTP_PORT="587"
SMTP_USERNAME="<postmark-token>"
SMTP_PASSWORD="<postmark-token>"
SMTP_TEST_EMAIL="admin@acme.com"

CLOUDFLARE_ENABLED="1"
CLOUDFLARE_MODE="plan"                # "plan" prints, "execute" uses CF API
CLOUDFLARE_API_TOKEN="<zone edit token>"
CF_ZONE_ID="<zone id for acme.com>"
ORIGIN_SERVER_IP="<IP address>"

ROLLBACK_OWNER="Jane Admin"

Then the Phase 2 pipeline:

intake  ->  render-config  ->  edge  ->  provision  ->  deploy  ->  verify-live
        ->  staging  ->  restore  ->  ready  ->  cutover

§4.1

Intake the Phase 1 handoff (stage: intake)

./operate.sh intake

Runs build-phase2-intake-manifest.py (snapshots the handoff + final ZIP to the Phase 2 workdir and hashes them) and validate-phase2-intake.py (verifies handoff.json is well-formed, the hash claimed inside matches the ZIP on disk, and the sidecar channel list is explicit). Output: workdir-phase2/reports/phase2-intake-report.json.

If this fails, do not force through. Typical failure modes:

The ZIP moved between phases and the hash no longer matches → re-copy or re-run Phase 1’s handoff.
sidecar_channels[] is empty but Phase 1 produced sidecars → bug in Phase 1 config. Re-run ./migrate.sh handoff.

§4.2

Render config (stage: render-config)

./operate.sh render-config

Emits workdir-phase2/rendered/config.json (Mattermost server config), workdir-phase2/rendered/mattermost.nginx.conf (Nginx vhost), and workdir-phase2/reports/config-validation.json. Key settings the import needs:

SiteURL = $MATTERMOST_URL
ListenAddress = 127.0.0.1:8065 (never exposed directly)
SqlSettings.DataSource = $POSTGRES_DSN
MaxPostSize = 16383 (Slack allows 40000; default 4000 would truncate)
MaxFileSize = 52428800 (50 MB)
EnableOpenServer = true (required for bulk import to create users)
EnableSignUpWithEmail = true + RequireEmailVerification = false
SMTP block from $SMTP_*
AllowCorsFrom = whatever you put in ALLOW_CORS_ORIGINS if fronted by multiple hostnames

§4.3

Cloudflare edge (stage: edge)

./operate.sh edge

Only runs if CLOUDFLARE_ENABLED=1. In plan mode it prints the DNS records and origin-CA cert it would create. In execute mode (requires an Edit-scoped CLOUDFLARE_API_TOKEN) it calls the Cloudflare API to:

Create/update chat.acme.com A record pointing at $ORIGIN_SERVER_IP, orange-clouded.
Generate a 15-year Cloudflare Origin CA certificate for chat.acme.com, save to workdir-phase2/rendered/origin.{pem,-key.pem}.
Optionally create a second grey-clouded calls.acme.com for the Calls plugin’s UDP 8443 traffic.

§4.4

Provision the host (stage: provision)

./operate.sh provision

Generates provision-host.sh (plan script) and in ssh mode executes it over SSH against TARGET_HOST. What the plan does:

apt-get install -y curl jq nginx ufw fail2ban unattended-upgrades postgresql-client (or postgresql too when local PG is provisioned).
Opens UFW for 22/tcp, 80/tcp, 443/tcp, 8443/udp (Calls). Enables UFW.
Enables fail2ban and unattended-upgrades.
If local Postgres is provisioned, creates the Mattermost role + database from the DSN credentials.

Runs in plan mode first (just prints the script) if you want to eyeball it. ssh mode reads the DSN envs, packages them into a one-shot bash invocation, and pipes the plan script over SSH. The target must have Python3.

§4.5

Deploy Mattermost + Nginx (stage: deploy)

./operate.sh deploy

Runs deploy-mattermost-stack.sh in whichever mode you set. For APT:

curl -o- https://deb.packages.mattermost.com/repo-setup.sh | bash -s mattermost
apt-get install -y mattermost nginx
Install rendered config.json to /opt/mattermost/config/config.json with 0600 mattermost:mattermost.
Install rendered mattermost.nginx.conf to /etc/nginx/sites-available/, symlink, install origin cert + key if present.
nginx -t then systemctl enable --now nginx and systemctl enable --now mattermost.

Ubuntu 25.10 workaround: the Mattermost APT package isn’t available there yet. Fall back with DEPLOY_METHOD=docker and re-run. Docker is not recommended for production HA (Mattermost’s own docs say so); use APT for anything that needs to scale beyond a single node.

§4.6

Verify live stack (stage: verify-live)

./operate.sh verify-live

Three HTTPS probes, 6 retries, 5 s apart to absorb JIT startup:

GET /api/v4/system/ping → expect 200 + JSON {"status":"OK"}.
WebSocket upgrade against /api/v4/websocket → expect 101 Switching Protocols.
SMTP reachability: TCP connect to $SMTP_SERVER:$SMTP_PORT + STARTTLS negotiation.

If CLOUDFLARE_ENABLED=1, also runs verify-cloudflare-edge.py which checks DNS A record resolves and is proxied, Cloudflare TLS offers a Cloudflare-issued cert (traffic goes through CF), origin cert is installed and not expired, and calls.yourdomain.com (if set) is DNS-only.

Typical failures: WebSocket fails → Nginx config missing the <Mono>Upgrade</Mono>/<Mono>Connection: upgrade</Mono> block; SMTP fails → provider blocks port 587 for new accounts or credentials are wrong (test with swaks to isolate).

§4.7

Staging rehearsal (stage: staging)

./operate.sh staging

This is the single most valuable stage in Phase 2. Safety: run-staging-rehearsal.sh refuses to run against a URL that looks like production unless ALLOW_NON_STAGING=1. Default heuristic: URL is localhost, 127.0.0.1, or contains the string “staging”.

Recommended staging path

A second cheap VPS that mirrors production at ~$4–10/mo, kept alive only for the rehearsal window.

Order a staging VPS (Hetzner CX22 €4/mo, Contabo VPS S $4/mo, OVH VLE-1). Ubuntu 24.04, same SSH key.
Add a DNS record for staging.chat.yourcompany.com pointing at the VPS’s IP (grey-clouded fine).
Copy your production config to config.env.phase2.staging and override: STAGING_URL, TARGET_HOST, MATTERMOST_URL.
Run the full Phase 2 pipeline: PHASE2_CONFIG=./config.env.phase2.staging ./operate.sh intake render-config provision deploy verify-live staging.
After cutover is confirmed green on production, cancel the staging VPS. Total cost ~<$10 for a full-scale dress rehearsal.

What it does: mmctl auth login with admin creds → mmctl import upload streams the final ZIP onto the server → mmctl import list available --json → mmctl import process <filename> kicks off the job → monitor-import.sh polls mmctl import job show --json every few seconds, writing one JSONL line per poll to import-watch.*.jsonl, until job hits success or error. Post-import smoke tests: run-import-smoke-tests.py hits PostgreSQL directly and counts users, channels, posts. reconcile-handoff-vs-import.py compares against handoff.json.counts. Anything missing is logged as a discrepancy.

§4.8

Restore drill (stage: restore, optional but recommended)

./operate.sh restore

Before cutover, prove that your backup strategy works. Configure BACKUP_PATH and SCRATCH_DB_URL (a different Postgres you can safely restore into). The script runs pg_restore into the scratch DB and reports on success. An un-restored backup is not a backup; it’s wishful thinking. Do the drill.

§4.9

Compute readiness (stage: ready)

./operate.sh ready

Runs validate-cutover-readiness.py, generate-readiness-score.py, and generate-phase2-readiness.py to produce the fail-closed gate covered in the next section.

§4.10

Cutover (stage: cutover)

Only run after ready says green and the war room has explicitly called go.

./operate.sh cutover

Under the hood, execute-production-cutover.sh runs the same import-upload-process-monitor loop as staging, plus:

Post-import smoke (against production DB).
Reconciliation vs. handoff (production observed counts).
Activation proof: if SMTP_TEST_EMAIL is set, triggers a password-reset flow against the live Mattermost and confirms the email arrives with a reset link that resolves to https://chat.acme.com/reset_password.

Outputs land in workdir-phase2/reports/cutover/ as timestamped files. The final cutover-status.<timestamp>.json.status (grab the newest with ls -t workdir-phase2/reports/cutover/cutover-status.*.json | head -1) is success or failed. Activation proof lands in workdir-phase2/reports/latest-activation.json.

Rollback:

ROLLBACK_CONFIRMATION="I_UNDERSTAND_THIS_RESTORES_BACKUPS" ./operate.sh rollback

The phrase is required verbatim by rollback-cutover.sh. The script refuses to run without it, on purpose: rollback restores the DB and optionally /opt/mattermost/config and /opt/mattermost/data, which is destructive.

An asymmetric bet.

The single most important property of this whole migration, and the reason it is worth running even if you are a little skeptical: your real Slack keeps working the entire time. You never touch it until you have independently verified Mattermost is good.

You order a Hetzner server. The agent sets it up and imports your history into it. You run a full staging rehearsal on a throwaway copy. Slack is untouched.

You log into the new Mattermost yourself, click around, read your DMs, spot-check the big channels. Still untouched.

You optionally activate a few volunteers on Mattermost and let them use both in parallel for a few days. Slack is still source of truth.

Only when you are satisfied do you flip Slack to read-only and do the final cutover. Even then, Slack stays accessible as a read-only archive until you choose to downgrade or cancel.

If anything goes wrong at any point before cutover, you cancel the Hetzner server, delete the workdir on your laptop, and you are out the price of a few weeks of server rent and a month of Postmark. Your Slack workspace is unaffected, because the migration never wrote to it: Phase 1 only ever read from Slack; Phase 2 only ever wrote to the new server. There are no Slack credentials in Phase 2's config at all.

That is the asymmetric bet. Downside is small and recoverable. Upside is tens of thousands of dollars a year, indefinitely.

What survives the move.

The question every internal stakeholder will ask — legal, HR, the people who ran Slackbot automations, the guy with four hundred saved items — is some variant of “does my X survive?” There are three possible answers, and the skill classifies each Slack feature into exactly one of them. Native means it imports as first-class Mattermost data: public and private channel messages, DMs, threads, reactions, file attachments, pinned messages, channel topics, custom emoji images. Sidecar means the content is preserved, but as posts in a dedicated archive channel rather than as native Mattermost objects — canvases, lists, and admin audit CSVs all end up this way. Unrecoverable means the content is genuinely not in Slack’s export and cannot be migrated; the best you can do is document it in unresolved-gaps.md, which the skill generates automatically, and plan a rebuild or an acceptance.

The matrix below lets you filter by disposition and toggle between Business+ and Pro plans. On Business+, most things are native. On Pro, private channels and DMs downgrade because Slack's Free/Pro export simply cannot see content the export token's user is not a party to — you fall back to slackdump-primary and inherit that blind spot. The honest way to handle it is to write the blind spot into unresolved-gaps.md in advance, not to pretend the export sees more than it does.

The rule the skills enforce: known-unknowns named in advance are cheaper than unknown-unknowns discovered in production. Anything that doesn't survive as native, and can't be preserved as a sidecar, gets an entry with a classification — native-importable, sidecar-only, manual-rebuild, or unrecoverable — so that when a user says at T+3 days “where are my saved items?”, you already have the answer written down and a rebuild plan.

The fail-closed gate.

Production cutover is the moment when every bad decision earlier in the pipeline stops being recoverable for free. The skill treats it that way: the ready stage is a fail-closed gate between everything and the production import.

cutover-readiness.json

The gate reads every prior report plus one environment variable, and emits status: “ready” or status: “blocked”. There is no middle state. If any of the inputs below is missing or stale, it blocks.

phase2-intake-report.json
config-validation.json
live-stack.md
latest-staging.json
latest-smoke.json
latest-reconciliation.json
latest-restore.json
ROLLBACK_OWNER

The point of fail-closed is that ambiguity at cutover is catastrophic. If you cannot produce evidence that staging passed, the gate assumes staging failed. If you cannot name the rollback owner, the gate assumes no one is empowered to pull the trigger. That framing is not paranoid; it is the same principle as a safety-critical interlock in any other engineering domain.

There is a closely related rule, almost comically low-tech, that the skill enforces: the rollback owner must be a name and an email, populated into ROLLBACK_OWNER before the gate is allowed to pass. Not “whoever is on call.” Not a team alias. A specific human who has pre-committed to being the one who calls the abort. In practice this is usually the operator running the migration, or their CTO. The point is to remove ambiguity at the exact moment it would otherwise cost you.

§10.8

MCP worked examples — what each server unlocks.

You installed MCP servers back in §1.5. Here is what each one actually gives the agent, with concrete prompts you can paste.

Slack MCP (Anthropic official, xoxb-)

Read access while Slack is still alive

“Use the Slack MCP to count the total messages in #general over the last 90 days and compare to Phase 1’s channel-audit CSV for the same channel.”
“Use the Slack MCP to list every user whose email ends in @acme.com but who hasn’t posted in 6 months. I want to decide whether to exclude them from the migration.”
“Fetch the 3 most-recent messages in the support channel so I can compare them byte-for-byte after import.”

Slack MCP stealth (korotovsky, xoxc- + xoxd-)

Full visibility for gap-fill verification

“Via the stealth Slack MCP, confirm that my export ZIP includes all my own DMs with Bob. The export should contain X messages; tell me if anything’s missing.”

Playwright MCP

Drives a real browser for UI-only work

“Use Playwright MCP to log into Slack admin and start a workspace export for dates 2023-01-01 to 2026-04-15. Wait for the email, click the download link, save the ZIP to ~/Downloads/, and tell me its SHA256.”
“In the Mattermost System Console, use Playwright to toggle EnableOpenServer=false after the import finishes. I don’t want to hand-edit config.json just for this.”

Mattermost MCP (community, admin PAT)

Direct API access to live Mattermost

“Via the Mattermost MCP, how many users have activated (non-zero last_activity_at) and how many are dormant?”
“List every bot user on the new Mattermost, and for each one tell me whether it was present in Phase 1’s integration-inventory.”
“Create a test post in #migration-check as the admin user, then delete it. I’m verifying the admin PAT works.”

You do not have to use any of them. The skill runs end-to-end without them. They are accelerators for verification and one-off operator questions that would otherwise require hand-driven browsers or SQL.

§4.13

Cutover day, minute by minute.

The thing non-technical operators worry about most is the moment where the old and new systems switch. It is actually the most orchestrated, best-narrated part of the whole process, because the skill has been thinking about cutover since before it was written. Here is what it looks like on your screen.

At T minus sixty minutes, you paste a short sentence asking the agent to run ready one more time. The agent re-reads every report and emits a readiness score with each category graded green. At T minus fifteen, you flip Slack to read-only yourself, in a browser tab — this is a human-in-the-loop step on purpose — and post the freeze notice from the comms kit. At T equals zero, you paste: “Run Phase 2 stage cutover against production. Pause before any destructive step and explain it to me.”

The agent then asks for approval, one command at a time, in roughly this sequence: SSH sanity-check the service on the target, authenticate to Mattermost as admin, upload the bulk-import ZIP, list the uploaded filename, kick off the import job, tail the server log, count imported users, and confirm the ping endpoint still serves. Between upload and kickoff there is usually one last decision point; between kickoff and smoke-test there is fifteen to thirty minutes of the agent streaming JSON progress lines while you drink coffee.

Three things to internalize about the stream above. First: every single approval is an Approve once click, not an “Approve for the rest of the session” click. The approvals are cheap and the alternative is risky. Second: the import is idempotent, which is the reason you can re-run cutover if the network flakes at seventy percent. Mattermost de-duplicates posts by Slack message ID; a second run catches what the first missed without double-posting anything. Third: if anything goes sideways after the import job completes, rollback is one command with a deliberately annoying confirmation phrase baked in: ROLLBACK_CONFIRMATION=I_UNDERSTAND_THIS_RESTORES_BACKUPS. The verbatim phrase is required on purpose; rollback restores the DB from the pre-cutover dump and is not a thing you want to kick off accidentally.

Thirty minutes after cutover, you open a browser tab, navigate to https://chat.acme.com/reset_password, enter your own Slack email, click the link that arrives, set a password, and log in. Your whole history is already there. That is the single highest-confidence check, and it takes ninety seconds.

§4.11

The Slack → Mattermost cutover day sequence

When	What happens
T − 24 h	Freeze Slack integrations (deactivate bots that auto-post). Send first user announcement: “Tomorrow we move to Mattermost at 10 AM. Slack will go read-only at 09:30. Please log in at chat.acme.com/reset_password using your Slack email starting at 10:15.”
T − 1 h	Final Phase 1 delta export (see baseline+deltas below). Import is idempotent so re-running does not double-post; it only catches new messages.
T − 15 min	Make Slack read-only. In Slack admin: Workspace settings → Permissions → Messages & files → disable posting for everyone except admins.
T = 0	./operate.sh cutover
T + cutover end	Confirm the newest cutover-status.<ts>.json has status == "success". Send activation announcement.
T + 1 h	Monitor /opt/mattermost/logs/mattermost.log and help desk. Watch for bounced password-reset emails, locked-out users, broken mentions.
T + 1 day	Check activation count: mmctl user list --all --json \| jq 'length'. Nudge stragglers.
T + 7 days	Revoke Slack migration app tokens, delete the Slack admin app. Archive Phase 1 / Phase 2 workdirs to long-term storage as the evidence pack.

§4.12

Baseline + deltas pattern

For workspaces that take more than a day to export and transform, use the baseline-plus-deltas pattern:

Baseline: run the full Phase 1 pipeline at T − several days. Do the Phase 2 staging rehearsal. Do not do production cutover yet.
Delta N: every few hours or daily, re-run Phase 1 against the same path (or against a new export covering only the recent range). Run ./operate.sh staging against production; since import is idempotent, this catches new messages without duplicating old ones.
Final delta: at T = 0, one last Phase 1 + Phase 2 staging run. Then ./operate.sh cutover, which is now essentially a no-op import of any final messages.

Phase 1 ships DELTA-CADENCE-WORKFLOW.md documenting the scheduled export setup. Business+ also supports Slack-side scheduled recurring exports, which are the cleanest way to get deltas; turn that on and combine with SLACK_EXPORT_AUTOMATION=1.

§4.13 · Acme Corp, 340 users

What cutover day looks like on your screen

Here is what you’ll actually see in the Claude Code or Codex desktop app between T-1h and T+30min, assuming a 340-user workspace.

T − 60 min — preflight readiness re-check

You paste: “Run Phase 2 stage ready against production and show me the readiness score.” You see a log block: “Reading handoff.json... loaded. Checking latest-staging.json... status=success. Checking latest-smoke.json... counts match. Checking latest-reconciliation.json... diffs=[]. Checking ROLLBACK_OWNER... set to ‘Jane Admin’.” Final line: cutover-readiness.json.status = "ready". A rendered readiness-score.md with category scores (intake: 10/10, config: 10/10, etc.). All green.

If any category is yellow or red, the agent stops and tells you why. Do not proceed past this point with anything red.

T − 15 min — freeze Slack, post the notice

You do this yourself in a browser tab, not in the agent. Slack admin → Workspace settings → Permissions → Messages & files → disable posting for everyone except admins. Post the T-15m comms template (see §comms kit) into #general.

T = 0 — kick off the cutover

You paste: “Run Phase 2 stage cutover against production. Pause before any destructive step and explain it to me.” The agent asks for approval in roughly this sequence (exact count depends on config; expect 6–10):

Prompt	What it’s doing	Decision
ssh deploy@chat.acme.com 'sudo systemctl status mattermost'	Sanity-check Mattermost is up on target	Approve
mmctl auth login --url https://chat.acme.com …	Authenticate as sysadmin	Approve
mmctl import upload … 22-GB.zip	Stream the ZIP to the server	Approve
mmctl import list available --json	Read back what just landed	Approve
mmctl import process <filename>	Start the import job — moment of commit	Approve (destructive)
ssh deploy@chat.acme.com 'tail -f …/mattermost.log'	Tail server log for the import duration	Approve
psql "$POSTGRES_DSN" -c 'SELECT COUNT(*) FROM users'	Count imported users	Approve
curl -sf https://chat.acme.com/api/v4/system/ping	Verify Mattermost still serves	Approve

Between “import process” and “post-import count” is the longest wait. For a 340-user workspace with ~1.3 M posts, expect ~15–30 minutes. You’ll see a live stream of lines in the session:

{"ts":"...","state":"pending","progress":0}
{"ts":"...","state":"running","progress":0.12,"posts_imported":154000}
{"ts":"...","state":"running","progress":0.45,"posts_imported":578000}
...
{"ts":"...","state":"success","progress":1.0,"posts_imported":1284903}

Each line is written to workdir-phase2/reports/cutover/import-watch.*.jsonl so you can re-read them later.

T + ~20 min — reconciliation + activation

reconcile-handoff-vs-import.py: observed 337 users / 142 channels / 1284903 posts
                                 handoff 337 users / 142 channels / 1284903 posts
                                 status: ok (diffs: [])
activation: sending password-reset to admin@acme.com...
activation: reset_link_received = true (proof in latest-activation.json)
cutover-status.2026-04-22T14-31-04Z.json written
status: success

T + 30 min — confirm for yourself

New browser tab → https://chat.acme.com/reset_password → your own Slack email → click the link → set password → log in. You should see #general populated with your Slack history. Single highest-confidence check. ~90 seconds.

If any step fails

Three common failures

Error	Fix
mmctl import upload: 413 Request Entity Too Large	Nginx client_max_body_size is too small. Raise to client_max_body_size 25G; in /etc/nginx/sites-enabled/mattermost.conf and sudo systemctl reload nginx.
import job state=error note='user foo@bar.com invalid email'	A user record slipped through without a valid email (usually a bot). Either set MMETL_DEFAULT_EMAIL_DOMAIN in Phase 1 and re-run from transform, or manually delete that user from the JSONL and re-import.
activation: reset_link_received = false	SMTP not working. Test with swaks (see §SMTP walkthrough). Does not block cutover success, but users can’t activate. Fix and re-run only the activation helper.

What approvals look like in the UI

In Claude Code desktop

Each approval is a card with: command (grey monospace) + working directory + three buttons — Approve once, Approve for the rest of the session, Deny. Pick Approve once for each destructive step during cutover. “Approve for the session” is fine during enrich (idempotent, read-only to Slack), but risky during cutover (one approval then covers everything after, including things you haven’t seen the command for yet).

Part 5 · post-cutover week

Activation, integrations, backups, file storage.

The skills hand off a working Mattermost. Users still need to activate, integrations still need to be rebuilt, and ops still needs to converge.

§5.1

Activation

Users receive the password-reset link via $MATTERMOST_URL/reset_password. To track activation rate, paste into the agent:

“What’s the current activation rate on Mattermost? List users who still haven’t logged in.”

The agent runs the relevant mmctl user list query and gives you a count plus a list. Ask it to filter by team, date, or email domain for a narrower slice.

If activation is under 50% by T+48h, send a reminder (templates in §comms kit). If under 80% by T+7 days, paste:

“For everyone who hasn’t activated, generate a temporary password, then email each of them with their password and the login URL. Show me the list before you send.”

The agent generates passwords via mmctl user change-password, composes the emails, sends via your Postmark SMTP, and pauses for review before anything goes out. Enable the Calls plugin on day 1 if voice or video matters; it needs its own UDP 8443 and a DNS-only record for calls.acme.com (see references/CALLS-PLUGIN.md).

§5.2

Rebuilding integrations

workdir/artifacts/reports/integration-inventory.md is your checklist. Typical categories:

Incoming webhooks (Slack → Slack): recreate one Mattermost incoming webhook per Slack one. Update the sender service (GitHub, Datadog, etc.) to POST to the new URL.
Outgoing webhooks: same trigger words, new endpoint.
Slash commands: recreate. Mattermost’s trigger-word matching differs from Slack’s; test each one.
Bot users: Mattermost bot framework is fine, or use a personal access token for light use cases.
Custom apps: port to Mattermost’s Plugin API (Go-native) or Apps Framework (HTTP + manifest).

For each: add a line to a tracking doc, assign an owner, verify it works, close it out.

§5.3

Backups and monitoring

Set up pg_dump nightly and ship off-site (Hetzner Storage Box or Cloudflare R2). Example cron:

# on the server, as deploy user
cat > /home/deploy/backup-mattermost.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
DATE=$(date +%Y%m%d)
pg_dump -U mmuser mattermost | gzip > /var/backups/mattermost/mm_${DATE}.sql.gz
find /var/backups/mattermost -name 'mm_*.sql.gz' -mtime +30 -delete
rclone copy /var/backups/mattermost/mm_${DATE}.sql.gz r2:mm-backups/
EOF
chmod +x /home/deploy/backup-mattermost.sh
(crontab -l 2>/dev/null; echo "0 3 * * * /home/deploy/backup-mattermost.sh") | crontab -

Enable Mattermost metrics on port 8067, scrape with Prometheus, dashboard with Grafana (off-box, per Mattermost’s own recommendation). Add fail2ban alerts, UFW logs, and at least one “is chat.acme.com returning 200?” uptime check.

§5.4

File storage — local vs Cloudflare R2

Default is local at /opt/mattermost/data/. For production, consider switching to R2:

{
  "FileSettings": {
    "DriverName": "amazons3",
    "AmazonS3AccessKeyId": "<R2 access key>",
    "AmazonS3SecretAccessKey": "<R2 secret>",
    "AmazonS3Bucket": "mattermost-files",
    "AmazonS3Endpoint": "<accountid>.r2.cloudflarestorage.com",
    "AmazonS3Region": "",
    "AmazonS3SSL": true
  }
}

R2 pricing: ~$0.015 / GB / month storage, no egress fees. For a 1,000-user org uploading 10 MB / user / month, that’s $1.50 / month of storage plus $0 in egress. Worth it. Migrating existing local files to R2 post-cutover: either use Mattermost’s built-in mmctl migration (newer versions) or rclone from /opt/mattermost/data/ into the bucket.

Part 7

Operator checklist — print and keep on the desk.

§7.1

Two days before

./scripts/doctor.sh green on the workstation (Phase 1 and Phase 2).
./scripts/doctor.sh --require-remote green (can SSH non-interactively to the target).
./scripts/doctor.sh --require-mcp green, if you’re using MCP servers.
DNS A record for chat.acme.com exists (orange-clouded if Cloudflare).
Server ordered and SSH reachable as root.
SMTP provider set up; swaks test email arrived.
Slack plan tier known, export scope decided, legal approval in hand if needed.

§7.2

One day before

Full Phase 1 pipeline done once (baseline); handoff.json + final ZIP + evidence pack exist.
./operate.sh intake + render-config + provision + deploy + verify-live green.
./operate.sh staging green; staging-observed counts match handoff counts.
./operate.sh restore green (or explicitly waived by rollback owner).
./operate.sh ready returns "status": "ready".
First user announcement sent with cutover time + reset URL.
Help desk bucket / channel named; on-call owner identified.

§7.3

Cutover day

T − 1 h: freeze Slack (admin UI). Start final Phase 1 delta export.
T − 15 min: confirm ./operate.sh ready still green with the final handoff.
T = 0: ./operate.sh cutover. Watch the newest workdir-phase2/reports/cutover/cutover-status.*.json.
T + cutover: send activation announcement. Watch help desk.
T + 4 h: mmctl user list --all --json | jq 'length' + spot-check top channels.
T + 1 day: activation reminder if < 50 %.
T + 7 days: revoke Slack tokens, delete migration app, archive workdirs to evidence storage.

§7.4

If cutover fails

Do not try to fix in place under time pressure. Check the note field in the newest cutover-status.*.json.
If the issue is mechanical (stuck mmctl job, config typo), fix and re-run cutover; imports are idempotent.
If the issue is data loss or state corruption, roll back: ROLLBACK_CONFIRMATION=I_UNDERSTAND_THIS_RESTORES_BACKUPS ./operate.sh rollback. The rollback restores the DB to the pre-cutover backup.
Unfreeze Slack and tell users you’re rolling back; commit to a new date.

Part 6

Troubleshooting index.

§6.1

Phase 1

Symptom	Likely cause	Fix
./migrate.sh setup can’t find slackdump or mmetl	Go-based tools not on PATH	./scripts/bootstrap-tools.sh again; add $(go env GOPATH)/bin to shell rc
intake-official-export.py fails with “invalid ZIP”	Download truncated or is an HTML error page	Re-download from the admin-email link; verify size matches
slack-advanced-exporter fetch-emails returns 403	SLACK_TOKEN lacks users:read.email scope	Reinstall the Slack app with proper scopes, re-issue token
mmetl transform panics on some post	Rare Slack message schema quirk	Set MMETL_EXTRA_FLAGS="--discard-invalid-props" and re-run transform
Reconciliation shows channels in audit CSV but not JSONL	mmetl dropped them; usually archived channels with zero messages in the window	Classify as native-importable but empty, or extend the export window

§6.2

Phase 2

Symptom	Likely cause	Fix
./operate.sh intake fails “hash mismatch”	ZIP got re-zipped between phases	Re-copy the canonical ZIP from Phase 1’s import-ready/
./operate.sh deploy on Ubuntu 25.10: no mattermost package	Repo doesn’t have a questing build yet	Switch DEPLOY_METHOD=docker and re-run; Docker images cover all distros
verify-live WebSocket check fails	Nginx missing the Upgrade / Connection: upgrade block	Re-run render-config; confirm deploy copied the regenerated nginx conf
verify-live SMTP fails but provider says creds are right	Provider’s outbound port 587 blocked for new accounts	Test from the server: nc -vz $SMTP_SERVER 587. Use port 465 + SSL, or contact provider
Staging import stuck in pending for > 10 min	mmctl import worker crashed	Check /opt/mattermost/logs/mattermost.log. mmctl import job cancel <id> and re-process
Reconciliation shows fewer users than handoff claims	--skip-empty-emails dropped users without emails	Set a fallback MMETL_DEFAULT_EMAIL_DOMAIN in Phase 1 and re-run
Users report password-reset email lands in spam	SPF / DKIM / DMARC not set for sender domain	Add the records in Cloudflare DNS per your SMTP provider’s docs
Cutover succeeds but users say “I can’t see #general history”	They weren’t added to the channel during import	mmctl channel users add myteam general <username>; investigate why their user_id wasn’t in the JSONL’s channel membership

§6.3

Evidence and audit

If you need to produce evidence later (compliance, audit, or a “prove we migrated this channel” question), everything is already on disk:

workdir/artifacts/reports/evidence-pack.json (Phase 1) — hashed manifest of everything produced, with provenance.
workdir-phase2/reports/ (Phase 2) — intake, config, live-stack, staging, smoke, reconciliation, cutover, activation, readiness. Each has JSON and MD siblings.

Tar them, encrypt with age or gpg, store off-site for as long as your retention policy requires.

§10.7

Resuming an interrupted migration.

Migrations take hours to days. Laptops sleep, SSH sessions drop, Cloudflare glitches. Safe-resume playbook:

Single most important fact

Both ./migrate.sh <stage> and ./operate.sh <stage> are idempotent per stage. Re-running a stage is always safe unless noted below. The skill reads the existing artifact tree, notices what’s already done, and either short-circuits or re-derives.

How to figure out where you are

Ask the agent

“Read the Phase 1 resume.md prompt and follow it” (or the Phase 2 equivalent). The agent will:

Inspect workdir/artifacts/ or workdir-phase2/reports/ and enumerate what exists.
Read the latest-*.json convenience copies (latest-staging.json, latest-smoke.json, latest-reconciliation.json, latest-activation.json, latest-restore.json) plus the newest cutover-status.*.json if present, and tell you the last green stage.
Recommend exactly one next move.

Driving without the agent

Cheat sheet

Symptom	Last green stage	Next action
manifest.raw.json exists but no enriched/ dir	export	./migrate.sh enrich
enriched/slack-export.enriched.zip exists but no JSONL	enrich	./migrate.sh transform
mattermost-bulk-import.zip exists but no verification.md	package	./migrate.sh verify
handoff.json exists	handoff	Move to Phase 2 intake
Any cutover-status.*.json with "status":"success"	cutover done	Post-cutover operations

Not safely idempotent

Exceptions

./operate.sh cutover is idempotent (same post IDs don’t double-post), but re-running without re-running ready could miss server-side changes. Always re-ready first.
./operate.sh rollback is destructive and gated by ROLLBACK_CONFIRMATION. Never re-run after success.
./operate.sh edge in execute mode creates real DNS records. Re-running with different values modifies DNS. Eyeball the plan first (CLOUDFLARE_MODE=plan).

Partial Phase 1

If enrich died 80% through

The skill keeps partial downloads under workdir/artifacts/enriched/. Re-running ./migrate.sh enrich picks up where it left off (resumable via slack-advanced-exporter’s internal state). If files remain stuck, manually delete the specific __uploads/F<id>/ directories that are incomplete and re-run.

Partial Phase 2

Recovering mid-staging / mid-deploy

If deploy finished but verify-live hasn’t, re-run <Mono>verify-live</Mono> alone; you don’t need to redeploy. If staging failed mid-import, run monitor-import.sh against the staging mmctl import job list --json to see if the job is still in flight or crashed; if crashed, mmctl import job cancel <id> and re-run.

§10.1 · worked example

Meet Acme Corp.

Throughout this article and the two skills, a fictitious workspace anchors the examples:

Company: Acme Corp (340 users, engineering + ops + sales)
Plan: Business+ (routed to Track A, the official admin export)
Target: chat.acme.com, served from a Hetzner AX42 in Falkenstein
Email: Postmark for transactional SMTP (admin@acme.com is the rollback owner mailbox)
Storage: Cloudflare R2 for files; local /opt/mattermost/data/ during cutover, migrate post-cutover
Calls: enabled; calls.acme.com is grey-clouded so UDP 8443 works

Phase 1 config

Acme Corp’s Phase 1 config.env

WORKSPACE_NAME="acme-slack"
PHASE1_WORKSPACE_ROOT="./workdir"
MATTERMOST_TEAM_NAME="acme"
MATTERMOST_TEAM_DISPLAY_NAME="Acme Corp"
SLACK_PLAN_TIER="Business+"

SLACK_EXPORT_ZIP="/Users/jane/Downloads/acme_slack_export_2026-04-15.zip"
SLACK_CHANNEL_AUDIT_CSV="/Users/jane/Downloads/acme_channel_audit_2026-04-15.csv"
SLACK_MEMBER_CSV="/Users/jane/Downloads/acme_member_list_2026-04-15.csv"

SLACK_TOKEN="xoxp-ACME-USER-TOKEN-WITH-READ-SCOPES"
MMETL_DEFAULT_EMAIL_DOMAIN="acme.com"
PHASE1_SIDECAR_INPUTS="/Users/jane/acme/canvases,/Users/jane/acme/lists"
PHASE1_WORKFLOW_INPUTS="/Users/jane/acme/workflows"
PHASE1_SIDECAR_CHANNELS="slack-canvases-archive,slack-lists-archive,slack-export-admin"

SLACK_BOT_TOKEN="xoxb-ACME-BOT-TOKEN"
SLACK_TEAM_ID="TACMETEAM"

Phase 2 config

Acme Corp’s Phase 2 config.env

WORKSPACE_NAME="acme-slack"
PHASE2_WORKSPACE_ROOT="./workdir-phase2"
HANDOFF_JSON="/Users/jane/slack-migration/acme/workdir/artifacts/reports/handoff.json"
IMPORT_ZIP="/Users/jane/slack-migration/acme/workdir/artifacts/import-ready/mattermost-bulk-import.zip"

MATTERMOST_URL="https://chat.acme.com"
MATTERMOST_ADMIN_USER="admin"
MATTERMOST_ADMIN_PASS="<generated, stored in 1Password>"
MATTERMOST_TEAM_NAME="acme"
ENABLE_LOCAL_MODE="1"

TARGET_HOST="chat.acme.com"
TARGET_SSH_USER="deploy"
DEPLOY_METHOD="apt"
POSTGRES_DSN="postgres://mmuser:<strong>@localhost:5432/mattermost?sslmode=disable"
SMOKE_DATABASE_URL="${POSTGRES_DSN}"

SMTP_SERVER="smtp.postmarkapp.com"
SMTP_PORT="587"
SMTP_USERNAME="<postmark-server-token>"
SMTP_PASSWORD="<postmark-server-token>"
SMTP_TEST_EMAIL="admin@acme.com"

CLOUDFLARE_ENABLED="1"
CLOUDFLARE_MODE="execute"
CLOUDFLARE_API_TOKEN="<zone-edit-scoped>"
CF_ZONE_ID="<acme-com-zone-id>"
ORIGIN_SERVER_IP="95.217.12.34"
CALLS_HOSTNAME="calls.acme.com"
CALLS_SERVER_IP="95.217.12.34"

MATTERMOST_ADMIN_TOKEN="<system_admin-PAT-created-post-deploy>"
ROLLBACK_OWNER="Jane Admin <jane@acme.com>"
BACKUP_PATH="/var/backups/mattermost/mm_2026-04-22.sql.gz"
SCRATCH_DB_URL="postgres://mmuser:<strong>@localhost:5432/mm_restore_drill?sslmode=disable"

Phase 1 kickoff prompt

Typical paste

“Use the slack-migration-to-mattermost-phase-1-extraction skill. Read the prompts directory, then run the setup stage for Acme Corp. Pause and show me the doctor.sh summary after it finishes so I can confirm we’re green before export.”

Expected reply (abridged): “doctor.sh says 14/14 required passing (100%). Tools: slackdump 3.2.0, slack-advanced-exporter 1.0.4, mmetl v2.3.0, mmctl v9.11. Disk: 420 GiB free on /. Config loaded: Track A, Acme Corp. Ready for export. Shall I proceed?”

Successful cutover-status

Acme’s production cutover

{
  "status": "success",
  "started_at": "2026-04-22T14:05:12Z",
  "completed_at": "2026-04-22T14:31:04Z",
  "import": {"job_id": "8hxm...", "state": "success", "final_lines": 218451},
  "smoke": {"users": 337, "channels": 142, "posts": 1284903, "direct_channels": 4921},
  "reconciliation": {"status": "ok", "diffs": []},
  "activation": {"smtp_test_email": "admin@acme.com", "reset_link_received": true},
  "rollback_owner": "Jane Admin <jane@acme.com>"
}

Use these numbers to sanity-check your own runs; Acme’s shape is the canonical “this is what a healthy migration looks like.”

§10.3

Stage cheatsheet — outcome, proof, recovery.

Phase 1

What you have after each stage

Stage	After this stage you will have	How to tell it worked	If it failed
setup	workdir/artifacts/{raw,enriched,import-ready,reports}/ tree; config validated; tools resolved	doctor.sh prints “Health score: N/N required passing (100%)”	Missing tool → re-run bootstrap-tools.sh; missing env → edit config.env and re-run
export	slack-export.zip + audit/member CSVs + manifest.raw.json	jq '.files \| length' manifest.raw.json matches file count; every file has SHA256	Truncated ZIP → re-download; rate-limited slackdump → retry with built-in backoff
enrich	slack-export.enriched.zip with __uploads/, rewritten users.json, emoji manifest, sidecar bundle	validate-enrichment-completeness.py reports empty missing_file_references + empty users_missing_email	Missing attachments → per-file decision: accept as unrecoverable or re-run after fixing scope
transform	mattermost_import.jsonl + data/bulk-export-attachments/	mmetl check slack exits 0; JSONL has users/channels/posts lines	mmetl panic → MMETL_EXTRA_FLAGS="--discard-invalid-props"
package	mattermost-bulk-import.zip + manifest.import-ready.json	Sidecar channels populated; emoji objects precede team line	Warning about missing user in memberships → trace to source in JSONL, fix patch script input
verify	reports/verification.md, evidence-pack.json, secret-scan.json (+ reports/redacted/ if findings)	verification.md has no red lines; scan findings empty or accepted	Red reconciliation → go back to enrich or export; do not proceed
handoff	handoff.md, handoff.json, unresolved-gaps.md	shasum -a 256 final.zip == handoff.json.final_package.sha256	Mismatch → re-run handoff (never edit handoff.json by hand)

Phase 2

What you have after each stage

Stage	After this stage you will have	How to tell it worked	If it failed
intake	workdir-phase2/reports/phase2-intake-report.json	Hash match confirmed, sidecar_channels[] non-empty	Re-copy canonical ZIP from Phase 1
render-config	rendered/config.json + mattermost.nginx.conf + config-validation.json	config-validation.json.status == "ready"; MaxPostSize=16383	Missing env → fix config.env; re-run
edge	Cloudflare A record proxied; origin CA cert in rendered/origin.{pem,-key.pem}	verify-cloudflare-edge.py green	Fall back to NGINX_ENABLE_TLS=1 with Let’s Encrypt
provision	UFW, fail2ban, unattended-upgrades, optional local PG on target	systemctl status fail2ban active; ufw status verbose active	Re-run in plan mode, eyeball script, then ssh mode
deploy	Mattermost + Nginx running, config.json in place, TLS cert installed	/api/v4/system/ping returns 200 via HTTPS	Ubuntu 25.10 + APT fail → switch to DEPLOY_METHOD=docker
verify-live	reports/live-stack.md with ping + WS + SMTP results	All three probes green, 6× retries exhausted without falling back	WS fail → re-render-config+deploy; SMTP fail → verify with swaks
staging	reports/latest-staging.json + timestamped staging-summary.*.json, import-watch JSONL	latest-staging.json.status=success, observed counts ≈ handoff counts	Counts off → go back to Phase 1
restore	Proof that pg_restore works against SCRATCH_DB_URL	restore-drill.sh exits 0; tables populate	Fix BACKUP_PATH; redo drill
ready	cutover-readiness.json, readiness-score.md, phase2-readiness.md	status: "ready" verbatim	Fix every blocker listed; re-run
cutover	reports/cutover/cutover-status.<ts>.json + latest-activation.json	newest cutover-status.*.json has status: "success"	Read note; fix-in-place or rollback
rollback	Restored pre-cutover state, archived rollback artifacts	Users can’t reach new Mattermost; DB is back to pre-cutover dump	Unfreeze Slack; schedule a new attempt

§10.5

Concrete monthly cost breakdown (340 users).

For a 340-user deployment (Acme Corp profile), numbers as of April 2026:

Line item	Price	Notes
Hetzner AX42 dedicated (Falkenstein or Helsinki)	€46/month (~$50)	AMD Ryzen 7 PRO 8700GE, 64 GB DDR5, 2× 512 GB NVMe. One-time setup €39.
OR Hetzner AX52 (recommended 500–1,000 users)	€64/month (~$70)	Ryzen 7 7700, 64 GB DDR5, 2× 1 TB NVMe. One-time €39.
Cloudflare Free plan	$0	TLS termination, DDoS, WAF, WebSockets, CDN for static assets.
Postmark (100K emails/month)	$15/month	SPF/DKIM/DMARC built in. Alternatives: Mailgun Flex ($35), SES ($1/10K but setup-heavy).
Domain + DNS (if not already owned)	$10–15/year	Cloudflare charges cost; any registrar fine.
Cloudflare R2 (file storage, optional)	~$1.50/month	For 100 GB files. Zero egress.
Hetzner Storage Box 1 TB (off-site backups)	€4/month (~$4)	Nightly pg_dump target.
Total / month (AX42 + R2 + backups)	~$70/month
Total / month (AX52 + R2 + backups)	~$90/month

Compared to Slack pricing for 340 users (Business+ is ~$12.50/user/month, or ~$4,250/month, ~$51,000/year), self-hosting at this scale is a 98–99% cost reduction, and the data lives on hardware you own.

One-time costs (not recurring):

Hetzner setup fee: €39 per server.
Operator time: one weekend for under 100 users, 1–2 weeks for 1,000 users with rehearsals.
Optional: Mattermost Professional Edition license (~$10/user/month) if you want SAML SSO, compliance features, or guest accounts. Team Edition is free and sufficient for most orgs.

§10.4

User-communications kit.

Phase 2 ships references/comms/USER-COMMS-KIT.md with longer versions of each template. Quick copy-paste versions below — edit for your voice.

T−7d — “Heads up, we’re moving”

Subject: We’re moving from Slack to Mattermost in 7 days

Hi team, quick heads-up: on [DATE] we’re migrating from Slack to a self-hosted Mattermost server at https://chat.acme.com. This saves us about [$X] per year and keeps our chat history on infrastructure we own.

What you need to do: nothing yet. We’ll send instructions the day before and the day of.

What won’t change: public channels, private channels you’re in, DMs, threads, files, and reactions all move over.

What will change: Slackbot automations, scheduled messages, saved items, and a few other per-user things don’t migrate. If you rely on any of these, I’ll list them in the “day of” email so you can recreate them.

Questions? [help channel / ticket link]

T−24h — freeze notice

Subject: Slack goes read-only tomorrow at 09:30

Tomorrow, [DATE] at 09:30 local, Slack will be set to read-only. You’ll still be able to read everything, but not post.

At 10:15 your Mattermost account will be waiting at https://chat.acme.com/reset_password. Enter the email you use in Slack. You’ll get a password-reset email. Set a password, log in, and you’re done.

All your Slack history (public, private channels you’re in, DMs, threads, files) will already be there.

Who to ask if something goes wrong: [name, email, Slack handle for today / Mattermost handle post-cutover]

T−15m — “Slack is now read-only”

#general: heads up, Slack is now read-only. Do not start new threads here. Mattermost opens for activation at 10:15 at https://chat.acme.com/reset_password. Use your Slack email.

T+0 — activation

Subject: Mattermost is live. Activate your account.

Mattermost is live at https://chat.acme.com. To activate:

Go to https://chat.acme.com/reset_password.
Enter your Slack email (the one you use day to day).
Check that email for a password-reset link.
Set a password. Log in.

Your Slack history is already there. If something looks off, ping [support handle].

Not migrated (recreate these yourself): Slackbot auto-replies, saved items, scheduled messages, bookmarks, custom notification rules. See [link to internal doc] for step-by-steps.

T+24h — activation reminder

Subject: If you haven’t activated Mattermost yet…

About [N]% of the team has activated. If you haven’t, take 90 seconds now: https://chat.acme.com/reset_password, your Slack email, done.

If you never got the reset email, check spam first, then reply to this message and I’ll either resend or set a temp password for you.

T+7d — wrap-up

Subject: One week in; Slack is going away

Everything’s been running on Mattermost for a week. Today I’m:

Revoking the Slack migration app (we only needed it for one-time access).
Downgrading the Slack workspace to the cheapest read-only tier so we can still reference old content for 90 days if anyone needs it.
Closing this migration ticket. Retrospective thread: [link].

If you still haven’t activated Mattermost: do it today.

§10.6

Legal approval gate — copy-paste email to legal / HR.

The Phase 1 skill’s references/playbooks/LEGAL-APPROVAL-GATE.md is the authoritative playbook. A starter email for impatient operators:

Subject: Approval to export Slack workspace data for migration to self-hosted Mattermost

Hi [Legal / HR contact],

As part of the planned chat-platform migration (ticket [#ID]), I need written approval to export the company’s Slack workspace content. Specifics:

Scope I’m requesting: full content export under our Business+ plan. That’s public channels, private channels, direct messages, and group DMs; the full set the plan tier authorizes.

Purpose: one-time migration to a self-hosted Mattermost server at chat.acme.com, owned and operated by [Company]. The migration uses Slack’s own admin export feature plus Mattermost’s official import tooling.

Data handling during migration:

Export ZIP is downloaded directly to my workstation at [location]; not uploaded to third parties.
During processing, the ZIP lives in ~/slack-migration/ on my laptop, deleted after T+30 days.
Import artifacts are SHA256-hashed and a machine-readable evidence pack is generated.
Slack session tokens and the Slack admin app are revoked within 7 days of cutover.

Retention: unchanged. Slack data that today expires per [retention policy] will expire in Mattermost on the same schedule.

Regulatory basis: [pick one of: “consent of the members via the prior communication sent on [DATE]” / “legitimate business interest under [policy]” / “contractual requirement under [customer contract clause]”].

What I need from you: a “yes, proceed” reply in this thread, plus any concerns or scope-trimming requests before I kick off the export. I’ll cc you on the final handoff.md plus evidence pack as proof of handling.

Happy to hop on a call if easier.

Thanks,
[Name]

Save the approving reply alongside handoff.md in the final evidence pack.

§10.9

Disk footprint per stage.

A worked-example table for a 340-user Business+ workspace with ~3 years of history, ~12 GB raw export, ~8 GB of attached files:

Stage	New files added	Cumulative disk
setup	empty directory tree + config copies	~1 MB
export	slack-export.zip (~12 GB), audit CSV (~2 MB), member CSV (~100 KB), manifest.raw.json	~12 GB
enrich	slack-export.enriched.zip (~20 GB including downloaded attachments), emoji images (~50 MB), sidecar bundle (~500 MB)	~33 GB
transform	mattermost_import.jsonl (~500 MB), data/bulk-export-attachments/ (~8 GB, deduped from enriched)	~42 GB
package	mattermost-bulk-import.zip (~22 GB)	~64 GB
verify + handoff	reports/ (~5 MB), evidence-pack.json (~1 MB)	~64 GB

Rough scaling rule: total disk needed ≈ 3× the raw Slack export ZIP size. For a 1,000-user workspace with 5 years of history, plan for 500 GB free. Temp space: mmetl uses a scratch directory up to ~1.5× the JSONL size; make sure $TMPDIR (or the rendered JSONL output dir) has headroom. After successful handoff, the only file you need to keep is mattermost-bulk-import.zip; the rest can be archived to cold storage (Storage Box / R2) for the evidence pack and then deleted.

§10.10

Enterprise Grid — per-workspace migration.

Grid admins have one extra decision: grid-wide export (one giant ZIP covering every workspace) vs per-workspace export (one ZIP per team). Per-workspace is usually cleaner because each workspace becomes its own Mattermost team.

Canonical flow

Per-workspace

In each Slack Grid workspace you want to migrate, run a separate official admin export.
Create a fresh working directory per workspace (~/slack-migration/acme-engineering, ~/slack-migration/acme-sales, etc.), each with its own config.env.
Run the Phase 1 pipeline per directory. Each emits its own handoff.json.
In Phase 2, either:
- Stand up one Mattermost server with multiple teams, and run ./operate.sh intake + cutover per workspace, each pointing at the same MATTERMOST_URL but different MATTERMOST_TEAM_NAME.
- Or stand up separate Mattermost servers per division.

Canonical flow

Grid-wide

If you got a single grid-wide ZIP, use the skill’s split-phase1-import.py helper before enrichment:

./scripts/split-phase1-import.py \
    --input /path/to/grid-export.zip \
    --output-dir workdir/split/ \
    --by workspace

Creates workdir/split/<workspace>/slack-export.zip. Treat each as a per-workspace export. references/ENTERPRISE-GRID.md has the detailed walkthrough including edge cases.

Grid edge cases

What to watch for

Users in multiple workspaces: same email. Mattermost merges them on import. If per-workspace Phase 1s, run Phase 2 imports in dependency order (least-dependent first) to keep username conflicts predictable.
Grid-wide search channels: don’t migrate as first-class; preserve the member list as a sidecar and flag for rebuild if operationally important.
IdP / SSO in Grid: Grid’s enterprise SSO doesn’t follow users into Mattermost. Configure Mattermost’s SAML separately (System Console → Authentication → SAML 2.0) and map on email.

§10.11

Compliance & audit handoff.

If your org has a compliance reviewer or external auditor, here is what you hand them.

Phase 1 evidence pack

Location + fields

Location: workdir/artifacts/reports/evidence-pack.json. Fields (summarized):

schema_version — frozen format identifier
generated_at — UTC timestamp
workspace — Slack workspace slug
plan_tier, export_basis — legal basis for the export (from SLACK_PLAN_TIER plus the legal-approval memo)
manifests[] — list of hash-anchored manifest files (raw, enriched, import-ready)
counts — users, channels, posts, DMs, emoji, attachments, sidecars
known_gaps[] — every documented not-migrated item with disposition class
secret_scan_findings — scan-and-redact-migration-secrets.py output (should be empty or explicitly accepted)

Phase 2 cutover pack

Location + artifacts

Location: workdir-phase2/reports/. Key artifacts:

phase2-intake-report.json — hash match proof (Phase 1 to Phase 2)
config-validation.json — server config drift check
live-stack.md — TLS + WebSocket + SMTP reachability evidence
latest-staging.json + timestamped staging-summary.*.json — rehearsal results, observed counts, reconciliation
cutover-readiness.json + readiness-score.md — pre-cutover gate, with ROLLBACK_OWNER named
cutover/cutover-status.<ts>.json + latest-activation.json — final import state, activation proof, reconciliation

What an auditor typically asks

Five common questions

Question	Where the answer lives
Prove the data we imported matches the data we exported.	Show handoff.json.final_package.sha256 + phase2-intake-report.json hash match + latest-staging.json count reconciliation.
Prove who authorized the export.	The legal-approval email (§10.6) stored alongside the evidence pack. Not in the skill’s output; you attach it.
Prove no secrets leaked into reports.	secret-scan.json from the secret scanner; redacted copies in reports/redacted/ if any.
Prove the cutover had a rollback plan.	cutover-readiness.json.rollback_owner (named human) + restore-drill result if done.
Retention: where is the raw Slack data now?	Deleted from workdir/artifacts/raw/ after T+[retention period]. The scan-and-redact helper plus the final handoff give you the last point the raw ZIP was referenced.

Handoff format

Store the encrypted blob off-site (R2 + a different cloud for redundancy). Retention: at least as long as your Slack retention policy, or per audit requirement. The unencrypted evidence pack contains organizational metadata (counts, channel names, user counts) but thanks to the secret scanner should not contain secrets. Still, encrypt it: cheap insurance.

Retention recommendations

How long to keep

Raw export ZIP + enriched ZIP: delete from operator workstation T+30 days after cutover, unless an auditor has asked for it.
Final import ZIP (mattermost-bulk-import.zip): keep for T+90 days in case a post-cutover re-import is needed.
Evidence pack + cutover pack: keep per your compliance retention policy. Typically 7 years for US SOX / EU GDPR article 5 compliance, or your sector-specific rule.

§10.12

Credential inventory — what you collect and where it goes.

Over the course of a migration you will create and store roughly a dozen credentials. Collect them in a password manager (1Password, Bitwarden, Dashlane), not in a text file on your desktop, and never commit them to git. The skill’s workdir/ and workdir-phase2/ directories, plus config.env, are in the default .gitignore.

In order of collection

The full list

#	Credential	What it is	Which config.env	Needed at stage
1	Anthropic or OpenAI subscription login	Sign-in for Claude Code / Codex desktop app	n/a (stays in the app)	Before Part 1
2	jsm account (Google OAuth)	Subscription at jeffreys-skills.md	n/a (stored in OS keychain)	§1.2 / Part 11
3	SSH keypair	~/.ssh/id_ed25519 + .pub	n/a (SSH uses it automatically)	§1.0, Phase 2 provision
4	Domain + registrar login	Your future chat.yourcompany.com DNS	n/a	§1.0.2
5	Cloudflare API token	Scoped: Zone.DNS:Edit + Zone.SSL:Edit for your one zone	CLOUDFLARE_API_TOKEN	Phase 2 edge
6	Cloudflare Zone ID	32-hex identifier for your zone	CF_ZONE_ID	Phase 2 edge
7	Slack user token (xoxp-…)	Read-scoped user OAuth token	SLACK_TOKEN	Phase 1 enrich
8	Slack bot token (xoxb-…)	Bot-scoped token for the same Slack app	SLACK_BOT_TOKEN	Phase 1 (optional, MCP verification)
9	Slack team ID (T…)	Workspace identifier	SLACK_TEAM_ID	Phase 1 enrich
10	Slack session cookies (xoxc- + xoxd-)	For slackdump stealth mode on Free/Pro	SLACKDUMP_XOXC + SLACKDUMP_XOXD	Phase 1 export on Free/Pro only
11	Postmark server token	SMTP credential for password-reset emails	SMTP_USERNAME + SMTP_PASSWORD (same value; Postmark convention)	Phase 2 verify-live, cutover
12	Mattermost admin password	System admin password for the admin account	MATTERMOST_ADMIN_PASS	Phase 2 deploy onwards
13	Mattermost admin PAT	Personal access token, created post-deploy	MATTERMOST_ADMIN_TOKEN	Phase 2 ready, cutover
14	PostgreSQL password (mmuser)	Local PG password the provisioner uses	inside POSTGRES_DSN	Phase 2 provision, deploy
15	Rollback-owner email	Your (or a named human’s) email	ROLLBACK_OWNER	Phase 2 ready, cutover

Lifecycle rules

Rotate and revoke

Never commit to git. Both phases ship a secret scanner that runs automatically; failure blocks handoff until you remediate.
Revoke after cutover. Within 7 days: revoke the Slack user token, bot token, and session cookies. Rotate the Mattermost admin PAT (create new, delete old) if you shared it with any automation.
Keep Cloudflare + Postmark + SSH long-term. Useful for operating the Mattermost server. Rotate Postmark if a former admin ever had access.
Chicken-and-egg: PAT after deploy. The Mattermost admin PAT doesn’t exist until deploy has finished and you’ve logged in as admin once. Leave MATTERMOST_ADMIN_TOKEN="" during intake/render-config/edge/provision/deploy, then come back and fill before verify-live.

Quick recovery

If you lose a credential

Lost Slack user token: re-install the Slack app, issue a new token, update config.env. Tokens are cheap; your identity is not.
Lost SSH key: see §1.0.5 (Hetzner rescue-system playbook).
Lost Cloudflare API token: delete old in Cloudflare → My Profile → API Tokens, create new with same scopes, paste into config.env.
Lost Mattermost admin password: SSH to the server and reset with sudo -u mattermost mmctl --local user change-password admin <new-password>. Write the new one into your password manager.
Lost rollback owner: pick a new one; update ROLLBACK_OWNER; re-run ./operate.sh ready to regenerate the gate record with the new name.

§10.13

Cloudflare walkthrough — click-by-click.

If you bought the domain at Cloudflare Registrar, skip step 1. Otherwise:

§10.13.1

Add your domain to Cloudflare

Sign up / log in at dash.cloudflare.com.
Click + Add a domain. Paste yourcompany.com (no https://, no subdomain).
Pick the Free plan. Free covers TLS, DDoS, WAF, CDN, and WebSockets — everything the migration needs. Continue.
Cloudflare scans your current DNS and imports the records. Confirm. Continue.
Cloudflare shows you two nameservers (e.g. ada.ns.cloudflare.com, joel.ns.cloudflare.com). Copy both.
Go to your registrar → nameservers → swap to Cloudflare’s two. Save.
Wait. Pending yellow → Active green in 15–60 min (occasionally up to 24 h). Don’t proceed past this until it’s green.

§10.13.2

Find your Zone ID

Click your domain name in the dashboard.
On Overview, right sidebar → API section.
Copy the 32-char hex Zone ID (e.g. 7e6c1f9b40a8d3e2f5c9b1a7e4d3f8c2).
Paste into config.env.phase2 as CF_ZONE_ID=… (no quotes, no spaces).

§10.13.3

Create a scoped API token

Never paste your global Cloudflare API Key. Use a scoped token.

Top-right avatar → My Profile → API Tokens → Create Token.
Scroll past the templates → Create Custom Token → Get started.
Name: slack-migration-phase-2 (any label you’ll recognize later).
Under Permissions, add:
- Zone → DNS → Edit
- Zone → SSL and Certificates → Edit
Under Zone Resources: Include → Specific zone → your domain.
Leave IP filtering and TTL defaults. Continue to summary → Create Token.
Cloudflare displays the token exactly once. Copy immediately. Paste into config.env.phase2 as CLOUDFLARE_API_TOKEN=…
The confirmation page shows a Test curl — run it; expect "status":"active" JSON.

§10.13.4

What the skill does with these

Creates/updates an A record for chat.yourcompany.com pointing at $ORIGIN_SERVER_IP, orange-clouded.
If CALLS_HOSTNAME is set, also creates a grey-clouded (DNS-only) A record for calls.yourcompany.com so UDP 8443 bypasses Cloudflare’s proxy.
Generates a 15-year Cloudflare Origin CA certificate for chat.yourcompany.com and saves PEMs into workdir-phase2/rendered/. The subsequent deploy stage SCPs these to /etc/nginx/ssl/origin.pem.

Origin CA is a Cloudflare-specific concept: valid only for traffic through Cloudflare’s proxy. Free, 15 years, no ACME renewal cron. If you prefer Let’s Encrypt directly on origin, set CLOUDFLARE_ENABLED=0 and supply your own cert at NGINX_CERT_PATH / NGINX_KEY_PATH.

§10.13.5

Orange-cloud vs grey-cloud in one sentence each

Orange-clouded (proxied): traffic intercepted by Cloudflare — TLS terminated, attacks filtered, static cached, forwarded to origin. Use for user-facing HTTP/HTTPS.
Grey-clouded (DNS-only): Cloudflare hands back your origin IP directly. Use for UDP (Calls 8443), staging, and MX records.

§10.13.6

Cloudflare troubleshooting

Zone stuck in Pending: nameserver change hasn’t propagated. Check dig NS yourcompany.com +short; if you see old nameservers, give it time or re-verify at the registrar.
API token returns 403: wrong zone in Zone Resources. Create a new token; Cloudflare requires recreation for scope changes.
Origin CA cert doesn’t work: edge stage wrote the cert but deploy didn’t copy. Check workdir-phase2/rendered/origin.pem, SCP manually to /etc/nginx/ssl/origin.pem, sudo systemctl reload nginx.

§10.14

SMTP (Postmark) walkthrough.

Mattermost sends password-reset emails to every user on activation. If SMTP is broken, users can’t log in after cutover. This is the single most under-documented piece of the stack for non-technical operators.

§10.14.1

Why Postmark

Cheapest entry tier ($15/month for 10K emails, more than enough for a 340-user activation burst).
Highest reputation for transactional email (fast inbox placement, rare spam-folder issues).
Simple domain verification (3 TXT records).
Server Tokens can be used directly as SMTP credentials.

Mailgun Flex ($35/month), Amazon SES ($1 per 10K emails but setup-heavy), and Google Workspace SMTP relay (free with a Workspace account but rate-limited) are valid alternatives with similar click-paths.

§10.14.2

Sign up for Postmark

Go to postmarkapp.com → Sign up. Use your company email.
Confirm email. Log in.
Pick Transactional email.
Create a server (Postmark’s term for a sending pool). Name: acme-chat-transactional. Stream type: Transactional.

§10.14.3

Add and verify your sending domain

Postmark dashboard → Sender Signatures → Domains → + Add Domain.
Enter acme.com (your root domain, not chat.acme.com). Verify.
Postmark shows 3 DNS records:
- DKIM TXT at 20260416pm._domainkey.acme.com, value k=rsa; p=MII…
- Return-Path CNAME at pm-bounces.acme.com → pm.mtasv.net
- Optionally DMARC TXT at _dmarc.acme.com with v=DMARC1; p=none; rua=mailto:dmarc-reports@acme.com
Add each in Cloudflare → DNS → Records. Type, Name, Content exactly as shown. TTL Auto. Proxy status DNS only (grey cloud) — required for Return-Path CNAME.
Back in Postmark, Verify. Usually succeeds within 2 minutes. If fail, recheck value character-for-character (DKIM keys are easy to truncate).

You want DKIM and Return-Path both verified (green checkmarks). DMARC is optional but recommended.

§10.14.4

Grab the Server Token

Postmark dashboard → your server → API Tokens tab.
Copy the Server Token.
Paste into config.env.phase2 as both SMTP_USERNAME and SMTP_PASSWORD. Postmark’s SMTP expects the same token in both — Postmark convention, not a mistake.

SMTP_SERVER="smtp.postmarkapp.com"
SMTP_PORT="587"
SMTP_TEST_EMAIL="admin@acme.com"
# Optional: override the from-address; default is $SMTP_TEST_EMAIL
SMTP_FROM_ADDRESS="noreply@acme.com"

§10.14.5

Test before you need it

From the target server (or your laptop with swaks installed — brew install swaks on Mac, apt install swaks on Ubuntu):

swaks --to $SMTP_TEST_EMAIL \
      --from noreply@acme.com \
      --server smtp.postmarkapp.com:587 \
      --tls \
      --auth-user "$SMTP_USERNAME" \
      --auth-password "$SMTP_PASSWORD" \
      --header "Subject: migration SMTP test" \
      --body "If you're reading this, Postmark works."

Expect 250 OK and the email in your inbox within 30 seconds. If it lands in spam, don’t panic — first emails from a new Postmark sender often do. Send 3–4 more over the next hour; deliverability improves as Postmark warms up your reputation.

Phase 2’s verify-live does the equivalent automatically. If it reports success but Mattermost’s own reset-password emails fail at cutover, it’s almost always:

SMTP_FROM_ADDRESS doesn’t match the verified domain (Postmark rejects). Fix: SMTP_FROM_ADDRESS=noreply@acme.com where acme.com matches the verified signature.
RequireEmailVerification=true in Mattermost config. render-config sets this false by default; re-check if you edited the rendered file.
User’s email provider classifies Mattermost’s template as marketing. Mitigation: ensure DMARC is set (§10.14.3 record 3).

§10.14.6

Cost at cutover scale

For a 340-user activation burst you’ll send ~340 welcome/reset emails in the first hour, plus retries over the following week (<50 typically). Well within Postmark’s 10K/month $15 plan. After activation week you’ll send 1–5 emails/day (new hires, admin-triggered resets), so the same plan covers you indefinitely.

Part 11

Installing the skills via Jeffrey’s Skills.md (jsm).

The two migration skills are published on jeffreys-skills.md, a subscription skill library built around a small Rust CLI. $20/month individual subscription gets you access to every premium skill, plus storing your own private skills in the cloud and syncing across machines.

Sign up for a subscription

Open jeffreys-skills.md.
Sign up / subscribe. Sign in with Google; no separate email/password.
Pick Individual ($20/month) and check out via Stripe or PayPal. Auto-renews monthly; cancel any time.
Dashboard shows active subscription and a button to install the jsm CLI.

What you get for $20/month:

Access to every premium skill on the site, including both slack-migration-to-mattermost-phase-1-extraction and -phase-2-setup-and-import.
Automatic updates (pinnable to specific versions).
Personal cloud skill storage — push private skills with jsm push, pull on any signed-in machine.
Cross-device sync.
Hash-verified downloads — jsm verify catches tampering.

§11.2

Install the jsm CLI

# macOS / Linux
curl -fsSL https://jeffreys-skills.md/install.sh | bash

# Windows PowerShell as Admin
irm https://jeffreys-skills.md/install.ps1 | iex

# Verify
jsm --version
# should print something like: jsm 0.1.7

Drops the binary into ~/.local/bin and adds it to PATH. Restart your terminal (or source ~/.bashrc).

§11.3

First-time setup and authentication

jsm setup        # interactive wizard — where should skills live
jsm login        # opens a browser → sign in with Google
jsm whoami
# Signed in as you@example.com (subscription: active)

For corporate proxies / weird networks:

jsm login --remote     # device-code style — paste a code in a browser anywhere
jsm login --manual     # prints the callback URL to paste into jsm yourself

§11.4

Install the two migration skills

jsm install slack-migration-to-mattermost-phase-1-extraction
jsm install slack-migration-to-mattermost-phase-2-setup-and-import
# or in one command (they declare pairs_with)
jsm install slack-migration-to-mattermost-phase-1-extraction --related

jsm list
jsm verify slack-migration-to-mattermost-phase-1-extraction
jsm info slack-migration-to-mattermost-phase-1-extraction

§11.5

Keeping skills up to date

jsm upgrade                      # apply any available updates
jsm upgrade --list               # show what would update
jsm upgrade slack-migration-to-mattermost-phase-1-extraction

# update preference
jsm config update-preference auto      # apply on every sync
jsm config update-preference notify    # just tell me
jsm config update-preference manual    # never auto-update

# pin a known-good version before production cutover
jsm pin slack-migration-to-mattermost-phase-1-extraction 1.3.0
jsm pin slack-migration-to-mattermost-phase-2-setup-and-import 1.3.0

# after cutover:
jsm unpin slack-migration-to-mattermost-phase-1-extraction
jsm unpin slack-migration-to-mattermost-phase-2-setup-and-import

§11.6

Multi-machine sync

jsm sync

Compares installed skills, local hashes, and last-synced hashes against the catalog; pulls anything new. Does not upload secrets or per-migration config.env; only the skill definitions sync.

§11.7

Troubleshooting jsm

jsm doctor
jsm doctor --fix     # auto-repair common issues

jsm: command not found → shell hasn’t re-read PATH. New terminal or export PATH="$HOME/.local/bin:$PATH".
jsm whoami says “not authenticated” after a successful jsm login → keychain didn’t persist (common on WSL2/headless Linux). Retry with jsm login --remote.
jsm install says “subscription required” but you’re subscribed → subscription email and Google-OAuth email don’t match. Check jeffreys-skills.md/dashboard; sign out and in with the correct Google account.
Install hangs on slow network → jsm install --retries 5 <skill>. Fall back to manual zip download if needed.
Claude Code / Codex don’t see the skill after install → restart the app (desktop) or session (CLI). Desktop apps index ~/.claude/skills/ on launch.

§11.8

Manual install without jsm (zip-download fallback)

If jsm refuses to install and you can’t get past it, you don’t have to use it. The skills are directories of files; jsm just fetches, verifies a hash, and drops them in the right place.

Sign in at jeffreys-skills.md/dashboard.
Find each skill in the catalog, click it, click Download zip. Copy the SHA-256 hash.

Then ask the agent to install, pasting the hashes:

“I downloaded two skill zip files from jeffreys-skills.md. Please install them into ~/.claude/skills/ by: (1) verifying each zip’s SHA-256 matches the hash I’ll paste below, (2) extracting each zip into ~/.claude/skills/<skill-name>/ so that SKILL.md lands at the top level, (3) running chmod +x on any .sh scripts, (4) listing the final tree. Zips at ~/Downloads/slack-migration-to-mattermost-phase-1-extraction-1.3.0.zip and …-phase-2-setup-and-import-1.3.0.zip. Expected hashes: [paste].”

Once jsm works later, jsm adopt <skill-name> hashes the installed files, registers them in its local database, and treats them as if it had installed them itself.

§11.9

Uninstalling

jsm uninstall slack-migration-to-mattermost-phase-1-extraction
jsm uninstall slack-migration-to-mattermost-phase-2-setup-and-import
# or:
jsm uninstall --all              # remove everything jsm installed
# add --keep-data to preserve per-skill config you'd written

Cancel the subscription itself from the dashboard; jsm doesn’t touch billing.

Part 12 · ongoing maintenance

The week after, and every week after that.

Moving is not the part people are afraid of. Running the new server, forever, is. That is the fear Slack's pricing team is counting on. It is also the part the Phase 3 maintenance skill exists to automate.

Ongoing maintenance is a small list of tasks that would be irritating to do manually on a regular cadence but are exactly the shape of a job an agent does well: a nightly Postgres dump to off-site storage with a hash check; a weekly health probe of the live stack; an OS patch pass with a scheduled reboot; a quarterly restore drill where the newest backup is restored into a scratch database to prove it still restores. An unrestored backup is wishful thinking, not a backup. The drill is what keeps it from quietly decaying. Phase 3 wires all of it into a single weekly sweep that the agent runs Saturday night and summarizes into a one-paragraph Monday-morning status you skim in sixty seconds.

The single piece of the maintenance skill worth pausing on, because it is the thing that turns Mattermost upgrades from a sweaty-palm activity into a background task, is the auto-rollback upgrade loop:

update-mattermost, auto-rollback on failure

doctor.sh confirms SSH + ping + PAT still work.
pg_dump streams the current DB to /var/backups/mattermost/pre-upgrade-<ts>.sql.gz. SHA-256 captured.
systemctl stop mattermost.
apt-get install --allow-downgrades mattermost=<target_version>.
systemctl start, then poll /api/v4/system/ping for up to 3 minutes.
If the new version doesn’t come up: stop, downgrade the package, DROP / CREATE the database, stream the pre-upgrade dump back in, start. Record status: failed_rolled_back.

Blast radius on failure: 2 to 6 minutes of Mattermost being offline. Data loss: zero. That loop is what lets a solo operator run production upgrades without a pager rotation.

Pair the auto-rollback loop with the quarterly restore drill and you have a backup pipeline that is actually tested, not one that will let you down the exact day the host dies. That is the whole point of running your own chat server. You own the schema, the hardware, the upgrade path, and — most importantly — the knowledge that the loops you depend on have been exercised on a scratch database recently enough to be trusted.

§12.3

The weekly cadence

This is the whole point: the agent runs everything, you read a one-paragraph status on Monday morning.

Saturday night (~20 min agent runtime): paste the weekly-sweep.md prompt. The agent runs health → update-os → backup → db-health and writes a summary.
Monday morning (~1 min attention): skim the summary. If anything is red, tell the agent to investigate.
First Saturday of the quarter (~60 min): paste restore-drill.md. Agent downloads the newest backup, restores into scratch DB, confirms row counts. Failed drill = production incident.
On a Mattermost security release: paste update-mattermost.md with the pinned version. Auto-rollback loop kicks in if the health check fails.

You can automate the weekly sweep with cron on your workstation plus a webhook alert on failure (set ALERT_WEBHOOK_URL in config.env), or keep it as a scheduled agent-run item.

§12.4

Paste-ready prompts — you don’t hand-roll the wording

The prompts/ directory is a library of agent prompts already phrased for good outcomes. Pick one, paste, done:

Prompt file	What the agent does
orient.md	Reads config.env, runs doctor.sh, reports where the deployment is and what’s known
health.md	One-shot health snapshot; posts summary
update-os.md	Applies OS patches, schedules reboot if required
update-mattermost.md	Bumps Mattermost to pinned version, verifies, auto-rolls-back on failure
backup.md	Takes pg_dump, uploads off-site, verifies hash, reports size and destination
db-health.md	Postgres sizing, bloat, connections; flags slow-burning issues
restore-drill.md	Quarterly restore-from-backup verification
schedule-reboot.md	Queues a pending reboot in the next off-hours window
weekly-sweep.md	Saturday combo (health + update-os + backup + db-health)
major-upgrade.md	Extended sequence for a major Mattermost upgrade
plugin-upgrade.md	Plugin lifecycle: compatibility check, staging, prod install
rotate-credentials.md	PAT / SSH / off-site / session-secret rotation, one scope at a time
incident-response.md	Live-incident coordinator: triage, comms cadence, timeline capture
disaster-recovery.md	Rebuild onto a fresh host from the latest backup
all.md	Meta-prompt: the agent picks which sub-prompt fits your ask

§12.6

Restore-drill — the quarterly canary

If you have never restored a backup, you do not have backups. You have files.

./maintain.sh restore-drill exercises the backup pipeline end to end:

Lists the off-site destination (or local BACKUP_PATH) and picks the newest mm_*.sql.gz.
DROP DATABASE / CREATE DATABASE on SCRATCH_DB_URL — a separate Postgres instance provisioned specifically for drills. Never point this at prod.
Streams the compressed dump through gunzip | psql into the scratch DB.
Counts rows in "Users", "Channels", "Posts" (PascalCase, per Mattermost schema).
Compares counts against RESTORE_MIN_USERS, RESTORE_MIN_CHANNELS, RESTORE_MIN_POSTS.
Emits latest-restore-drill.json with status: ok|failed and counts.

Three distinct failure modes, each with its own remediation:

No backup found: off-site credentials expired, or the nightly backup has been silently failing. Check latest-backup.json from the last week.
Restore fails mid-stream: dump corrupted or scratch DB Postgres major version older than prod’s. pg_dump is forward-compatible but not backward.
Row counts below minimums: backup succeeded but captured an empty or partial DB. Has happened when a failed migration left Mattermost writing to a scratch schema; the backup job dutifully captured the empty one.

Passing drill: ~45 min of agent-watched runtime per quarter on a small deployment. Failing drill is the cheapest production incident you’ll ever have, because it happens on a scratch DB instead of on the day the host dies.

§12.7

Subagents for deep audits

Seven focused subagents live in subagents/. They are not part of the weekly sweep; you invoke them on-demand when you want a second opinion on a specific dimension. Each is already wired to the skill’s references, scripts, and config.

Subagent	Use when
backup-integrity-auditor	You want judgement on backup completeness, SHA-256 coverage, off-site freshness, and restore-drill recency, not just stage runs
db-bloat-auditor	DB size climbing faster than user count can explain; looks at table bloat, vacuum status, index health, pg_stat_user_tables
health-drift-auditor	Nothing is red yet, but you want to know what is slowly getting worse across the last 8 weeks of health reports
version-drift-auditor	How far behind the recommended upgrade target you are, framed against Mattermost’s ESR policy
security-posture-auditor	Credential rotation cadence, SSH key hygiene, fail2ban / UFW state, exposed ports
maintenance-scheduler	Planning a maintenance window; coordinates comms, picks off-hours, writes the user-facing heads-up
incident-coordinator	Live incident: triage playbook, comms cadence, timeline capture for the post-mortem

§12.8

Scenario pack — Acme Corp’s actual schedule

assets/scenario-packs/acme-corp-weekly.yaml is a worked schedule for a 40-user Acme Corp profile. Drop into your scheduler (cron, systemd timers, or scheduled agent runs):

workspace: acme-corp
timezone: America/Los_Angeles
operator: alex@acme.com

schedule:
  - name: nightly-backup
    cron: "0 10 * * *"            # 10:00 UTC = 02:00-03:00 Pacific
    command: "./maintain.sh backup"
    log: /var/log/mm-backup.log

  - name: weekly-sweep
    cron: "0 10 * * 0"            # Sunday 10:00 UTC
    command: "./maintain.sh weekly-sweep"
    log: /var/log/mm-sweep.log

  - name: quarterly-restore-drill
    cron: "0 11 1-7 1,4,7,10 0"   # First Sunday of each quarter
    command: "./maintain.sh restore-drill"
    log: /var/log/mm-drill.log

alert_webhook: https://chat.acme.com/hooks/abcdef12345

thresholds:
  disk_pct_red: 85
  pg_conn_pct_red: 80
  log_err_per_min_red: 10

upgrade:
  policy: esr                     # track ESR releases only
  max_delay_patch_security: 72h
  rollback: auto

Lift the cron lines into crontab -e on the workstation that holds the agent credentials. The alert_webhook posts a red-status summary to a Mattermost channel. ESR policy is the most consequential line for small teams: ESR (Enterprise-Scale Release) means fewer, more-stable bumps instead of every minor release.

§12.9

Disaster-recovery drill

Once a year (pick a Saturday, budget 2 hours), run a full DR simulation: order a fresh cheap Hetzner CX22, restore the latest backup into it with restore-drill.sh pointed at that host’s PG, verify it comes up as a working Mattermost. Cancel the CX22 when you’re satisfied. Tests the whole DR path without touching production and costs ~€0.10 in server-hours.

Full playbook in references/DISASTER-RECOVERY.md. The incident-coordinator subagent (§12.7) can also walk you through it live.

§12.10

Reading the weekly report and spotting trends

assets/templates/maintenance-report.md is the shape the agent follows. The summary table looks like:

Stage	Result	Notes
health	green	all probes green, 0 red
update-os	4 security patches, reboot required: yes	reboot scheduled for Sun 03:00 UTC
backup	success	1.4 GB, sha256=ab12…, off-site verified
db-health	yellow	Posts table up 8 % week over week, vacuum last ran 14 hours ago

The trend block matters more than any single week. Look at four-week deltas for disk growth, DB size, and error-rate baseline — these are the slow-burn numbers that predict when you need to upsize the server, not acute red alerts. The health-drift-auditor subagent does this reading for you and flags what’s getting slowly worse. Incident post-mortems share a template too (assets/templates/incident-status.md): timeline in UTC, root cause (not symptom), what fixed it, five whys.

§12.11

Credential-rotation cadence

./maintain.sh rotate-credentials --scope <name> rotates one thing at a time.

Scope	Cadence	What rotates
pat	90 days	MATTERMOST_ADMIN_TOKEN (Mattermost PAT for the bot admin)
ssh	annually	Deploy-user SSH key used by the workstation to reach TARGET_HOST
offsite	annually	rclone credentials for OFFSITE_REMOTE (R2 / Hetzner Storage Box token)
session-secret	on compromise only	Mattermost session signing secret; forces all users to re-login

The security-posture-auditor subagent reads your rotation-history.json and tells you what’s overdue. For the rare session-secret rotation, expect a full-team re-login and a heads-up message posted 24 hours in advance (comms templates in references/comms/).

§12.12

When to bring in more tooling

The Phase 3 skill is deliberately point-in-time health probes plus scheduled tasks. It does not replace continuous observability. If you eventually need:

SLO dashboards and alerting — spin up Grafana + Prometheus scraping Mattermost’s metrics port 8067.
Synthetic end-to-end user checks — Uptime Robot, Better Stack, or Cronitor hitting /api/v4/system/ping every 5 minutes.
Log aggregation — Loki or Grafana Cloud for mattermost.log.
Incident-response runbooks — Statuspage or a markdown repo your on-call reads on their phone.

All are complementary, not replacements for the Phase 3 skill’s automation of routine work. The OBSERVABILITY-LADDER.md reference lays out a graduated path; each rung has a “when it is worth the complexity” criterion so you’re not adding dashboards for their own sake.

A pattern, not a migration.

The deeper thing worth taking away from this is not about chat software. It is about the shape of problems that become tractable when a coding agent and a well-written skill are both in the room.

A decade ago, a company that wanted to move off Slack had three options. Hire a consultant for a six-figure fixed bid. Assign an internal engineer and lose them for a month. Or stay on Slack, grumble every April, and pay the price hike. The middle option — “assign an engineer” — was the right one for a lot of companies, but it was not cheap, and every time a new platform came out the institutional knowledge from the previous migration was gone.

The agent-plus-skill pattern collapses the expense side of that decision. The senior engineer writes the skill once, against the problem as it exists today, and every subsequent user inherits the whole thing — including the edge cases that cost the first engineer two weekends to discover. The skill is version-controlled, signed, installable in a minute, and pinnable to a known-good release for a production run. It is not a custom pipeline that decays. It is infrastructure, published like a library, that any company with a Claude Code or Codex subscription can run against their own Slack.

The pattern generalizes beyond Slack, of course. One-off infrastructure migrations — databases between providers, DNS between registrars, CI systems between vendors — are exactly the shape of problem that fits into a paired-skill architecture. Each has a sensitive extract step, a transform, a staging rehearsal, a fail-closed gate, and a cutover that needs to be an asymmetric bet by construction. Each is worth doing at most once per company, and the institutional knowledge is worth retaining forever. Each is a project a senior engineer would resent being assigned. Each is a thing an agent-driven skill, well-designed, can do in a weekend.

If you are still paying Slack today, what is going to happen is that at some point in the next eighteen months the vendor will email you a new number, and it will be larger than the current one by some multiple that is too painful to ignore. When it happens, you will have two options. You can pay. Or you can open a new Claude Code session, paste one sentence, and be somewhere better by the end of the weekend.

For operators who want to actually run this

This post is a distilled essay. The 2,500-line source guide that drives the two skills — and that an AI agent reads before kicking off the migration — includes everything this post skips:

Day-zero server ordering & SSH setup
Bootstrap scripts (doctor.sh, bootstrap-tools.sh)
MCP worked examples (Slack, Playwright, Mattermost)
Full Phase 1 / Phase 2 config.env field tables
Stage-by-stage cheatsheet with proof & recovery
Troubleshooting index (Phase 1, Phase 2, audit)
Printable operator checklist (T−2d, T−1d, T+0, T+7d)
User-communications kit (every template, T−7d → T+7d)
Legal-approval email template
Full credential inventory & rotation cadence
Cloudflare & Postmark click-by-click walkthroughs
Enterprise Grid split workflow
Compliance & audit evidence-pack handoff
Resume-after-interrupt playbook per stage
jsm install / pin / sync / verify commands
Phase 3 maintenance: weekly sweep, restore drill, DR, subagents, scenario pack

Download the full guide as Markdown

for feeding to an AI agent · ~185 KB · 2.5k lines

.md

Paste it into Claude Code or Codex with “read this guide end-to-end, then plan my migration” and the agent drives from there.

TL;DR

Two agent skills. One weekend. ~99% lower ongoing cost. Slack keeps working until you flip the switch yourself.

AI Agents · Infrastructure · Cost

Using AI Agents
to Migrate Off Slack.

Two paired skills. One focused weekend. Roughly a 99% cut in ongoing cost — and your whole chat history on hardware you own.

Slack → Mattermost

Public · private · DMs · threads

Agent-driven cutover

Scroll to Explore

For operators who want to run this

Download the full guide as Markdown

for feeding to an AI agent · ~185 KB · 2.5k lines

.md

The 2.5k-line source guide — paste the path into Claude Code or Codex and the agent drives the migration from there.

Part 0 · Why bother

Why bother with any of this?

Other reasons, in rough order of how often they matter

Why else self-host?

Reason	What it unlocks
You own your history	Slack's 90-day retention on Free, plus dead-link exports, means the moment you stop paying, your history is effectively gone. Self-hosted Mattermost keeps data in a Postgres you can back up, restore, inspect, and re-import.
Compliance without the BAA premium	You're the data custodian; you sign your own BAA, DPA, SCCs. Mattermost Team Edition (free) supports SSO via OAuth/SAML with the Professional Edition upgrade at $10/user/month if needed — still well below Slack Business+.
AI features, your way	Slack's enterprise tier bundles AI into the price. With Mattermost you pick: OpenAI, Anthropic, Groq, your own Llama-on-a-GPU, or no AI at all. Cost scales with actual usage, not per-seat.
No vendor price hikes	Your costs are fixed infrastructure rented by the month; no one quietly raises the seat price or changes the retention policy overnight.
Works on a locked-down network	Useful for regulated industries, field teams on unreliable internet, or a deliberate “no cloud” policy.
No seat counting	No guest-user surcharge, no “inactive user” rebuilds. Mattermost Team Edition doesn't have the same SKU inventory Slack does.

The 60-second version

Read this first, even if you never run a command.

The overall flow:

You decide a few things (plan tier, domain, server size, cutover date, rollback owner).
An AI agent runs Phase 1 on your laptop — downloads Slack history, pulls every file while the link still works, resolves user emails, packages it into one zip.
The agent runs Phase 2 — SSHes into an Ubuntu server, installs Mattermost behind Cloudflare, rehearses on a throwaway copy, runs the real cutover once the fail-closed readiness gate says green.
Users activate their accounts at https://chat.yourdomain.com/reset_password with their Slack email.

For non-technical operators

Can a non-technical person do this?

What you actually do:

Action	Effort
Paste tokens the agent asks for (Slack admin, Cloudflare, Postmark).	One browser-tab fetch per token.
Click “Approve” on permission prompts before the agent does something destructive.	~20–40 approvals, 5 seconds each.
Read a few reports (readiness score, reconciliation output, cutover status).	5–15 minutes per report.
Send user comms at cutover (copy-paste from templates).	5 minutes total.

Two things the agent cannot do for you:

Order the server at Hetzner (or OVH, Contabo). Hetzner requires ID verification on the human paying. You sign up, ID-verify (~2 hours clearance during business hours), and click “Order”; the agent does everything from there.
Pick a named rollback owner for cutover. This is you, or someone you designate, who has pre-committed to making the call to abort if cutover goes sideways. Phase 2 refuses to run cutover without ROLLBACK_OWNER set, on purpose.

When you’re done

What you end up with

A self-hosted Mattermost 10.11+ server behind Cloudflare with Origin CA TLS and proper WebSocket upgrade.
All your Slack history (public, private, DMs, group DMs, threads, reactions) imported and searchable.
File attachments either in local storage or Cloudflare R2 — preserved, not linked.
Custom emoji, canvases (as sidecar HTML posts), lists (as sidecar JSON posts), and admin audit CSVs (as sidecar posts in a dedicated channel). Nothing Slack-native gets silently dropped.
User accounts pre-created, matched by email. Users activate via /reset_password with their Slack email.
A complete evidence pack: SHA-256 hashes of every raw ZIP, enriched ZIP, import ZIP; reconciliation reports; cutover status JSON; activation proof.

How long this takes

Timeline and effort expectations

Phase	Duration	Your attention
Slack export approval (Business+)	1–7 days, out of your control	none while waiting
Download + enrich + transform	1–6 hours, scales with data	5–15 min to kick off
Server provisioning + deploy	20–60 min	approve SSH/install prompts
Staging rehearsal	1–4 hours	10 min kick-off + read report
Production cutover window	15–45 min after staging green	full attention (approvals, comms)
Activation week	3–7 days	respond to help-desk questions

Before you start

Which path through this guide is for you?

There are three supported paths. Pick one now and stay with it — they produce the exact same result, the only difference is how the skills get onto your machine and how you drive the agent.

Path	Who it’s for	Where skills live	What you install
A: Desktop app + jsm	Prefers clicking over typing; Mac or Windows laptop. Recommended for most.	jsm manages ~/.claude/skills/ (and ~/.codex/skills/) for you.	Claude Code desktop app or Codex desktop app, plus the jsm CLI.
B: CLI only	Comfortable with terminals; wants the leanest install.	Manual symlink or jsm install.	Claude Code CLI or Codex CLI.
C: CLI + jsm	Wants the CLI but wants skills auto-synced across machines.	jsm-managed.	CLI plus jsm.

Decision tree

Quick routing before you commit

┌────────────────────────────────────────────────────────────────┐
│ What Slack plan are you on?                                    │
└────────────────────────────────────────────────────────────────┘
    │
    ├── Free or Pro ──────→ Track B (slackdump-primary). See §3.
    │                       Expect: public + accessible private channels
    │                       and DMs only. Other people's DMs are invisible.
    │
    ├── Business+ ───────→ Track A (official admin export). See §3.
    │                       Expect: full workspace content.
    │
    └── Enterprise Grid ─→ Track C (grid split). See §Grid-migration.
                            Either grid-wide export + split, or
                            per-workspace exports.

┌────────────────────────────────────────────────────────────────┐
│ Where will Mattermost live?                                    │
└────────────────────────────────────────────────────────────────┘
    │
    ├── Hetzner AX42/AX52 dedicated (recommended) ─→ §2.3 sizing
    ├── OVH Advance / Contabo VPS ─────────────────→ same table, cheaper
    └── Existing infra you run ─────────────────────→ supply SSH target

┌────────────────────────────────────────────────────────────────┐
│ How do you want to drive the agent?                            │
└────────────────────────────────────────────────────────────────┘
    │
    ├── Click, don't type ───→ Path A (Desktop app). See §Part 1.
    ├── Terminal-native ────→ Path B (CLI-only).
    └── Multi-machine ──────→ Path C (CLI + jsm for cross-device sync).

┌────────────────────────────────────────────────────────────────┐
│ Where is your Mattermost database going to live?               │
└────────────────────────────────────────────────────────────────┘
    │
    ├── Same box as Mattermost (default)  →  POSTGRES_DSN=postgres://…@localhost:5432
    │                                         Skill provisions local PG for you.
    ├── Supabase (managed)                →  Supabase session pooler on 5432
    │                                         (NOT the transaction pooler on 6543).
    └── Your own managed PG               →  Provide the DSN; skill is hands-off.

The math

The money math.

Why now

Why this wasn’t practical before.

The specific pair of skills this whole piece is about:

slack-migration-to-mattermost-phase-1-extraction runs on your laptop. Picks Track A / Track B / Track C based on your Slack plan, pulls the content, downloads every file before the link expires, resolves users to emails, extracts canvases and lists as sidecar content, transforms through mmetl, patches the JSONL, packages the ZIP, runs five validators, and emits a hash-anchored evidence pack.
slack-migration-to-mattermost-phase-2-setup-and-import runs from the same laptop over SSH to a fresh Ubuntu VPS. Provisions the server, installs Mattermost and Nginx, wires up Cloudflare, rehearses the import on a throwaway staging target, computes a fail-closed readiness gate, and executes the production cutover with explicit rollback semantics.

Part 1 · one-time setup

Workstation setup: day zero to first skill call.

§1.0

Day zero — order a server and wire up SSH

1.0.1

Order a Hetzner dedicated server

Go to hetzner.com/dedicated-rootserver and click Server Auction. The auction has the same specs at lower prices.
Sign up with company email. Hetzner requires government-ID upload for first-time verification; usually clears in 1–2 hours during German business hours.
Pick an AX42 (up to ~250 users) or AX52 (250–1,000 users) from the auction. Prefer NVMe storage. Datacenter: Falkenstein or Helsinki for EU, Ashburn for US.
OS: Ubuntu 24.04 LTS (noble). If 24.04 isn’t offered, pick 22.04 LTS and upgrade post-provision.
Leave Rescue System and KVM on defaults. Do not set a root password. Paste your SSH public key (from §1.0.3 below) into the “SSH keys” field.
Submit. You’ll receive a “Server installed” email with the IP and confirmation the key was installed.

1.0.2

I don’t have a domain yet

Cloudflare Registrar — at-cost ~$10/year for .com, auto-adds the zone to Cloudflare. Fastest path.
Any existing registrar (GoDaddy, Namecheap, Porkbun, Route 53) — update nameservers to Cloudflare later. See §Cloudflare walkthrough.

Buy the domain now. DNS propagation after nameserver update takes 15 minutes to 24 hours; you want that clock running in parallel with ID-verification.

1.0.3

Generate an SSH keypair on your laptop

macOS

ssh-keygen -t ed25519 -C "your_email@example.com"
# press Enter to accept default path (~/.ssh/id_ed25519)
# passphrase is optional; empty is acceptable if your disk is encrypted

cat ~/.ssh/id_ed25519.pub
# copy the ssh-ed25519 AAAAC3... line into Hetzner's order form

Windows 10/11 (PowerShell)

ssh-keygen -t ed25519 -C "your_email@example.com"
# files land in C:\Users\<you>\.ssh\
Get-Content $HOME\.ssh\id_ed25519.pub

1.0.4

First SSH login after the server is installed

ssh root@95.217.12.34     # replace with your real IP
# SSH prints a host-key fingerprint — type 'yes' to record it in ~/.ssh/known_hosts
# you should land at root@Ubuntu-...#
# type 'exit' to return

If you lose your private SSH key (recoverable)

Boot into Hetzner’s rescue system (robot UI → server → Rescue → activate Linux rescue → reboot). Get a temp root password by email, SSH in, mount the installed filesystem (mount /dev/sda1 /mnt), paste a new public key into /mnt/root/.ssh/authorized_keys, umount, reboot. Works for every provider with a rescue console.
Re-order the server and start fresh. If you’re at day zero and nothing is installed yet, this is faster than rescue-system diagnosis.

Sidebar: Windows-specific notes

PowerShell, not Command Prompt — this article’s commands assume a POSIX-ish shell. On Windows, PowerShell 7+ or Git Bash.
Install Git for Windows (git-scm.com/downloads/win). Provides git plus Git Bash.
Chocolatey is the Windows equivalent of Homebrew — install from chocolatey.org/install in an Admin PowerShell.
WSL2 is optional but convenient: wsl --install -d Ubuntu-24.04, then wsl.
Paths: Mac-style ~/.claude/skills/ = Windows %USERPROFILE%\.claude\skills\.
Symlinks need Admin PowerShell (New-Item -ItemType SymbolicLink) or Git Bash with Developer Mode.
SSH built into Windows 10 (1809+) and 11. Run ssh -V; if missing, Settings → Apps → Optional Features → OpenSSH Client.

§1.1

Pick an agent harness (GUI app or CLI)

You need one of the following. Either can run the skills end to end. Both Claude Code and Codex ship as GUI desktop apps and as CLIs.

Option	Requires	Install
1a · Claude Code desktop	Anthropic Pro, Max, Team, or Enterprise plan	Download from claude.ai/download · sign in · open Code tab · Select folder
1b · Codex desktop	ChatGPT Plus/Pro/Business/Edu/Enterprise, or OpenAI API key with Codex access	Download from developers.openai.com/codex/app · sign in · pick project folder
1c · Claude Code CLI	Anthropic plan	npm install -g @anthropic-ai/claude-code · claude login · claude in your workdir
1d · Codex CLI	ChatGPT plan or API key	Install from github.com/openai/codex · codex login · codex in workdir

What “running the skill” looks like

In all four options, running a skill means opening a session in your working directory and asking the agent, in plain English, to use it. Examples:

Desktop app: type / in the prompt box to see slash commands, pick slack-migration-to-mattermost-phase-1-extraction. Or just say “Use the Phase 1 Slack-to-Mattermost skill to run the setup stage.”
CLI: claude (or codex) in the workdir, then the same plain-English request.

Behind the scenes the agent runs ./migrate.sh setup for you and shows the output. You’ll see commands flash by; you don’t need to memorize them.

§1.2

Install the two skills

Skill catalog pages · open in a new tab

jeffreys-skills.md/skills/slack-migration-to-mattermost-phase-1-extraction — Phase 1, the Slack-side extraction skill.
jeffreys-skills.md/skills/slack-migration-to-mattermost-phase-2-setup-and-import — Phase 2, the Mattermost-side deploy + import skill.
jeffreys-skills.md/skills/slack-migration-to-mattermost-phase-3-ongoing-mattermost-maintainance — Phase 3, the ongoing-maintenance skill (weekly sweep, auto-rollback upgrades, restore drills).

Three ways to install. Pick whichever matches the path you chose above.

Recommended: via jsm (Jeffrey’s Skills.md)

# macOS / Linux
curl -fsSL https://jeffreys-skills.md/install.sh | bash
# Windows (PowerShell as Admin)
irm https://jeffreys-skills.md/install.ps1 | iex

jsm setup                        # first-time wizard: creates config, picks skill dirs
jsm login                        # opens browser → sign in with Google
jsm install slack-migration-to-mattermost-phase-1-extraction
jsm install slack-migration-to-mattermost-phase-2-setup-and-import

Alternative: via claude plugins

claude plugins install slack-migration-to-mattermost-phase-1-extraction
claude plugins install slack-migration-to-mattermost-phase-2-setup-and-import

Alternative: symlink from a local clone (developers only)

ln -s /path/to/je_private_skills_repo/.claude/skills/slack-migration-to-mattermost-phase-1-extraction  ~/.claude/skills/
ln -s /path/to/je_private_skills_repo/.claude/skills/slack-migration-to-mattermost-phase-2-setup-and-import ~/.claude/skills/
# mirror to Codex too:
ln -s /path/to/je_private_skills_repo/.claude/skills/slack-migration-to-mattermost-phase-1-extraction  ~/.codex/skills/
ln -s /path/to/je_private_skills_repo/.claude/skills/slack-migration-to-mattermost-phase-2-setup-and-import ~/.codex/skills/

On Windows (Git Bash or PowerShell 7+ as Admin), use mklink /D or New-Item -ItemType SymbolicLink.

Verify

jsm list                          # lists installed skills + versions
ls -la ~/.claude/skills/ | grep slack-migration
# Windows:
dir %USERPROFILE%\.claude\skills

§1.3

Bootstrap the workstation for Phase 1

Installs the underlying CLI tools the skill shells out to: slackdump does extraction, mmetl does transformation, mmctl does import upload, and so on.

cd ~/.claude/skills/slack-migration-to-mattermost-phase-1-extraction
./scripts/doctor.sh                    # what's missing?
./scripts/bootstrap-tools.sh           # install missing system + Go tools
./scripts/doctor.sh                    # confirm all required checks are green

If something goes wrong

command not found: ./scripts/doctor.sh → you forgot the cd, or the skills dir is elsewhere. Find it with jsm list.
permission denied → run chmod +x scripts/*.sh inside the skill dir, then retry.
One Go install fails (bad network, yanked release) → the script warns and continues. Re-run once network cooperates.
Windows permission errors → open PowerShell as Administrator.

§1.4

Bootstrap the workstation for Phase 2

cd ~/.claude/skills/slack-migration-to-mattermost-phase-2-setup-and-import
./scripts/doctor.sh                       # what's missing?
./scripts/bootstrap-tools.sh              # install workstation-side tools
./scripts/doctor.sh --require-remote      # probe SSH to your target once TARGET_HOST is set

§1.5

Wire up MCP servers (optional but recommended)

The skills ship installers that register Slack / Playwright / Mattermost MCP servers into whichever agent CLIs you have.

# Phase 1 (workstation)
./scripts/install-mcp-servers.sh
./scripts/doctor.sh --require-mcp

# Phase 2 (workstation)
./scripts/install-mcp-servers.sh
./scripts/doctor.sh --require-mcp

MCP	When it helps	Phase
Slack MCP (Anthropic official, xoxb-)	“count channels”, “verify last message in #general”, “check user U0ABC’s email”	Phase 1
Slack MCP stealth (korotovsky, xoxc- + xoxd-)	full visibility including DMs for gap-fill verification	Phase 1
Playwright MCP	drives the Slack admin UI’s export flow, or Mattermost System Console screens that lack API equivalents	Phase 1 + 2
Mattermost MCP (community, admin PAT)	“which users are inactive”, “stamp a test post”, “list team roles”	Phase 2

You do not need any of these for the skill itself to run. They are accelerators for verification, gap-hunting, and UI steps. See the §MCP worked examples section later for concrete prompts.

Part 2 · pre-flight

Before you touch Slack.

Three things need to be decided before your first ./migrate.sh export call. Spending 20 minutes on these now saves hours downstream.

§2.1

Slack plan tier and export privileges

Log into Slack as an owner/admin and open Workspace Settings → Security → Import & export data. The export page tells you which scope you’re authorized for:

Free or Pro: public channels only. Private channels, DMs, and group DMs cannot be exported via the official path. Phase 1 routes you into Track B (slackdump as primary) and emits an explicit unresolved-gaps.md listing the private content it can’t pull.
Pro with legal exception: Workspace Owners can apply to Slack for full export under “valid legal process, consent of members, or a requirement under applicable laws.” If granted → Track A.
Business+ or Enterprise Grid: full content export of public, private, and DM is available. Track A is the default path.

Write down the answer. The value goes into config.env as SLACK_PLAN_TIER and controls several downstream validators.

§2.2

Scope of the export

Default: full history from workspace creation to now. Before you commit:

Is there content legal has told you must not be exported? (A private HR channel whose members did not consent, for example.) Exclude those channels via Slack admin before the export, or accept them and redact post-export.
Are there moribund channels older than your retention policy that you’d rather never import? Leave them in Slack and skip them in the Mattermost archive-channel mapping.
Is the export size going to blow past the server’s disk budget? Rule of thumb: plan for 3× the compressed Slack export size of free disk. For many years of heavy attachments, use split-phase1-import.py (per-year batch ZIPs).

§2.3

Server sizing

Mattermost’s official 1000-user recommendation is 4 vCPU / 8 GB RAM / 90–180 GB storage. That’s bare-minimum. Real production wants headroom:

User count	Target hardware	Hetzner	OVH	Contabo	Est. $/mo
Up to 50	2 vCPU / 4 GB / 80 GB SSD	AX21 or small VPS	VLE-4	VPS M	$10–20
50–250	4 vCPU / 16 GB / 250 GB NVMe	AX42 / CCX23	Advance-1	VPS L	$40–60
250–1000	8 cores / 64 GB / 2×1 TB NVMe RAID 1	AX52 (recommended)	Advance-2	VPS XL	$65–90
1000+	8–16 cores / 64–128 GB, separate PG	AX52 + Supabase Pro	Advance-2 + managed PG	enterprise	$100–300+

Four values go into config.env.phase2 when the agent asks; you’re picking a name, not doing setup:

Field	What	Notes
DOMAIN	Typically chat.yourdomain.com	Add to Cloudflare if not already there (§Cloudflare walkthrough).
SMTP	Mailgun, Postmark, SES, or Google Workspace relay	Sign up for a provider; the agent wires credentials into Mattermost. Users can’t log in without password-reset emails.
ADMIN_EMAIL	A mailbox you own	The agent creates the Mattermost admin account during deploy. Password is generated; store in 1Password.
ROLLBACK_OWNER	A named human (can be yourself)	Phase 2 refuses cutover without this set, so it’s enforced.

§2.4

How you drive the skill

Shortcut: hand the agent the guide

Open your Claude Code or Codex session in your working directory and paste something like:

The agent produces a tailored checklist, tells you which tokens to collect, and pauses before each destructive step. Download the guide with the button near the top of this page.

§2.4 · cont.

The pause-and-confirm pattern

When to say yes to a permission prompt

Non-technical operator cheat-sheet

Looks like	Decision
./migrate.sh <stage> / ./operate.sh <stage> matching the stage you asked for	Approve
ssh <user>@<your TARGET_HOST>	Approve (confirm hostname matches config.env)
mmctl <anything> --url https://<your MATTERMOST_URL>	Approve (confirm URL is yours)
curl to jeffreys-skills.md / hetzner.com / cloudflare.com / your own domain	Approve
sudo apt install <package> during bootstrap-tools.sh or provision	Approve
psql / pg_dump / pg_restore against $POSTGRES_DSN or $SCRATCH_DB_URL	Approve
rm -rf /opt/mattermost or delete outside workdir/	Deny and ask why
ssh <some unknown hostname>	Deny
Anything reading ~/.ssh/id_* and piping somewhere	Deny and investigate
git push to a remote you didn’t set up	Deny
Anything right after the agent has seemed confused	Deny and re-read prompt

When in doubt, type: “Explain what this command does and why you’re running it at this stage.” The agent will tell you.

Keep your laptop awake

During long stages

Phase 1 enrich and Phase 2 staging / cutover can run 30–120 min. If your laptop sleeps mid-run, the SSH session dies and the stage aborts.

# macOS — separate Terminal tab, leave running
caffeinate -dims

# Windows — PowerShell as Admin
powercfg /requestsoverride process powershell.exe DISPLAY SYSTEM AWAYMODE
# reverse when done
powercfg /requestsoverride process powershell.exe

# Simplest: plug in, disable sleep for the migration week, re-enable after

The two-phase pipeline

Phase 1 → handoff → Phase 2.

Part 3 · Phase 1

Driving Phase 1 — extraction and transformation.

The canonical Phase 1 pipeline:

setup  ->  export  ->  enrich  ->  transform  ->  package  ->  verify  ->  handoff

You can run ./migrate.sh all to chain the whole thing; in practice most operators step through stage by stage and read the reports between each.

§3.1

Set up the working directory (stage: setup)

Pick a working directory with plenty of disk. For a 50-user workspace, 50 GB free is enough. For 1,000 users with heavy file attachments, assume 500 GB to 1 TB.

mkdir -p ~/slack-migration/acme
cd ~/slack-migration/acme
cp ~/.claude/skills/slack-migration-to-mattermost-phase-1-extraction/config.env.example ./config.env
$EDITOR config.env

Minimum fields for a Business+ / Track A run:

WORKSPACE_NAME="acme-slack"
SLACK_PLAN_TIER="Business+"
PHASE1_WORKSPACE_ROOT="./workdir"
MATTERMOST_TEAM_NAME="acme"
MATTERMOST_TEAM_DISPLAY_NAME="Acme Corp"

# Fill one of these two blocks:
# (A) official export — paste the path to the downloaded ZIP here.
SLACK_EXPORT_ZIP=""
SLACK_CHANNEL_AUDIT_CSV=""
SLACK_MEMBER_CSV=""
# (B) slackdump-primary — fetch tokens from a logged-in browser session.
# SLACK_TOKEN="xoxp-..."     # slack app user token, for enrichment API calls
# SLACKDUMP_PRIMARY="1"

§3.2

Acquire the Slack export (stage: export)

Three possible paths — work out which one you’re on, then execute.

3.2.1

Track A — official admin export (recommended when available)

Slack has no public API to trigger a workspace export; it’s a UI-only operation. Three sub-paths past that:

Agent-driven via Playwright MCP (recommended). If the Playwright MCP is registered, ask the agent: “Open the Slack admin export page and kick off an export for the full date range. Wait for the email, grab the download URL, and pull the ZIP into artifacts/raw/.” The agent opens a browser session, clicks through, waits for mail, completes intake. You approve browser-control permission once.
Automated via SLACK_EXPORT_AUTOMATION=1. Set a Slack session cookie in config.env and point the skill at an IMAP mailbox; automate-official-export.py does the POST, polls for the email, downloads the ZIP, hashes, writes provenance. This is the path for recurring baseline+delta cadences.
Fully manual. Click through the Slack admin UI yourself, wait, download, tell the agent where you saved it. The agent runs ./migrate.sh export to hash and write manifest.raw.json.

Regardless of which sub-path, the working directory ends up with:

workdir/artifacts/raw/
├── slack-export.zip           # hashed
├── channel-audit-YYYY-MM-DD.csv   # hashed
├── member-list-YYYY-MM-DD.csv     # hashed (if available)
└── manifest.raw.json          # names every file + its SHA256

3.2.2

Track B — slackdump as primary (Pro / Free, or official unavailable)

./migrate.sh export

3.2.3

Track C — Enterprise Grid with per-workspace export

Common to all tracks

Channel-audit CSV, member list, workflows

§3.3

Enrich the export (stage: enrich)

./migrate.sh enrich

What runs under the hood:

run-slack-advanced-exporter.sh fetch-emails — resolves Slack user IDs to email addresses, rewriting users.json in place inside a copy of the ZIP. Requires xoxp- with users:read.email.
run-slack-advanced-exporter.sh fetch-attachments — walks every message’s files[] and downloads bytes into __uploads/F<id>/<filename> inside the enriched ZIP. Requires xoxp- with files:read.
export-custom-emoji.py — hits Slack’s emoji.list API, downloads every custom emoji image, writes a manifest plus an alias map.
extract-phase1-sidecars.py — pulls canvases, lists, integration_logs.json, and any admin CSV / workflow JSON from PHASE1_SIDECAR_INPUTS or PHASE1_WORKFLOW_INPUTS into a sidecar bundle.
build-artifact-manifest.py — rewrites manifest.enriched.json with hashes for all new artifacts.

§3.4

Transform to Mattermost bulk-import format (stage: transform)

./migrate.sh transform

--team "$MATTERMOST_TEAM_NAME" — target team name.
--default-email-domain — only if MMETL_DEFAULT_EMAIL_DOMAIN is set (use when some Slack users have no email; mmetl fabricates <username>@<domain>).
--skip-empty-emails, --discard-invalid-props — passed via MMETL_EXTRA_FLAGS if needed.
--attachments-dir data/bulk-export-attachments — forces binary files into the canonical import location.

§3.5

Patch and package (stage: package)

mmetl gets you close but not all the way. Three things still need patching into the JSONL:

Custom emoji objects (must go before the first team line).
Archive channels for sidecar content (slack-canvases-archive, slack-lists-archive, slack-export-admin), and a post per canvas, list, or admin artifact that attaches the sidecar file.
User membership into those archive channels (otherwise no one can see them in Mattermost).

./migrate.sh package

§3.6

Verify and build the evidence pack (stage: verify)

This is the most important stage because it catches silent data loss.

./migrate.sh verify

It runs five validators:

validate-phase1-artifacts.py — hashes in manifest.*.json match files on disk; required artifacts (ZIP, CSV, JSONL, final ZIP) all exist.
validate-phase1-jsonl.py — JSONL is well-ordered (version, emoji, team, channel, user, post, direct_channel, direct_post), every thread_ts reference is to an earlier post, every channel has at least one member, counts are non-zero.
validate-enrichment-completeness.py — every files[] entry in the enriched ZIP has a downloaded binary; every user in users.json has an email (or a documented exception).
reconcile-phase1-counts.py — message counts across raw ZIP, enriched ZIP, channel-audit CSV, and JSONL all agree within tolerance. Channels in the audit CSV but missing from the JSONL are reported as discrepancies with severity.
export-integration-inventory.py — parses integration_logs.json and emits integration-inventory.md, a concrete list of bots, webhooks, and apps that must be rebuilt in Mattermost post-cutover.

§3.7

Handoff (stage: handoff)

./migrate.sh handoff

Emits the three artifacts Phase 2 needs to trust your bundle:

handoff.md — human-readable summary for you and the war room.
handoff.json — the machine-readable contract. Contains schema_version, generated_at, workspace, plan_tier, export_basis, final_package.path, final_package.sha256, jsonl_path, manifests[], counts (users, channels, posts, DMs, emoji, attachments), sidecar_channels[], and known_gaps[].
unresolved-gaps.md — one entry per classified gap, each with disposition class (native-importable / sidecar-only / manual-rebuild / unrecoverable).

Part 4 · Phase 2

Driving Phase 2 — deploy, rehearse, cut over.

Setup

Open a fresh session, copy the config

cd ~/slack-migration/acme
cp ~/.claude/skills/slack-migration-to-mattermost-phase-2-setup-and-import/config.env.example ./config.env.phase2
echo "HANDOFF_JSON=$(pwd)/workdir/artifacts/reports/handoff.json"    >> ./config.env.phase2
echo "IMPORT_ZIP=$(pwd)/workdir/artifacts/import-ready/mattermost-bulk-import.zip" >> ./config.env.phase2
$EDITOR ./config.env.phase2

export PHASE2_CONFIG=./config.env.phase2

Minimum fields for a typical VPS deployment with self-hosted PostgreSQL on the same box:

WORKSPACE_NAME="acme-slack"
PHASE2_WORKSPACE_ROOT="./workdir-phase2"
HANDOFF_JSON="<abs path>"
IMPORT_ZIP="<abs path>"

MATTERMOST_URL="https://chat.acme.com"
MATTERMOST_ADMIN_USER="admin"
MATTERMOST_ADMIN_PASS="<strong random password>"
MATTERMOST_TEAM_NAME="acme"

TARGET_HOST="chat.acme.com"
TARGET_SSH_USER="root"
DEPLOY_METHOD="apt"          # "apt" for production, "docker" for staging
PROVISION_MODE="ssh"
DEPLOY_MODE="ssh"

POSTGRES_DSN="postgres://mmuser:<pwd>@localhost:5432/mattermost?sslmode=disable"
SMOKE_DATABASE_URL="${POSTGRES_DSN}"

SMTP_SERVER="smtp.postmarkapp.com"
SMTP_PORT="587"
SMTP_USERNAME="<postmark-token>"
SMTP_PASSWORD="<postmark-token>"
SMTP_TEST_EMAIL="admin@acme.com"

CLOUDFLARE_ENABLED="1"
CLOUDFLARE_MODE="plan"                # "plan" prints, "execute" uses CF API
CLOUDFLARE_API_TOKEN="<zone edit token>"
CF_ZONE_ID="<zone id for acme.com>"
ORIGIN_SERVER_IP="<IP address>"

ROLLBACK_OWNER="Jane Admin"

Then the Phase 2 pipeline:

intake  ->  render-config  ->  edge  ->  provision  ->  deploy  ->  verify-live
        ->  staging  ->  restore  ->  ready  ->  cutover

§4.1

Intake the Phase 1 handoff (stage: intake)

./operate.sh intake

If this fails, do not force through. Typical failure modes:

The ZIP moved between phases and the hash no longer matches → re-copy or re-run Phase 1’s handoff.
sidecar_channels[] is empty but Phase 1 produced sidecars → bug in Phase 1 config. Re-run ./migrate.sh handoff.

§4.2

Render config (stage: render-config)

./operate.sh render-config

SiteURL = $MATTERMOST_URL
ListenAddress = 127.0.0.1:8065 (never exposed directly)
SqlSettings.DataSource = $POSTGRES_DSN
MaxPostSize = 16383 (Slack allows 40000; default 4000 would truncate)
MaxFileSize = 52428800 (50 MB)
EnableOpenServer = true (required for bulk import to create users)
EnableSignUpWithEmail = true + RequireEmailVerification = false
SMTP block from $SMTP_*
AllowCorsFrom = whatever you put in ALLOW_CORS_ORIGINS if fronted by multiple hostnames

§4.3

Cloudflare edge (stage: edge)

./operate.sh edge

Create/update chat.acme.com A record pointing at $ORIGIN_SERVER_IP, orange-clouded.
Generate a 15-year Cloudflare Origin CA certificate for chat.acme.com, save to workdir-phase2/rendered/origin.{pem,-key.pem}.
Optionally create a second grey-clouded calls.acme.com for the Calls plugin’s UDP 8443 traffic.

§4.4

Provision the host (stage: provision)

./operate.sh provision

Generates provision-host.sh (plan script) and in ssh mode executes it over SSH against TARGET_HOST. What the plan does:

apt-get install -y curl jq nginx ufw fail2ban unattended-upgrades postgresql-client (or postgresql too when local PG is provisioned).
Opens UFW for 22/tcp, 80/tcp, 443/tcp, 8443/udp (Calls). Enables UFW.
Enables fail2ban and unattended-upgrades.
If local Postgres is provisioned, creates the Mattermost role + database from the DSN credentials.

§4.5

Deploy Mattermost + Nginx (stage: deploy)

./operate.sh deploy

Runs deploy-mattermost-stack.sh in whichever mode you set. For APT:

curl -o- https://deb.packages.mattermost.com/repo-setup.sh | bash -s mattermost
apt-get install -y mattermost nginx
Install rendered config.json to /opt/mattermost/config/config.json with 0600 mattermost:mattermost.
Install rendered mattermost.nginx.conf to /etc/nginx/sites-available/, symlink, install origin cert + key if present.
nginx -t then systemctl enable --now nginx and systemctl enable --now mattermost.

§4.6

Verify live stack (stage: verify-live)

./operate.sh verify-live

Three HTTPS probes, 6 retries, 5 s apart to absorb JIT startup:

GET /api/v4/system/ping → expect 200 + JSON {"status":"OK"}.
WebSocket upgrade against /api/v4/websocket → expect 101 Switching Protocols.
SMTP reachability: TCP connect to $SMTP_SERVER:$SMTP_PORT + STARTTLS negotiation.

§4.7

Staging rehearsal (stage: staging)

./operate.sh staging

Recommended staging path

A second cheap VPS that mirrors production at ~$4–10/mo, kept alive only for the rehearsal window.

Order a staging VPS (Hetzner CX22 €4/mo, Contabo VPS S $4/mo, OVH VLE-1). Ubuntu 24.04, same SSH key.
Add a DNS record for staging.chat.yourcompany.com pointing at the VPS’s IP (grey-clouded fine).
Copy your production config to config.env.phase2.staging and override: STAGING_URL, TARGET_HOST, MATTERMOST_URL.
Run the full Phase 2 pipeline: PHASE2_CONFIG=./config.env.phase2.staging ./operate.sh intake render-config provision deploy verify-live staging.
After cutover is confirmed green on production, cancel the staging VPS. Total cost ~<$10 for a full-scale dress rehearsal.

§4.8

Restore drill (stage: restore, optional but recommended)

./operate.sh restore

§4.9

Compute readiness (stage: ready)

./operate.sh ready

Runs validate-cutover-readiness.py, generate-readiness-score.py, and generate-phase2-readiness.py to produce the fail-closed gate covered in the next section.

§4.10

Cutover (stage: cutover)

Only run after ready says green and the war room has explicitly called go.

./operate.sh cutover

Under the hood, execute-production-cutover.sh runs the same import-upload-process-monitor loop as staging, plus:

Post-import smoke (against production DB).
Reconciliation vs. handoff (production observed counts).
Activation proof: if SMTP_TEST_EMAIL is set, triggers a password-reset flow against the live Mattermost and confirms the email arrives with a reset link that resolves to https://chat.acme.com/reset_password.

Rollback:

ROLLBACK_CONFIRMATION="I_UNDERSTAND_THIS_RESTORES_BACKUPS" ./operate.sh rollback

An asymmetric bet.

You order a Hetzner server. The agent sets it up and imports your history into it. You run a full staging rehearsal on a throwaway copy. Slack is untouched.

You log into the new Mattermost yourself, click around, read your DMs, spot-check the big channels. Still untouched.

You optionally activate a few volunteers on Mattermost and let them use both in parallel for a few days. Slack is still source of truth.

Only when you are satisfied do you flip Slack to read-only and do the final cutover. Even then, Slack stays accessible as a read-only archive until you choose to downgrade or cancel.

That is the asymmetric bet. Downside is small and recoverable. Upside is tens of thousands of dollars a year, indefinitely.

What survives the move.

The fail-closed gate.

cutover-readiness.json

phase2-intake-report.json
config-validation.json
live-stack.md
latest-staging.json
latest-smoke.json
latest-reconciliation.json
latest-restore.json
ROLLBACK_OWNER

§10.8

MCP worked examples — what each server unlocks.

You installed MCP servers back in §1.5. Here is what each one actually gives the agent, with concrete prompts you can paste.

Slack MCP (Anthropic official, xoxb-)

Read access while Slack is still alive

“Use the Slack MCP to count the total messages in #general over the last 90 days and compare to Phase 1’s channel-audit CSV for the same channel.”
“Use the Slack MCP to list every user whose email ends in @acme.com but who hasn’t posted in 6 months. I want to decide whether to exclude them from the migration.”
“Fetch the 3 most-recent messages in the support channel so I can compare them byte-for-byte after import.”

Slack MCP stealth (korotovsky, xoxc- + xoxd-)

Full visibility for gap-fill verification

“Via the stealth Slack MCP, confirm that my export ZIP includes all my own DMs with Bob. The export should contain X messages; tell me if anything’s missing.”

Playwright MCP

Drives a real browser for UI-only work

“Use Playwright MCP to log into Slack admin and start a workspace export for dates 2023-01-01 to 2026-04-15. Wait for the email, click the download link, save the ZIP to ~/Downloads/, and tell me its SHA256.”
“In the Mattermost System Console, use Playwright to toggle EnableOpenServer=false after the import finishes. I don’t want to hand-edit config.json just for this.”

Mattermost MCP (community, admin PAT)

Direct API access to live Mattermost

“Via the Mattermost MCP, how many users have activated (non-zero last_activity_at) and how many are dormant?”
“List every bot user on the new Mattermost, and for each one tell me whether it was present in Phase 1’s integration-inventory.”
“Create a test post in #migration-check as the admin user, then delete it. I’m verifying the admin PAT works.”

§4.13

Cutover day, minute by minute.

§4.11

The Slack → Mattermost cutover day sequence

When	What happens
T − 24 h	Freeze Slack integrations (deactivate bots that auto-post). Send first user announcement: “Tomorrow we move to Mattermost at 10 AM. Slack will go read-only at 09:30. Please log in at chat.acme.com/reset_password using your Slack email starting at 10:15.”
T − 1 h	Final Phase 1 delta export (see baseline+deltas below). Import is idempotent so re-running does not double-post; it only catches new messages.
T − 15 min	Make Slack read-only. In Slack admin: Workspace settings → Permissions → Messages & files → disable posting for everyone except admins.
T = 0	./operate.sh cutover
T + cutover end	Confirm the newest cutover-status.<ts>.json has status == "success". Send activation announcement.
T + 1 h	Monitor /opt/mattermost/logs/mattermost.log and help desk. Watch for bounced password-reset emails, locked-out users, broken mentions.
T + 1 day	Check activation count: mmctl user list --all --json \| jq 'length'. Nudge stragglers.
T + 7 days	Revoke Slack migration app tokens, delete the Slack admin app. Archive Phase 1 / Phase 2 workdirs to long-term storage as the evidence pack.

§4.12

Baseline + deltas pattern

For workspaces that take more than a day to export and transform, use the baseline-plus-deltas pattern:

Baseline: run the full Phase 1 pipeline at T − several days. Do the Phase 2 staging rehearsal. Do not do production cutover yet.
Delta N: every few hours or daily, re-run Phase 1 against the same path (or against a new export covering only the recent range). Run ./operate.sh staging against production; since import is idempotent, this catches new messages without duplicating old ones.
Final delta: at T = 0, one last Phase 1 + Phase 2 staging run. Then ./operate.sh cutover, which is now essentially a no-op import of any final messages.

§4.13 · Acme Corp, 340 users

What cutover day looks like on your screen

Here is what you’ll actually see in the Claude Code or Codex desktop app between T-1h and T+30min, assuming a 340-user workspace.

T − 60 min — preflight readiness re-check

If any category is yellow or red, the agent stops and tells you why. Do not proceed past this point with anything red.

T − 15 min — freeze Slack, post the notice

T = 0 — kick off the cutover

Prompt	What it’s doing	Decision
ssh deploy@chat.acme.com 'sudo systemctl status mattermost'	Sanity-check Mattermost is up on target	Approve
mmctl auth login --url https://chat.acme.com …	Authenticate as sysadmin	Approve
mmctl import upload … 22-GB.zip	Stream the ZIP to the server	Approve
mmctl import list available --json	Read back what just landed	Approve
mmctl import process <filename>	Start the import job — moment of commit	Approve (destructive)
ssh deploy@chat.acme.com 'tail -f …/mattermost.log'	Tail server log for the import duration	Approve
psql "$POSTGRES_DSN" -c 'SELECT COUNT(*) FROM users'	Count imported users	Approve
curl -sf https://chat.acme.com/api/v4/system/ping	Verify Mattermost still serves	Approve

Between “import process” and “post-import count” is the longest wait. For a 340-user workspace with ~1.3 M posts, expect ~15–30 minutes. You’ll see a live stream of lines in the session:

{"ts":"...","state":"pending","progress":0}
{"ts":"...","state":"running","progress":0.12,"posts_imported":154000}
{"ts":"...","state":"running","progress":0.45,"posts_imported":578000}
...
{"ts":"...","state":"success","progress":1.0,"posts_imported":1284903}

Each line is written to workdir-phase2/reports/cutover/import-watch.*.jsonl so you can re-read them later.

T + ~20 min — reconciliation + activation

reconcile-handoff-vs-import.py: observed 337 users / 142 channels / 1284903 posts
                                 handoff 337 users / 142 channels / 1284903 posts
                                 status: ok (diffs: [])
activation: sending password-reset to admin@acme.com...
activation: reset_link_received = true (proof in latest-activation.json)
cutover-status.2026-04-22T14-31-04Z.json written
status: success

T + 30 min — confirm for yourself

If any step fails

Three common failures

Error	Fix
mmctl import upload: 413 Request Entity Too Large	Nginx client_max_body_size is too small. Raise to client_max_body_size 25G; in /etc/nginx/sites-enabled/mattermost.conf and sudo systemctl reload nginx.
import job state=error note='user foo@bar.com invalid email'	A user record slipped through without a valid email (usually a bot). Either set MMETL_DEFAULT_EMAIL_DOMAIN in Phase 1 and re-run from transform, or manually delete that user from the JSONL and re-import.
activation: reset_link_received = false	SMTP not working. Test with swaks (see §SMTP walkthrough). Does not block cutover success, but users can’t activate. Fix and re-run only the activation helper.

What approvals look like in the UI

In Claude Code desktop

Part 5 · post-cutover week

Activation, integrations, backups, file storage.

The skills hand off a working Mattermost. Users still need to activate, integrations still need to be rebuilt, and ops still needs to converge.

§5.1

Activation

Users receive the password-reset link via $MATTERMOST_URL/reset_password. To track activation rate, paste into the agent:

“What’s the current activation rate on Mattermost? List users who still haven’t logged in.”

The agent runs the relevant mmctl user list query and gives you a count plus a list. Ask it to filter by team, date, or email domain for a narrower slice.

If activation is under 50% by T+48h, send a reminder (templates in §comms kit). If under 80% by T+7 days, paste:

“For everyone who hasn’t activated, generate a temporary password, then email each of them with their password and the login URL. Show me the list before you send.”

§5.2

Rebuilding integrations

workdir/artifacts/reports/integration-inventory.md is your checklist. Typical categories:

Incoming webhooks (Slack → Slack): recreate one Mattermost incoming webhook per Slack one. Update the sender service (GitHub, Datadog, etc.) to POST to the new URL.
Outgoing webhooks: same trigger words, new endpoint.
Slash commands: recreate. Mattermost’s trigger-word matching differs from Slack’s; test each one.
Bot users: Mattermost bot framework is fine, or use a personal access token for light use cases.
Custom apps: port to Mattermost’s Plugin API (Go-native) or Apps Framework (HTTP + manifest).

For each: add a line to a tracking doc, assign an owner, verify it works, close it out.

§5.3

Backups and monitoring

Set up pg_dump nightly and ship off-site (Hetzner Storage Box or Cloudflare R2). Example cron:

# on the server, as deploy user
cat > /home/deploy/backup-mattermost.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
DATE=$(date +%Y%m%d)
pg_dump -U mmuser mattermost | gzip > /var/backups/mattermost/mm_${DATE}.sql.gz
find /var/backups/mattermost -name 'mm_*.sql.gz' -mtime +30 -delete
rclone copy /var/backups/mattermost/mm_${DATE}.sql.gz r2:mm-backups/
EOF
chmod +x /home/deploy/backup-mattermost.sh
(crontab -l 2>/dev/null; echo "0 3 * * * /home/deploy/backup-mattermost.sh") | crontab -

§5.4

File storage — local vs Cloudflare R2

Default is local at /opt/mattermost/data/. For production, consider switching to R2:

{
  "FileSettings": {
    "DriverName": "amazons3",
    "AmazonS3AccessKeyId": "<R2 access key>",
    "AmazonS3SecretAccessKey": "<R2 secret>",
    "AmazonS3Bucket": "mattermost-files",
    "AmazonS3Endpoint": "<accountid>.r2.cloudflarestorage.com",
    "AmazonS3Region": "",
    "AmazonS3SSL": true
  }
}

Part 7

Operator checklist — print and keep on the desk.

§7.1

Two days before

./scripts/doctor.sh green on the workstation (Phase 1 and Phase 2).
./scripts/doctor.sh --require-remote green (can SSH non-interactively to the target).
./scripts/doctor.sh --require-mcp green, if you’re using MCP servers.
DNS A record for chat.acme.com exists (orange-clouded if Cloudflare).
Server ordered and SSH reachable as root.
SMTP provider set up; swaks test email arrived.
Slack plan tier known, export scope decided, legal approval in hand if needed.

§7.2

One day before

Full Phase 1 pipeline done once (baseline); handoff.json + final ZIP + evidence pack exist.
./operate.sh intake + render-config + provision + deploy + verify-live green.
./operate.sh staging green; staging-observed counts match handoff counts.
./operate.sh restore green (or explicitly waived by rollback owner).
./operate.sh ready returns "status": "ready".
First user announcement sent with cutover time + reset URL.
Help desk bucket / channel named; on-call owner identified.

§7.3

Cutover day

T − 1 h: freeze Slack (admin UI). Start final Phase 1 delta export.
T − 15 min: confirm ./operate.sh ready still green with the final handoff.
T = 0: ./operate.sh cutover. Watch the newest workdir-phase2/reports/cutover/cutover-status.*.json.
T + cutover: send activation announcement. Watch help desk.
T + 4 h: mmctl user list --all --json | jq 'length' + spot-check top channels.
T + 1 day: activation reminder if < 50 %.
T + 7 days: revoke Slack tokens, delete migration app, archive workdirs to evidence storage.

§7.4

If cutover fails

Do not try to fix in place under time pressure. Check the note field in the newest cutover-status.*.json.
If the issue is mechanical (stuck mmctl job, config typo), fix and re-run cutover; imports are idempotent.
If the issue is data loss or state corruption, roll back: ROLLBACK_CONFIRMATION=I_UNDERSTAND_THIS_RESTORES_BACKUPS ./operate.sh rollback. The rollback restores the DB to the pre-cutover backup.
Unfreeze Slack and tell users you’re rolling back; commit to a new date.

Part 6

Troubleshooting index.

§6.1

Phase 1

Symptom	Likely cause	Fix
./migrate.sh setup can’t find slackdump or mmetl	Go-based tools not on PATH	./scripts/bootstrap-tools.sh again; add $(go env GOPATH)/bin to shell rc
intake-official-export.py fails with “invalid ZIP”	Download truncated or is an HTML error page	Re-download from the admin-email link; verify size matches
slack-advanced-exporter fetch-emails returns 403	SLACK_TOKEN lacks users:read.email scope	Reinstall the Slack app with proper scopes, re-issue token
mmetl transform panics on some post	Rare Slack message schema quirk	Set MMETL_EXTRA_FLAGS="--discard-invalid-props" and re-run transform
Reconciliation shows channels in audit CSV but not JSONL	mmetl dropped them; usually archived channels with zero messages in the window	Classify as native-importable but empty, or extend the export window

§6.2

Phase 2

Symptom	Likely cause	Fix
./operate.sh intake fails “hash mismatch”	ZIP got re-zipped between phases	Re-copy the canonical ZIP from Phase 1’s import-ready/
./operate.sh deploy on Ubuntu 25.10: no mattermost package	Repo doesn’t have a questing build yet	Switch DEPLOY_METHOD=docker and re-run; Docker images cover all distros
verify-live WebSocket check fails	Nginx missing the Upgrade / Connection: upgrade block	Re-run render-config; confirm deploy copied the regenerated nginx conf
verify-live SMTP fails but provider says creds are right	Provider’s outbound port 587 blocked for new accounts	Test from the server: nc -vz $SMTP_SERVER 587. Use port 465 + SSL, or contact provider
Staging import stuck in pending for > 10 min	mmctl import worker crashed	Check /opt/mattermost/logs/mattermost.log. mmctl import job cancel <id> and re-process
Reconciliation shows fewer users than handoff claims	--skip-empty-emails dropped users without emails	Set a fallback MMETL_DEFAULT_EMAIL_DOMAIN in Phase 1 and re-run
Users report password-reset email lands in spam	SPF / DKIM / DMARC not set for sender domain	Add the records in Cloudflare DNS per your SMTP provider’s docs
Cutover succeeds but users say “I can’t see #general history”	They weren’t added to the channel during import	mmctl channel users add myteam general <username>; investigate why their user_id wasn’t in the JSONL’s channel membership

§6.3

Evidence and audit

If you need to produce evidence later (compliance, audit, or a “prove we migrated this channel” question), everything is already on disk:

workdir/artifacts/reports/evidence-pack.json (Phase 1) — hashed manifest of everything produced, with provenance.
workdir-phase2/reports/ (Phase 2) — intake, config, live-stack, staging, smoke, reconciliation, cutover, activation, readiness. Each has JSON and MD siblings.

Tar them, encrypt with age or gpg, store off-site for as long as your retention policy requires.

§10.7

Resuming an interrupted migration.

Migrations take hours to days. Laptops sleep, SSH sessions drop, Cloudflare glitches. Safe-resume playbook:

Single most important fact

How to figure out where you are

Ask the agent

“Read the Phase 1 resume.md prompt and follow it” (or the Phase 2 equivalent). The agent will:

Inspect workdir/artifacts/ or workdir-phase2/reports/ and enumerate what exists.
Read the latest-*.json convenience copies (latest-staging.json, latest-smoke.json, latest-reconciliation.json, latest-activation.json, latest-restore.json) plus the newest cutover-status.*.json if present, and tell you the last green stage.
Recommend exactly one next move.

Driving without the agent

Cheat sheet

Symptom	Last green stage	Next action
manifest.raw.json exists but no enriched/ dir	export	./migrate.sh enrich
enriched/slack-export.enriched.zip exists but no JSONL	enrich	./migrate.sh transform
mattermost-bulk-import.zip exists but no verification.md	package	./migrate.sh verify
handoff.json exists	handoff	Move to Phase 2 intake
Any cutover-status.*.json with "status":"success"	cutover done	Post-cutover operations

Not safely idempotent

Exceptions

./operate.sh cutover is idempotent (same post IDs don’t double-post), but re-running without re-running ready could miss server-side changes. Always re-ready first.
./operate.sh rollback is destructive and gated by ROLLBACK_CONFIRMATION. Never re-run after success.
./operate.sh edge in execute mode creates real DNS records. Re-running with different values modifies DNS. Eyeball the plan first (CLOUDFLARE_MODE=plan).

Partial Phase 1

If enrich died 80% through

Partial Phase 2

Recovering mid-staging / mid-deploy

§10.1 · worked example

Meet Acme Corp.

Throughout this article and the two skills, a fictitious workspace anchors the examples:

Company: Acme Corp (340 users, engineering + ops + sales)
Plan: Business+ (routed to Track A, the official admin export)
Target: chat.acme.com, served from a Hetzner AX42 in Falkenstein
Email: Postmark for transactional SMTP (admin@acme.com is the rollback owner mailbox)
Storage: Cloudflare R2 for files; local /opt/mattermost/data/ during cutover, migrate post-cutover
Calls: enabled; calls.acme.com is grey-clouded so UDP 8443 works

Phase 1 config

Acme Corp’s Phase 1 config.env

WORKSPACE_NAME="acme-slack"
PHASE1_WORKSPACE_ROOT="./workdir"
MATTERMOST_TEAM_NAME="acme"
MATTERMOST_TEAM_DISPLAY_NAME="Acme Corp"
SLACK_PLAN_TIER="Business+"

SLACK_EXPORT_ZIP="/Users/jane/Downloads/acme_slack_export_2026-04-15.zip"
SLACK_CHANNEL_AUDIT_CSV="/Users/jane/Downloads/acme_channel_audit_2026-04-15.csv"
SLACK_MEMBER_CSV="/Users/jane/Downloads/acme_member_list_2026-04-15.csv"

SLACK_TOKEN="xoxp-ACME-USER-TOKEN-WITH-READ-SCOPES"
MMETL_DEFAULT_EMAIL_DOMAIN="acme.com"
PHASE1_SIDECAR_INPUTS="/Users/jane/acme/canvases,/Users/jane/acme/lists"
PHASE1_WORKFLOW_INPUTS="/Users/jane/acme/workflows"
PHASE1_SIDECAR_CHANNELS="slack-canvases-archive,slack-lists-archive,slack-export-admin"

SLACK_BOT_TOKEN="xoxb-ACME-BOT-TOKEN"
SLACK_TEAM_ID="TACMETEAM"

Phase 2 config

Acme Corp’s Phase 2 config.env

WORKSPACE_NAME="acme-slack"
PHASE2_WORKSPACE_ROOT="./workdir-phase2"
HANDOFF_JSON="/Users/jane/slack-migration/acme/workdir/artifacts/reports/handoff.json"
IMPORT_ZIP="/Users/jane/slack-migration/acme/workdir/artifacts/import-ready/mattermost-bulk-import.zip"

MATTERMOST_URL="https://chat.acme.com"
MATTERMOST_ADMIN_USER="admin"
MATTERMOST_ADMIN_PASS="<generated, stored in 1Password>"
MATTERMOST_TEAM_NAME="acme"
ENABLE_LOCAL_MODE="1"

TARGET_HOST="chat.acme.com"
TARGET_SSH_USER="deploy"
DEPLOY_METHOD="apt"
POSTGRES_DSN="postgres://mmuser:<strong>@localhost:5432/mattermost?sslmode=disable"
SMOKE_DATABASE_URL="${POSTGRES_DSN}"

SMTP_SERVER="smtp.postmarkapp.com"
SMTP_PORT="587"
SMTP_USERNAME="<postmark-server-token>"
SMTP_PASSWORD="<postmark-server-token>"
SMTP_TEST_EMAIL="admin@acme.com"

CLOUDFLARE_ENABLED="1"
CLOUDFLARE_MODE="execute"
CLOUDFLARE_API_TOKEN="<zone-edit-scoped>"
CF_ZONE_ID="<acme-com-zone-id>"
ORIGIN_SERVER_IP="95.217.12.34"
CALLS_HOSTNAME="calls.acme.com"
CALLS_SERVER_IP="95.217.12.34"

MATTERMOST_ADMIN_TOKEN="<system_admin-PAT-created-post-deploy>"
ROLLBACK_OWNER="Jane Admin <jane@acme.com>"
BACKUP_PATH="/var/backups/mattermost/mm_2026-04-22.sql.gz"
SCRATCH_DB_URL="postgres://mmuser:<strong>@localhost:5432/mm_restore_drill?sslmode=disable"

Phase 1 kickoff prompt

Typical paste

Successful cutover-status

Acme’s production cutover

{
  "status": "success",
  "started_at": "2026-04-22T14:05:12Z",
  "completed_at": "2026-04-22T14:31:04Z",
  "import": {"job_id": "8hxm...", "state": "success", "final_lines": 218451},
  "smoke": {"users": 337, "channels": 142, "posts": 1284903, "direct_channels": 4921},
  "reconciliation": {"status": "ok", "diffs": []},
  "activation": {"smtp_test_email": "admin@acme.com", "reset_link_received": true},
  "rollback_owner": "Jane Admin <jane@acme.com>"
}

Use these numbers to sanity-check your own runs; Acme’s shape is the canonical “this is what a healthy migration looks like.”

§10.3

Stage cheatsheet — outcome, proof, recovery.

Phase 1

What you have after each stage

Stage	After this stage you will have	How to tell it worked	If it failed
setup	workdir/artifacts/{raw,enriched,import-ready,reports}/ tree; config validated; tools resolved	doctor.sh prints “Health score: N/N required passing (100%)”	Missing tool → re-run bootstrap-tools.sh; missing env → edit config.env and re-run
export	slack-export.zip + audit/member CSVs + manifest.raw.json	jq '.files \| length' manifest.raw.json matches file count; every file has SHA256	Truncated ZIP → re-download; rate-limited slackdump → retry with built-in backoff
enrich	slack-export.enriched.zip with __uploads/, rewritten users.json, emoji manifest, sidecar bundle	validate-enrichment-completeness.py reports empty missing_file_references + empty users_missing_email	Missing attachments → per-file decision: accept as unrecoverable or re-run after fixing scope
transform	mattermost_import.jsonl + data/bulk-export-attachments/	mmetl check slack exits 0; JSONL has users/channels/posts lines	mmetl panic → MMETL_EXTRA_FLAGS="--discard-invalid-props"
package	mattermost-bulk-import.zip + manifest.import-ready.json	Sidecar channels populated; emoji objects precede team line	Warning about missing user in memberships → trace to source in JSONL, fix patch script input
verify	reports/verification.md, evidence-pack.json, secret-scan.json (+ reports/redacted/ if findings)	verification.md has no red lines; scan findings empty or accepted	Red reconciliation → go back to enrich or export; do not proceed
handoff	handoff.md, handoff.json, unresolved-gaps.md	shasum -a 256 final.zip == handoff.json.final_package.sha256	Mismatch → re-run handoff (never edit handoff.json by hand)

Phase 2

What you have after each stage

Stage	After this stage you will have	How to tell it worked	If it failed
intake	workdir-phase2/reports/phase2-intake-report.json	Hash match confirmed, sidecar_channels[] non-empty	Re-copy canonical ZIP from Phase 1
render-config	rendered/config.json + mattermost.nginx.conf + config-validation.json	config-validation.json.status == "ready"; MaxPostSize=16383	Missing env → fix config.env; re-run
edge	Cloudflare A record proxied; origin CA cert in rendered/origin.{pem,-key.pem}	verify-cloudflare-edge.py green	Fall back to NGINX_ENABLE_TLS=1 with Let’s Encrypt
provision	UFW, fail2ban, unattended-upgrades, optional local PG on target	systemctl status fail2ban active; ufw status verbose active	Re-run in plan mode, eyeball script, then ssh mode
deploy	Mattermost + Nginx running, config.json in place, TLS cert installed	/api/v4/system/ping returns 200 via HTTPS	Ubuntu 25.10 + APT fail → switch to DEPLOY_METHOD=docker
verify-live	reports/live-stack.md with ping + WS + SMTP results	All three probes green, 6× retries exhausted without falling back	WS fail → re-render-config+deploy; SMTP fail → verify with swaks
staging	reports/latest-staging.json + timestamped staging-summary.*.json, import-watch JSONL	latest-staging.json.status=success, observed counts ≈ handoff counts	Counts off → go back to Phase 1
restore	Proof that pg_restore works against SCRATCH_DB_URL	restore-drill.sh exits 0; tables populate	Fix BACKUP_PATH; redo drill
ready	cutover-readiness.json, readiness-score.md, phase2-readiness.md	status: "ready" verbatim	Fix every blocker listed; re-run
cutover	reports/cutover/cutover-status.<ts>.json + latest-activation.json	newest cutover-status.*.json has status: "success"	Read note; fix-in-place or rollback
rollback	Restored pre-cutover state, archived rollback artifacts	Users can’t reach new Mattermost; DB is back to pre-cutover dump	Unfreeze Slack; schedule a new attempt

§10.5

Concrete monthly cost breakdown (340 users).

For a 340-user deployment (Acme Corp profile), numbers as of April 2026:

Line item	Price	Notes
Hetzner AX42 dedicated (Falkenstein or Helsinki)	€46/month (~$50)	AMD Ryzen 7 PRO 8700GE, 64 GB DDR5, 2× 512 GB NVMe. One-time setup €39.
OR Hetzner AX52 (recommended 500–1,000 users)	€64/month (~$70)	Ryzen 7 7700, 64 GB DDR5, 2× 1 TB NVMe. One-time €39.
Cloudflare Free plan	$0	TLS termination, DDoS, WAF, WebSockets, CDN for static assets.
Postmark (100K emails/month)	$15/month	SPF/DKIM/DMARC built in. Alternatives: Mailgun Flex ($35), SES ($1/10K but setup-heavy).
Domain + DNS (if not already owned)	$10–15/year	Cloudflare charges cost; any registrar fine.
Cloudflare R2 (file storage, optional)	~$1.50/month	For 100 GB files. Zero egress.
Hetzner Storage Box 1 TB (off-site backups)	€4/month (~$4)	Nightly pg_dump target.
Total / month (AX42 + R2 + backups)	~$70/month
Total / month (AX52 + R2 + backups)	~$90/month

One-time costs (not recurring):

Hetzner setup fee: €39 per server.
Operator time: one weekend for under 100 users, 1–2 weeks for 1,000 users with rehearsals.
Optional: Mattermost Professional Edition license (~$10/user/month) if you want SAML SSO, compliance features, or guest accounts. Team Edition is free and sufficient for most orgs.

§10.4

User-communications kit.

Phase 2 ships references/comms/USER-COMMS-KIT.md with longer versions of each template. Quick copy-paste versions below — edit for your voice.

T−7d — “Heads up, we’re moving”

Subject: We’re moving from Slack to Mattermost in 7 days

What you need to do: nothing yet. We’ll send instructions the day before and the day of.

What won’t change: public channels, private channels you’re in, DMs, threads, files, and reactions all move over.

Questions? [help channel / ticket link]

T−24h — freeze notice

Subject: Slack goes read-only tomorrow at 09:30

Tomorrow, [DATE] at 09:30 local, Slack will be set to read-only. You’ll still be able to read everything, but not post.

All your Slack history (public, private channels you’re in, DMs, threads, files) will already be there.

Who to ask if something goes wrong: [name, email, Slack handle for today / Mattermost handle post-cutover]

T−15m — “Slack is now read-only”

#general: heads up, Slack is now read-only. Do not start new threads here. Mattermost opens for activation at 10:15 at https://chat.acme.com/reset_password. Use your Slack email.

T+0 — activation

Subject: Mattermost is live. Activate your account.

Mattermost is live at https://chat.acme.com. To activate:

Go to https://chat.acme.com/reset_password.
Enter your Slack email (the one you use day to day).
Check that email for a password-reset link.
Set a password. Log in.

Your Slack history is already there. If something looks off, ping [support handle].

Not migrated (recreate these yourself): Slackbot auto-replies, saved items, scheduled messages, bookmarks, custom notification rules. See [link to internal doc] for step-by-steps.

T+24h — activation reminder

Subject: If you haven’t activated Mattermost yet…

About [N]% of the team has activated. If you haven’t, take 90 seconds now: https://chat.acme.com/reset_password, your Slack email, done.

If you never got the reset email, check spam first, then reply to this message and I’ll either resend or set a temp password for you.

T+7d — wrap-up

Subject: One week in; Slack is going away

Everything’s been running on Mattermost for a week. Today I’m:

Revoking the Slack migration app (we only needed it for one-time access).
Downgrading the Slack workspace to the cheapest read-only tier so we can still reference old content for 90 days if anyone needs it.
Closing this migration ticket. Retrospective thread: [link].

If you still haven’t activated Mattermost: do it today.

§10.6

Legal approval gate — copy-paste email to legal / HR.

The Phase 1 skill’s references/playbooks/LEGAL-APPROVAL-GATE.md is the authoritative playbook. A starter email for impatient operators:

Subject: Approval to export Slack workspace data for migration to self-hosted Mattermost

Hi [Legal / HR contact],

As part of the planned chat-platform migration (ticket [#ID]), I need written approval to export the company’s Slack workspace content. Specifics:

Scope I’m requesting: full content export under our Business+ plan. That’s public channels, private channels, direct messages, and group DMs; the full set the plan tier authorizes.

Data handling during migration:

Export ZIP is downloaded directly to my workstation at [location]; not uploaded to third parties.
During processing, the ZIP lives in ~/slack-migration/ on my laptop, deleted after T+30 days.
Import artifacts are SHA256-hashed and a machine-readable evidence pack is generated.
Slack session tokens and the Slack admin app are revoked within 7 days of cutover.

Retention: unchanged. Slack data that today expires per [retention policy] will expire in Mattermost on the same schedule.

Happy to hop on a call if easier.

Thanks,
[Name]

Save the approving reply alongside handoff.md in the final evidence pack.

§10.9

Disk footprint per stage.

A worked-example table for a 340-user Business+ workspace with ~3 years of history, ~12 GB raw export, ~8 GB of attached files:

Stage	New files added	Cumulative disk
setup	empty directory tree + config copies	~1 MB
export	slack-export.zip (~12 GB), audit CSV (~2 MB), member CSV (~100 KB), manifest.raw.json	~12 GB
enrich	slack-export.enriched.zip (~20 GB including downloaded attachments), emoji images (~50 MB), sidecar bundle (~500 MB)	~33 GB
transform	mattermost_import.jsonl (~500 MB), data/bulk-export-attachments/ (~8 GB, deduped from enriched)	~42 GB
package	mattermost-bulk-import.zip (~22 GB)	~64 GB
verify + handoff	reports/ (~5 MB), evidence-pack.json (~1 MB)	~64 GB

§10.10

Enterprise Grid — per-workspace migration.

Canonical flow

Per-workspace

In each Slack Grid workspace you want to migrate, run a separate official admin export.
Create a fresh working directory per workspace (~/slack-migration/acme-engineering, ~/slack-migration/acme-sales, etc.), each with its own config.env.
Run the Phase 1 pipeline per directory. Each emits its own handoff.json.
In Phase 2, either:
- Stand up one Mattermost server with multiple teams, and run ./operate.sh intake + cutover per workspace, each pointing at the same MATTERMOST_URL but different MATTERMOST_TEAM_NAME.
- Or stand up separate Mattermost servers per division.

Canonical flow

Grid-wide

If you got a single grid-wide ZIP, use the skill’s split-phase1-import.py helper before enrichment:

./scripts/split-phase1-import.py \
    --input /path/to/grid-export.zip \
    --output-dir workdir/split/ \
    --by workspace

Creates workdir/split/<workspace>/slack-export.zip. Treat each as a per-workspace export. references/ENTERPRISE-GRID.md has the detailed walkthrough including edge cases.

Grid edge cases

What to watch for

Users in multiple workspaces: same email. Mattermost merges them on import. If per-workspace Phase 1s, run Phase 2 imports in dependency order (least-dependent first) to keep username conflicts predictable.
Grid-wide search channels: don’t migrate as first-class; preserve the member list as a sidecar and flag for rebuild if operationally important.
IdP / SSO in Grid: Grid’s enterprise SSO doesn’t follow users into Mattermost. Configure Mattermost’s SAML separately (System Console → Authentication → SAML 2.0) and map on email.

§10.11

Compliance & audit handoff.

If your org has a compliance reviewer or external auditor, here is what you hand them.

Phase 1 evidence pack

Location + fields

Location: workdir/artifacts/reports/evidence-pack.json. Fields (summarized):

schema_version — frozen format identifier
generated_at — UTC timestamp
workspace — Slack workspace slug
plan_tier, export_basis — legal basis for the export (from SLACK_PLAN_TIER plus the legal-approval memo)
manifests[] — list of hash-anchored manifest files (raw, enriched, import-ready)
counts — users, channels, posts, DMs, emoji, attachments, sidecars
known_gaps[] — every documented not-migrated item with disposition class
secret_scan_findings — scan-and-redact-migration-secrets.py output (should be empty or explicitly accepted)

Phase 2 cutover pack

Location + artifacts

Location: workdir-phase2/reports/. Key artifacts:

phase2-intake-report.json — hash match proof (Phase 1 to Phase 2)
config-validation.json — server config drift check
live-stack.md — TLS + WebSocket + SMTP reachability evidence
latest-staging.json + timestamped staging-summary.*.json — rehearsal results, observed counts, reconciliation
cutover-readiness.json + readiness-score.md — pre-cutover gate, with ROLLBACK_OWNER named
cutover/cutover-status.<ts>.json + latest-activation.json — final import state, activation proof, reconciliation

What an auditor typically asks

Five common questions

Question	Where the answer lives
Prove the data we imported matches the data we exported.	Show handoff.json.final_package.sha256 + phase2-intake-report.json hash match + latest-staging.json count reconciliation.
Prove who authorized the export.	The legal-approval email (§10.6) stored alongside the evidence pack. Not in the skill’s output; you attach it.
Prove no secrets leaked into reports.	secret-scan.json from the secret scanner; redacted copies in reports/redacted/ if any.
Prove the cutover had a rollback plan.	cutover-readiness.json.rollback_owner (named human) + restore-drill result if done.
Retention: where is the raw Slack data now?	Deleted from workdir/artifacts/raw/ after T+[retention period]. The scan-and-redact helper plus the final handoff give you the last point the raw ZIP was referenced.

Handoff format

How long to keep

Raw export ZIP + enriched ZIP: delete from operator workstation T+30 days after cutover, unless an auditor has asked for it.
Final import ZIP (mattermost-bulk-import.zip): keep for T+90 days in case a post-cutover re-import is needed.
Evidence pack + cutover pack: keep per your compliance retention policy. Typically 7 years for US SOX / EU GDPR article 5 compliance, or your sector-specific rule.

§10.12

Credential inventory — what you collect and where it goes.

In order of collection

The full list

#	Credential	What it is	Which config.env	Needed at stage
1	Anthropic or OpenAI subscription login	Sign-in for Claude Code / Codex desktop app	n/a (stays in the app)	Before Part 1
2	jsm account (Google OAuth)	Subscription at jeffreys-skills.md	n/a (stored in OS keychain)	§1.2 / Part 11
3	SSH keypair	~/.ssh/id_ed25519 + .pub	n/a (SSH uses it automatically)	§1.0, Phase 2 provision
4	Domain + registrar login	Your future chat.yourcompany.com DNS	n/a	§1.0.2
5	Cloudflare API token	Scoped: Zone.DNS:Edit + Zone.SSL:Edit for your one zone	CLOUDFLARE_API_TOKEN	Phase 2 edge
6	Cloudflare Zone ID	32-hex identifier for your zone	CF_ZONE_ID	Phase 2 edge
7	Slack user token (xoxp-…)	Read-scoped user OAuth token	SLACK_TOKEN	Phase 1 enrich
8	Slack bot token (xoxb-…)	Bot-scoped token for the same Slack app	SLACK_BOT_TOKEN	Phase 1 (optional, MCP verification)
9	Slack team ID (T…)	Workspace identifier	SLACK_TEAM_ID	Phase 1 enrich
10	Slack session cookies (xoxc- + xoxd-)	For slackdump stealth mode on Free/Pro	SLACKDUMP_XOXC + SLACKDUMP_XOXD	Phase 1 export on Free/Pro only
11	Postmark server token	SMTP credential for password-reset emails	SMTP_USERNAME + SMTP_PASSWORD (same value; Postmark convention)	Phase 2 verify-live, cutover
12	Mattermost admin password	System admin password for the admin account	MATTERMOST_ADMIN_PASS	Phase 2 deploy onwards
13	Mattermost admin PAT	Personal access token, created post-deploy	MATTERMOST_ADMIN_TOKEN	Phase 2 ready, cutover
14	PostgreSQL password (mmuser)	Local PG password the provisioner uses	inside POSTGRES_DSN	Phase 2 provision, deploy
15	Rollback-owner email	Your (or a named human’s) email	ROLLBACK_OWNER	Phase 2 ready, cutover

Lifecycle rules

Rotate and revoke

Never commit to git. Both phases ship a secret scanner that runs automatically; failure blocks handoff until you remediate.
Revoke after cutover. Within 7 days: revoke the Slack user token, bot token, and session cookies. Rotate the Mattermost admin PAT (create new, delete old) if you shared it with any automation.
Keep Cloudflare + Postmark + SSH long-term. Useful for operating the Mattermost server. Rotate Postmark if a former admin ever had access.
Chicken-and-egg: PAT after deploy. The Mattermost admin PAT doesn’t exist until deploy has finished and you’ve logged in as admin once. Leave MATTERMOST_ADMIN_TOKEN="" during intake/render-config/edge/provision/deploy, then come back and fill before verify-live.

Quick recovery

If you lose a credential

Lost Slack user token: re-install the Slack app, issue a new token, update config.env. Tokens are cheap; your identity is not.
Lost SSH key: see §1.0.5 (Hetzner rescue-system playbook).
Lost Cloudflare API token: delete old in Cloudflare → My Profile → API Tokens, create new with same scopes, paste into config.env.
Lost Mattermost admin password: SSH to the server and reset with sudo -u mattermost mmctl --local user change-password admin <new-password>. Write the new one into your password manager.
Lost rollback owner: pick a new one; update ROLLBACK_OWNER; re-run ./operate.sh ready to regenerate the gate record with the new name.

§10.13

Cloudflare walkthrough — click-by-click.

If you bought the domain at Cloudflare Registrar, skip step 1. Otherwise:

§10.13.1

Add your domain to Cloudflare

Sign up / log in at dash.cloudflare.com.
Click + Add a domain. Paste yourcompany.com (no https://, no subdomain).
Pick the Free plan. Free covers TLS, DDoS, WAF, CDN, and WebSockets — everything the migration needs. Continue.
Cloudflare scans your current DNS and imports the records. Confirm. Continue.
Cloudflare shows you two nameservers (e.g. ada.ns.cloudflare.com, joel.ns.cloudflare.com). Copy both.
Go to your registrar → nameservers → swap to Cloudflare’s two. Save.
Wait. Pending yellow → Active green in 15–60 min (occasionally up to 24 h). Don’t proceed past this until it’s green.

§10.13.2

Find your Zone ID

Click your domain name in the dashboard.
On Overview, right sidebar → API section.
Copy the 32-char hex Zone ID (e.g. 7e6c1f9b40a8d3e2f5c9b1a7e4d3f8c2).
Paste into config.env.phase2 as CF_ZONE_ID=… (no quotes, no spaces).

§10.13.3

Create a scoped API token

Never paste your global Cloudflare API Key. Use a scoped token.

Top-right avatar → My Profile → API Tokens → Create Token.
Scroll past the templates → Create Custom Token → Get started.
Name: slack-migration-phase-2 (any label you’ll recognize later).
Under Permissions, add:
- Zone → DNS → Edit
- Zone → SSL and Certificates → Edit
Under Zone Resources: Include → Specific zone → your domain.
Leave IP filtering and TTL defaults. Continue to summary → Create Token.
Cloudflare displays the token exactly once. Copy immediately. Paste into config.env.phase2 as CLOUDFLARE_API_TOKEN=…
The confirmation page shows a Test curl — run it; expect "status":"active" JSON.

§10.13.4

What the skill does with these

Creates/updates an A record for chat.yourcompany.com pointing at $ORIGIN_SERVER_IP, orange-clouded.
If CALLS_HOSTNAME is set, also creates a grey-clouded (DNS-only) A record for calls.yourcompany.com so UDP 8443 bypasses Cloudflare’s proxy.
Generates a 15-year Cloudflare Origin CA certificate for chat.yourcompany.com and saves PEMs into workdir-phase2/rendered/. The subsequent deploy stage SCPs these to /etc/nginx/ssl/origin.pem.

§10.13.5

Orange-cloud vs grey-cloud in one sentence each

Orange-clouded (proxied): traffic intercepted by Cloudflare — TLS terminated, attacks filtered, static cached, forwarded to origin. Use for user-facing HTTP/HTTPS.
Grey-clouded (DNS-only): Cloudflare hands back your origin IP directly. Use for UDP (Calls 8443), staging, and MX records.

§10.13.6

Cloudflare troubleshooting

Zone stuck in Pending: nameserver change hasn’t propagated. Check dig NS yourcompany.com +short; if you see old nameservers, give it time or re-verify at the registrar.
API token returns 403: wrong zone in Zone Resources. Create a new token; Cloudflare requires recreation for scope changes.
Origin CA cert doesn’t work: edge stage wrote the cert but deploy didn’t copy. Check workdir-phase2/rendered/origin.pem, SCP manually to /etc/nginx/ssl/origin.pem, sudo systemctl reload nginx.

§10.14

SMTP (Postmark) walkthrough.

§10.14.1

Why Postmark

Cheapest entry tier ($15/month for 10K emails, more than enough for a 340-user activation burst).
Highest reputation for transactional email (fast inbox placement, rare spam-folder issues).
Simple domain verification (3 TXT records).
Server Tokens can be used directly as SMTP credentials.

§10.14.2

Sign up for Postmark

Go to postmarkapp.com → Sign up. Use your company email.
Confirm email. Log in.
Pick Transactional email.
Create a server (Postmark’s term for a sending pool). Name: acme-chat-transactional. Stream type: Transactional.

§10.14.3

Add and verify your sending domain

Postmark dashboard → Sender Signatures → Domains → + Add Domain.
Enter acme.com (your root domain, not chat.acme.com). Verify.
Postmark shows 3 DNS records:
- DKIM TXT at 20260416pm._domainkey.acme.com, value k=rsa; p=MII…
- Return-Path CNAME at pm-bounces.acme.com → pm.mtasv.net
- Optionally DMARC TXT at _dmarc.acme.com with v=DMARC1; p=none; rua=mailto:dmarc-reports@acme.com
Add each in Cloudflare → DNS → Records. Type, Name, Content exactly as shown. TTL Auto. Proxy status DNS only (grey cloud) — required for Return-Path CNAME.
Back in Postmark, Verify. Usually succeeds within 2 minutes. If fail, recheck value character-for-character (DKIM keys are easy to truncate).

You want DKIM and Return-Path both verified (green checkmarks). DMARC is optional but recommended.

§10.14.4

Grab the Server Token

Postmark dashboard → your server → API Tokens tab.
Copy the Server Token.
Paste into config.env.phase2 as both SMTP_USERNAME and SMTP_PASSWORD. Postmark’s SMTP expects the same token in both — Postmark convention, not a mistake.

SMTP_SERVER="smtp.postmarkapp.com"
SMTP_PORT="587"
SMTP_TEST_EMAIL="admin@acme.com"
# Optional: override the from-address; default is $SMTP_TEST_EMAIL
SMTP_FROM_ADDRESS="noreply@acme.com"

§10.14.5

Test before you need it

From the target server (or your laptop with swaks installed — brew install swaks on Mac, apt install swaks on Ubuntu):

swaks --to $SMTP_TEST_EMAIL \
      --from noreply@acme.com \
      --server smtp.postmarkapp.com:587 \
      --tls \
      --auth-user "$SMTP_USERNAME" \
      --auth-password "$SMTP_PASSWORD" \
      --header "Subject: migration SMTP test" \
      --body "If you're reading this, Postmark works."

Phase 2’s verify-live does the equivalent automatically. If it reports success but Mattermost’s own reset-password emails fail at cutover, it’s almost always:

SMTP_FROM_ADDRESS doesn’t match the verified domain (Postmark rejects). Fix: SMTP_FROM_ADDRESS=noreply@acme.com where acme.com matches the verified signature.
RequireEmailVerification=true in Mattermost config. render-config sets this false by default; re-check if you edited the rendered file.
User’s email provider classifies Mattermost’s template as marketing. Mitigation: ensure DMARC is set (§10.14.3 record 3).

§10.14.6

Cost at cutover scale

Part 11

Installing the skills via Jeffrey’s Skills.md (jsm).

Sign up for a subscription

Open jeffreys-skills.md.
Sign up / subscribe. Sign in with Google; no separate email/password.
Pick Individual ($20/month) and check out via Stripe or PayPal. Auto-renews monthly; cancel any time.
Dashboard shows active subscription and a button to install the jsm CLI.

What you get for $20/month:

Access to every premium skill on the site, including both slack-migration-to-mattermost-phase-1-extraction and -phase-2-setup-and-import.
Automatic updates (pinnable to specific versions).
Personal cloud skill storage — push private skills with jsm push, pull on any signed-in machine.
Cross-device sync.
Hash-verified downloads — jsm verify catches tampering.

§11.2

Install the jsm CLI

# macOS / Linux
curl -fsSL https://jeffreys-skills.md/install.sh | bash

# Windows PowerShell as Admin
irm https://jeffreys-skills.md/install.ps1 | iex

# Verify
jsm --version
# should print something like: jsm 0.1.7

Drops the binary into ~/.local/bin and adds it to PATH. Restart your terminal (or source ~/.bashrc).

§11.3

First-time setup and authentication

jsm setup        # interactive wizard — where should skills live
jsm login        # opens a browser → sign in with Google
jsm whoami
# Signed in as you@example.com (subscription: active)

For corporate proxies / weird networks:

jsm login --remote     # device-code style — paste a code in a browser anywhere
jsm login --manual     # prints the callback URL to paste into jsm yourself

§11.4

Install the two migration skills

jsm install slack-migration-to-mattermost-phase-1-extraction
jsm install slack-migration-to-mattermost-phase-2-setup-and-import
# or in one command (they declare pairs_with)
jsm install slack-migration-to-mattermost-phase-1-extraction --related

jsm list
jsm verify slack-migration-to-mattermost-phase-1-extraction
jsm info slack-migration-to-mattermost-phase-1-extraction

§11.5

Keeping skills up to date

jsm upgrade                      # apply any available updates
jsm upgrade --list               # show what would update
jsm upgrade slack-migration-to-mattermost-phase-1-extraction

# update preference
jsm config update-preference auto      # apply on every sync
jsm config update-preference notify    # just tell me
jsm config update-preference manual    # never auto-update

# pin a known-good version before production cutover
jsm pin slack-migration-to-mattermost-phase-1-extraction 1.3.0
jsm pin slack-migration-to-mattermost-phase-2-setup-and-import 1.3.0

# after cutover:
jsm unpin slack-migration-to-mattermost-phase-1-extraction
jsm unpin slack-migration-to-mattermost-phase-2-setup-and-import

§11.6

Multi-machine sync

jsm sync

Compares installed skills, local hashes, and last-synced hashes against the catalog; pulls anything new. Does not upload secrets or per-migration config.env; only the skill definitions sync.

§11.7

Troubleshooting jsm

jsm doctor
jsm doctor --fix     # auto-repair common issues

jsm: command not found → shell hasn’t re-read PATH. New terminal or export PATH="$HOME/.local/bin:$PATH".
jsm whoami says “not authenticated” after a successful jsm login → keychain didn’t persist (common on WSL2/headless Linux). Retry with jsm login --remote.
jsm install says “subscription required” but you’re subscribed → subscription email and Google-OAuth email don’t match. Check jeffreys-skills.md/dashboard; sign out and in with the correct Google account.
Install hangs on slow network → jsm install --retries 5 <skill>. Fall back to manual zip download if needed.
Claude Code / Codex don’t see the skill after install → restart the app (desktop) or session (CLI). Desktop apps index ~/.claude/skills/ on launch.

§11.8

Manual install without jsm (zip-download fallback)

If jsm refuses to install and you can’t get past it, you don’t have to use it. The skills are directories of files; jsm just fetches, verifies a hash, and drops them in the right place.

Sign in at jeffreys-skills.md/dashboard.
Find each skill in the catalog, click it, click Download zip. Copy the SHA-256 hash.

Then ask the agent to install, pasting the hashes:

Once jsm works later, jsm adopt <skill-name> hashes the installed files, registers them in its local database, and treats them as if it had installed them itself.

§11.9

Uninstalling

jsm uninstall slack-migration-to-mattermost-phase-1-extraction
jsm uninstall slack-migration-to-mattermost-phase-2-setup-and-import
# or:
jsm uninstall --all              # remove everything jsm installed
# add --keep-data to preserve per-skill config you'd written

Cancel the subscription itself from the dashboard; jsm doesn’t touch billing.

Part 12 · ongoing maintenance

The week after, and every week after that.

update-mattermost, auto-rollback on failure

doctor.sh confirms SSH + ping + PAT still work.
pg_dump streams the current DB to /var/backups/mattermost/pre-upgrade-<ts>.sql.gz. SHA-256 captured.
systemctl stop mattermost.
apt-get install --allow-downgrades mattermost=<target_version>.
systemctl start, then poll /api/v4/system/ping for up to 3 minutes.
If the new version doesn’t come up: stop, downgrade the package, DROP / CREATE the database, stream the pre-upgrade dump back in, start. Record status: failed_rolled_back.

Blast radius on failure: 2 to 6 minutes of Mattermost being offline. Data loss: zero. That loop is what lets a solo operator run production upgrades without a pager rotation.

§12.3

The weekly cadence

This is the whole point: the agent runs everything, you read a one-paragraph status on Monday morning.

Saturday night (~20 min agent runtime): paste the weekly-sweep.md prompt. The agent runs health → update-os → backup → db-health and writes a summary.
Monday morning (~1 min attention): skim the summary. If anything is red, tell the agent to investigate.
First Saturday of the quarter (~60 min): paste restore-drill.md. Agent downloads the newest backup, restores into scratch DB, confirms row counts. Failed drill = production incident.
On a Mattermost security release: paste update-mattermost.md with the pinned version. Auto-rollback loop kicks in if the health check fails.

You can automate the weekly sweep with cron on your workstation plus a webhook alert on failure (set ALERT_WEBHOOK_URL in config.env), or keep it as a scheduled agent-run item.

§12.4

Paste-ready prompts — you don’t hand-roll the wording

The prompts/ directory is a library of agent prompts already phrased for good outcomes. Pick one, paste, done:

Prompt file	What the agent does
orient.md	Reads config.env, runs doctor.sh, reports where the deployment is and what’s known
health.md	One-shot health snapshot; posts summary
update-os.md	Applies OS patches, schedules reboot if required
update-mattermost.md	Bumps Mattermost to pinned version, verifies, auto-rolls-back on failure
backup.md	Takes pg_dump, uploads off-site, verifies hash, reports size and destination
db-health.md	Postgres sizing, bloat, connections; flags slow-burning issues
restore-drill.md	Quarterly restore-from-backup verification
schedule-reboot.md	Queues a pending reboot in the next off-hours window
weekly-sweep.md	Saturday combo (health + update-os + backup + db-health)
major-upgrade.md	Extended sequence for a major Mattermost upgrade
plugin-upgrade.md	Plugin lifecycle: compatibility check, staging, prod install
rotate-credentials.md	PAT / SSH / off-site / session-secret rotation, one scope at a time
incident-response.md	Live-incident coordinator: triage, comms cadence, timeline capture
disaster-recovery.md	Rebuild onto a fresh host from the latest backup
all.md	Meta-prompt: the agent picks which sub-prompt fits your ask

§12.6

Restore-drill — the quarterly canary

If you have never restored a backup, you do not have backups. You have files.

./maintain.sh restore-drill exercises the backup pipeline end to end:

Lists the off-site destination (or local BACKUP_PATH) and picks the newest mm_*.sql.gz.
DROP DATABASE / CREATE DATABASE on SCRATCH_DB_URL — a separate Postgres instance provisioned specifically for drills. Never point this at prod.
Streams the compressed dump through gunzip | psql into the scratch DB.
Counts rows in "Users", "Channels", "Posts" (PascalCase, per Mattermost schema).
Compares counts against RESTORE_MIN_USERS, RESTORE_MIN_CHANNELS, RESTORE_MIN_POSTS.
Emits latest-restore-drill.json with status: ok|failed and counts.

Three distinct failure modes, each with its own remediation:

No backup found: off-site credentials expired, or the nightly backup has been silently failing. Check latest-backup.json from the last week.
Restore fails mid-stream: dump corrupted or scratch DB Postgres major version older than prod’s. pg_dump is forward-compatible but not backward.
Row counts below minimums: backup succeeded but captured an empty or partial DB. Has happened when a failed migration left Mattermost writing to a scratch schema; the backup job dutifully captured the empty one.

§12.7

Subagents for deep audits

Subagent	Use when
backup-integrity-auditor	You want judgement on backup completeness, SHA-256 coverage, off-site freshness, and restore-drill recency, not just stage runs
db-bloat-auditor	DB size climbing faster than user count can explain; looks at table bloat, vacuum status, index health, pg_stat_user_tables
health-drift-auditor	Nothing is red yet, but you want to know what is slowly getting worse across the last 8 weeks of health reports
version-drift-auditor	How far behind the recommended upgrade target you are, framed against Mattermost’s ESR policy
security-posture-auditor	Credential rotation cadence, SSH key hygiene, fail2ban / UFW state, exposed ports
maintenance-scheduler	Planning a maintenance window; coordinates comms, picks off-hours, writes the user-facing heads-up
incident-coordinator	Live incident: triage playbook, comms cadence, timeline capture for the post-mortem

§12.8

Scenario pack — Acme Corp’s actual schedule

assets/scenario-packs/acme-corp-weekly.yaml is a worked schedule for a 40-user Acme Corp profile. Drop into your scheduler (cron, systemd timers, or scheduled agent runs):

workspace: acme-corp
timezone: America/Los_Angeles
operator: alex@acme.com

schedule:
  - name: nightly-backup
    cron: "0 10 * * *"            # 10:00 UTC = 02:00-03:00 Pacific
    command: "./maintain.sh backup"
    log: /var/log/mm-backup.log

  - name: weekly-sweep
    cron: "0 10 * * 0"            # Sunday 10:00 UTC
    command: "./maintain.sh weekly-sweep"
    log: /var/log/mm-sweep.log

  - name: quarterly-restore-drill
    cron: "0 11 1-7 1,4,7,10 0"   # First Sunday of each quarter
    command: "./maintain.sh restore-drill"
    log: /var/log/mm-drill.log

alert_webhook: https://chat.acme.com/hooks/abcdef12345

thresholds:
  disk_pct_red: 85
  pg_conn_pct_red: 80
  log_err_per_min_red: 10

upgrade:
  policy: esr                     # track ESR releases only
  max_delay_patch_security: 72h
  rollback: auto

§12.9

Disaster-recovery drill

Full playbook in references/DISASTER-RECOVERY.md. The incident-coordinator subagent (§12.7) can also walk you through it live.

§12.10

Reading the weekly report and spotting trends

assets/templates/maintenance-report.md is the shape the agent follows. The summary table looks like:

Stage	Result	Notes
health	green	all probes green, 0 red
update-os	4 security patches, reboot required: yes	reboot scheduled for Sun 03:00 UTC
backup	success	1.4 GB, sha256=ab12…, off-site verified
db-health	yellow	Posts table up 8 % week over week, vacuum last ran 14 hours ago

§12.11

Credential-rotation cadence

./maintain.sh rotate-credentials --scope <name> rotates one thing at a time.

Scope	Cadence	What rotates
pat	90 days	MATTERMOST_ADMIN_TOKEN (Mattermost PAT for the bot admin)
ssh	annually	Deploy-user SSH key used by the workstation to reach TARGET_HOST
offsite	annually	rclone credentials for OFFSITE_REMOTE (R2 / Hetzner Storage Box token)
session-secret	on compromise only	Mattermost session signing secret; forces all users to re-login

§12.12

When to bring in more tooling

The Phase 3 skill is deliberately point-in-time health probes plus scheduled tasks. It does not replace continuous observability. If you eventually need:

SLO dashboards and alerting — spin up Grafana + Prometheus scraping Mattermost’s metrics port 8067.
Synthetic end-to-end user checks — Uptime Robot, Better Stack, or Cronitor hitting /api/v4/system/ping every 5 minutes.
Log aggregation — Loki or Grafana Cloud for mattermost.log.
Incident-response runbooks — Statuspage or a markdown repo your on-call reads on their phone.

A pattern, not a migration.

The deeper thing worth taking away from this is not about chat software. It is about the shape of problems that become tractable when a coding agent and a well-written skill are both in the room.

For operators who want to actually run this

This post is a distilled essay. The 2,500-line source guide that drives the two skills — and that an AI agent reads before kicking off the migration — includes everything this post skips:

Day-zero server ordering & SSH setup
Bootstrap scripts (doctor.sh, bootstrap-tools.sh)
MCP worked examples (Slack, Playwright, Mattermost)
Full Phase 1 / Phase 2 config.env field tables
Stage-by-stage cheatsheet with proof & recovery
Troubleshooting index (Phase 1, Phase 2, audit)
Printable operator checklist (T−2d, T−1d, T+0, T+7d)
User-communications kit (every template, T−7d → T+7d)
Legal-approval email template
Full credential inventory & rotation cadence
Cloudflare & Postmark click-by-click walkthroughs
Enterprise Grid split workflow
Compliance & audit evidence-pack handoff
Resume-after-interrupt playbook per stage
jsm install / pin / sync / verify commands
Phase 3 maintenance: weekly sweep, restore drill, DR, subagents, scenario pack

Download the full guide as Markdown

for feeding to an AI agent · ~185 KB · 2.5k lines

.md

Paste it into Claude Code or Codex with “read this guide end-to-end, then plan my migration” and the agent drives from there.

TL;DR

Two agent skills. One weekend. ~99% lower ongoing cost. Slack keeps working until you flip the switch yourself.

Using AI Agentsto Migrate Off Slack.

Why bother with any of this?

Why else self-host?

Read this first, even if you never run a command.

Can a non-technical person do this?

What you end up with

Timeline and effort expectations

Which path through this guide is for you?

Quick routing before you commit

The money math.

Why this wasn’t practical before.

Workstation setup: day zero to first skill call.

Day zero — order a server and wire up SSH

Order a Hetzner dedicated server

I don’t have a domain yet

Generate an SSH keypair on your laptop

First SSH login after the server is installed

Pick an agent harness (GUI app or CLI)

Install the two skills

Bootstrap the workstation for Phase 1

Bootstrap the workstation for Phase 2

Wire up MCP servers (optional but recommended)

Before you touch Slack.

Slack plan tier and export privileges

Scope of the export

Server sizing

How you drive the skill

The pause-and-confirm pattern

Non-technical operator cheat-sheet

During long stages

Phase 1 → handoff → Phase 2.

Driving Phase 1 — extraction and transformation.

Set up the working directory (stage: setup)

Acquire the Slack export (stage: export)

Track A — official admin export (recommended when available)

Track B — slackdump as primary (Pro / Free, or official unavailable)

Track C — Enterprise Grid with per-workspace export

Channel-audit CSV, member list, workflows

Enrich the export (stage: enrich)

Transform to Mattermost bulk-import format (stage: transform)

Patch and package (stage: package)

Verify and build the evidence pack (stage: verify)

Handoff (stage: handoff)

Driving Phase 2 — deploy, rehearse, cut over.

Open a fresh session, copy the config

Intake the Phase 1 handoff (stage: intake)

Render config (stage: render-config)

Cloudflare edge (stage: edge)

Provision the host (stage: provision)

Deploy Mattermost + Nginx (stage: deploy)

Verify live stack (stage: verify-live)

Staging rehearsal (stage: staging)

Restore drill (stage: restore, optional but recommended)

Compute readiness (stage: ready)

Cutover (stage: cutover)

An asymmetric bet.

What survives the move.

The fail-closed gate.

MCP worked examples — what each server unlocks.

Read access while Slack is still alive

Full visibility for gap-fill verification

Drives a real browser for UI-only work

Direct API access to live Mattermost

Cutover day, minute by minute.

The Slack → Mattermost cutover day sequence

Baseline + deltas pattern

What cutover day looks like on your screen

Three common failures

In Claude Code desktop

Activation, integrations, backups, file storage.

Activation

Rebuilding integrations

Backups and monitoring

File storage — local vs Cloudflare R2

Operator checklist — print and keep on the desk.

Two days before

One day before

Cutover day

If cutover fails

Troubleshooting index.

Using AI Agents
to Migrate Off Slack.