Skip to content

docs: install guides for people and for AI agents - #155

Merged
argiad merged 2 commits into
developmentfrom
docs/install-guides
Nov 8, 2026
Merged

docs: install guides for people and for AI agents#155
argiad merged 2 commits into
developmentfrom
docs/install-guides

Conversation

@argiad

@argiad argiad commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

What this adds

Install documentation for promoting MatrixMedia, in two forms:

  • docs/install.md: for admins who install by hand and don't want AI involved. It stands alone: requirements, firewall, DNS, reading the installer before running it, sign-in, payments, mmctl, backups, upgrades, removal, troubleshooting.
  • docs/install-agent.md: the same install for an AI agent. It has hard rules (what to ask the human first, which files never to print), read-only checks with expected output, a run that survives timeouts and dropped SSH, exact success criteria, and a failure table keyed by the installer's real log lines.
  • llms.txt at the root points agents to the agent guide.

It also fixes the docs a newcomer would land on first:

  • README: a new "Install on your own server" section. The old "Quick Start", which is the developer setup, becomes "Develop locally". Three dead links are removed.
  • deploy/README.md: links the walkthrough, sends sign-in to the Operator Console, marks --vendor-subdomain as not available yet, and replaces the two partial mmctl lists with one complete table.
  • docs/deployment.md and docs/quickstart.md: now point server installs at the guide.

The paths docs/install.md and docs/install-agent.md are linked from the landing docs (another branch), so please keep them.

How it was checked

  • Every path was run on fresh Hetzner Cloud cx23 servers (2 vCPU, 4 GB, Ubuntu 24.04) using the public one-liner pinned to fix(deploy): make the self-host install work on a clean server #154:
    • --no-domain: about 4 min
    • --domain with real Let's Encrypt certificates: 2m36s. All URLs return 200 with strict TLS, and matrix.org's federation tester reports FederationOK: true.
    • --demo
    • mmctl doctor, check, backup, upgrade and uninstall --purge
  • An independent review compared every claim and command against the installer source. It found 12 problems, all fixed here. Among them:
    • the ufw example didn't match the exact ranges the installer checks
    • the AAAA check the guide relied on never runs
    • mmctl upgrade re-pulls the installed release rather than moving to a new one
    • re-runs fail after an owner password change
    • backups contain every secret but no media
  • Relative links and anchors resolve. The agent guide's command blocks pass bash -n.

Merge order

Merge after #154. The guides describe its behavior: the Operator Console line, payments off without Stripe, and the mmctl fixes. The one-liner reads main, so newcomers get all of it only after a release (v0.10.1) is cut.

Installer gaps the review found (not changed here)

These are documented with workarounds in the guides. They're follow-up work for the installer:

  1. mmctl upgrade never moves to a new release, because only install.sh refreshes /opt/mm/versions.env. A release upgrade is "back up, then re-run the installer", and the re-run itself takes no backup.
  2. Re-running fails with could not capture admin token after the owner changes the generated password (the stored bootstrap password is reused).
  3. The AAAA check in preflight never runs during install: MM_DOMAIN is only set after preflight.
  4. Preflight doesn't check the CPU architecture. Images are amd64-only, so ARM hosts fail at image pull.
  5. Backups are never pruned and don't cover media or recording volumes.
  6. examples/selfhost/README.md still calls a one-command installer "a separately-maintained, supported offering", while deploy/ is public. That's a positioning call for the owner.

🤖 Generated with Claude Code

@argiad
argiad enabled auto-merge (rebase) November 8, 2026 09:28
@argiad @claude
docs: install guides for people and for AI agents
72ff637 
MatrixMedia is starting to be promoted, and the only install docs were the
installer reference and developer setups that read like install guides.

- docs/install.md: step-by-step server install for admins who will not use
  AI. Covers requirements (x86-64 only, 4 GB, public IPv4), firewall ports
  (the three UDP ranges the installer checks by name), DNS (subdomain advice
  when the apex hosts a website), reading the installer before running it,
  signing in to the Operator Console, payments, mmctl, what backups contain,
  upgrading to a new release (backup, then re-run with MM_DEPLOY_REF), re-run
  caveats, removal, and a troubleshooting table of the installer's real
  messages.
- docs/install-agent.md: the same install for an AI agent. Rules (what to ask
  the human first, which files never to print, no sign-in with the owner
  password), read-only checks with expected output, a nohup + pipefail run
  that survives timeouts and dropped SSH, exact success criteria, which WARN
  lines are normal, a failure table keyed by log lines, and the hand-over.
- llms.txt points agents at the agent guide.
- README: an "Install on your own server" section; "Quick Start" becomes
  "Develop locally"; three dead links removed from the docs table.
- deploy/README.md: links the walkthrough; sign-in goes to the Operator
  Console; --vendor-subdomain marked not available yet; one complete mmctl
  table (upgrade re-pulls the installed release; update skips the backup);
  backup and published-port descriptions corrected.
- docs/deployment.md and docs/quickstart.md point server installs at
  docs/install.md.

Every path in the guides was run on fresh Hetzner cx23 / Ubuntu 24.04
servers: --no-domain, --domain with real Let's Encrypt certificates
(federation tester passed), --demo, and doctor/check/backup/upgrade/purge.
An independent review checked every claim against the installer code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@argiad
argiad force-pushed the docs/install-guides branch from efc789e to 72ff637 Compare November 8, 2026 10:30
@argiad argiad mentioned this pull request Nov 8, 2026
Merged
@argiad @claude
ci(fresh-clone): install just without the GitHub releases API
a16d5aa 
extractions/setup-just resolves the version by asking the GitHub releases
API, and on 2026-11-08 that call answered 504 on six runs in a row for one
PR (attempts and fresh pushes alike), failing the required "clone → stack
up" check before anything in the PR was tested. taiki-e/install-action
ships its own version manifest and downloads the release asset directly.
Ubuntu's packaged just (1.21) is too old for the justfile's [doc]
attributes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@argiad
argiad merged commit ea2edd6 into development Nov 8, 2026
13 checks passed
argiad added a commit that referenced this pull request Nov 8, 2026
@argiad @claude
ci(test): give each cargo-test run its own database
d24b7b0 
The mm-runners jobs share one host Postgres, and every run reset the same
"mm_test". When two runs overlapped, the second one's dropdb either
failed ("database is being accessed by other users", PR #157 twice) or
dropped the database under the first one's live tests, which then panicked
in test_support ("connecting to Postgres failed", development's push run
after #155). Each run attempt now uses mm_test_<run_id>_<attempt> and drops
it at the end, cancelled runs included.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
argiad added a commit that referenced this pull request Nov 8, 2026
@argiad @claude
ci(test): give each cargo-test run its own database
5565865 
The mm-runners jobs share one host Postgres, and every run reset the same
"mm_test". When two runs overlapped, the second one's dropdb either
failed ("database is being accessed by other users", PR #157 twice) or
dropped the database under the first one's live tests, which then panicked
in test_support ("connecting to Postgres failed", development's push run
after #155). Each run attempt now uses mm_test_<run_id>_<attempt> and drops
it at the end, cancelled runs included.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@argiad argiad mentioned this pull request Nov 8, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@argiad