[argiad]

Why

This is the first real run of the public one-liner on a clean server: Hetzner cx23 (2 vCPU, 4 GB), Ubuntu 24.04, --no-domain --non-interactive. Every fresh install failed, one step after another. Each fix below was found on that server, covered by a test that failed first, and then checked on a brand-new server again.

The finished install now completes in about 4 minutes with self-smoke passed. It uses about 1.8 GB of 3.8 GB RAM and 8.9 GB of disk, and runs 14 containers.

What was broken (in the order the server hit it)

#	Symptom on a clean server	Cause	Fix
1	Both Postgres containers restart-loop; install dies at stack_up	versions.env pins postgres:18-alpine. Postgres 18 refuses a volume at /var/lib/postgresql/data (docker-library/postgres#1259)	PGDATA: /var/lib/postgresql/data on both services. The mount is not moved: moving it would make existing volumes look empty and initdb a blank cluster beside them
2	mm-core: password authentication failed for user "mm_admin"	The rendered mm-postgres-init.sql is root:root 0600, and Postgres runs init scripts after dropping to the postgres user: init.sql: Permission denied. The cluster still counts as initialized, so a re-run never recovers	Mount it at /run/mm-init/ and copy it in (owned by postgres) while the entrypoint is still root. The host file stays 0600
3	lk-jwt-service restart-loops	Pinned to latest-ci (upstream's rolling main), which now requires LIVEKIT_FULL_ACCESS_HOMESERVERS	Pin release 0.9.0 (upstream tags releases now) and set the variable to ${MM_DOMAIN}
4	mm-core exits: MM_STRIPE_SECRET_KEY required when monetization enabled	Compose defaults payments on, and a plain install has no Stripe keys. The Console where you add the keys is served by that same mm-core, so there was no way out	install.sh seeds MM_MONETIZATION_ENABLED from the keys (payments_seed) and says where to turn payments on. --demo generates throwaway sk_test_demo_/whsec_demo_ values for mm-fakestripe
5	Owner login gets 504 after 30 s; install stops silently	Traefik had --providers.docker.network=mm_network, but the real name is matrixmedia_mm_network. Traefik then picks a network per container at random, so routes to Synapse, mm-core, mm-web, mm-switch and LiveKit could land on internal. Under pipefail, capture_admin_token also died before its die	Use the prefixed name. Changing only that flag on the server took the Synapse routes from 504 to 200. Token capture now reports what the login answered
6	Self-smoke fails on a healthy stack	It probed mm-core right after recreating it, before Traefik routes it. https://<domain>/.well-known/matrix/client was never routed on the bare domain (clients use it to find the homeserver)	wait_healthy plus new wait_http before the smoke. The apex rule now forwards both well-known files to mm-web
7	mmctl doctor / check fail on a healthy install; every upgrade would "fail" its smoke and print the restore command	All three passed MM_SYNAPSE_ADMIN_TOKEN to mm-core's admin health check (always 401)	MM_ADMIN_TOKEN everywhere, matching install.sh. One test covers every caller
8	mmctl check: check_min: command not found	mmctl didn't load lib/preflight.sh	Load it
9	mmctl version prints dev on every piped install	No .git in a downloaded tree	The bootstrap records the ref in src/.deploy-ref
10	The installer's closing line sends the owner to a 403	https://matrix.<domain>/ is an optional landing mount; only the dashboard and viewer are baked into mm-web	The closing line points at the Operator Console (/_mm/dashboard/) and the homeserver address. admin.credentials gains console=
11	--demo: lnbits unhealthy, install fails	SUPER_USER: admin (lnbits needs a 128-bit hex id). This is the same line that broke the dev server in August	Removed. The first web-UI account becomes the superuser, as the comment beside it already said. The fallback image now matches the pin

mmctl is also linked before the stack starts. Every failure message says "run: mmctl …", and until now the command didn't exist yet at that point.

Verification

• deploy/test/fresh_install.bats (new) and additions to bootstrap, smoke, mmctl and pipe_bootstrap. Each test was watched failing before its fix. Mid-test [[ ]] checks use || false, because macOS /bin/bash 3.2 doesn't fail a test on them otherwise.
• Full suite: 274 ok, 0 failed (2 environment skips: needs root, needs a Docker daemon). shellcheck is clean with the CI flags.
• On a fresh server, one-liner pinned to this branch: exit 0, self-smoke passed.
  • mmctl doctor: passed. mmctl check: OK.
  • mmctl backup writes config plus both database dumps. mmctl upgrade backs up, rolls, and passes the smoke.
  • mmctl uninstall --purge removes every volume.
  • From outside: both well-known files, /versions, /login, federation version, the dashboard and viewer SPAs, and Element Call all answer 200. mm-switch metrics and health stay hidden.
• --demo, after uninstall --purge on the same server: exit 0, self-smoke passed, lnbits healthy, mm-fakestripe up, payments on with generated test keys, 16 containers.
• Not verified: signing in to the Operator Console with the generated owner account (that's a credential entry, so it was left for a human). The --domain path with real Let's Encrypt certificates, and federation, were not tested either.

Not changed here (owner decisions / follow-ups)

• What https://matrix.<domain>/ should show on a self-host (it's a 403 until a landing page is mounted; the nginx root also aliases a dev-server steegler-landing path).
• livekit.yaml has room.auto_create: true. Upstream lk-jwt-service says it must be false to actually restrict room creation, but mm-core may rely on it.
• mm-postgres sets log_statement = 'ddl', so CREATE ROLE … PASSWORD '<plaintext>' lands in docker logs on the first start.
• Backups are written 0644 (inside the 0700 /opt/mm).
• The nightly deploy-e2e harness can't pass as written: it uses the retired cx22 type and a matrixmedia.app subdomain that doesn't resolve, and it never tests the one-liner.
• Existing installs on Postgres ≤17 that pick up the postgres:18 pin need a pg_upgrade. With PGDATA pinned they fail loudly instead of silently.

Stage deploys use the host's own /opt/mm/docker-compose.yml and don't re-render these templates, so the dev server is unaffected.

🤖 Generated with Claude Code