configure managed Mesh homeserver login

Author: Dhawal Ranka

.github/workflows/release-beta.yml

@@ -19,8 +19,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 45
     env:
-      VITE_MESH_HOMESERVER: ${{ vars.VITE_MESH_HOMESERVER }}
+      VITE_MESH_HOMESERVER: https://matrix.mesh.dhawal.org
       VITE_MESH_SERVICE_NAME: ${{ vars.VITE_MESH_SERVICE_NAME }}
+      MESH_MANAGED_HOMESERVER: https://matrix.mesh.dhawal.org
+      MESH_MANAGED_SERVER_NAME: mesh.dhawal.org
     steps:
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
@@ -87,8 +89,10 @@ jobs:
     timeout-minutes: 90
     environment: matrix-beta
     env:
-      VITE_MESH_HOMESERVER: ${{ vars.VITE_MESH_HOMESERVER }}
+      VITE_MESH_HOMESERVER: https://matrix.mesh.dhawal.org
       VITE_MESH_SERVICE_NAME: ${{ vars.VITE_MESH_SERVICE_NAME }}
+      MESH_MANAGED_HOMESERVER: https://matrix.mesh.dhawal.org
+      MESH_MANAGED_SERVER_NAME: mesh.dhawal.org
     permissions:
       contents: write
     steps:

.gitignore

@@ -29,6 +29,8 @@ e2e-results/
 # Internal documents, prompts, chats, and design artifacts
 *.md
 *.mdx
+!AGENTS.md
+!mesh/infra/homeserver/README.md
 *.doc
 *.docx
 *.pages
@@ -78,6 +80,7 @@ claudereview/
 
 # Generated local integration-test state
 **/infra/matrix-spike/runtime/
+**/infra/homeserver/runtime/
 
 # Local configuration and secrets
 .env

AGENTS.md

@@ -0,0 +1,56 @@
+# Mesh Product North Star
+
+Mesh must feel like a regular consumer communication app, even though it is
+built on decentralized infrastructure. A normal user should be able to:
+
+1. install Mesh;
+2. open an invitation;
+3. create or sign in to an account; and
+4. enter the community.
+
+That path must not require the user to understand or configure Matrix,
+homeservers, federation, DNS, TLS, ports, relays, TURN, Synapse, or storage
+replication.
+
+## Non-negotiable UX rules
+
+- Ship safe, working defaults for the recommended Mesh service in release
+  builds.
+- Invitation links must carry or resolve everything needed to reach the
+  service and community.
+- Use plain product language such as "service", "community", and "voice";
+  reserve protocol terminology for diagnostics and advanced settings.
+- Keep "sign in somewhere else" and custom homeserver support available as an
+  advanced path so decentralization does not become lock-in.
+- Detect service capabilities and network conditions automatically. Do not ask
+  users to make infrastructure decisions that Mesh can make safely.
+- Errors must explain what the user can do next without exposing raw protocol
+  failures as the primary message.
+- Never silently consume a user's disk, bandwidth, or battery for shared
+  storage. Contribution must be explicit, bounded, encrypted, observable, and
+  reversible.
+- Treat extra setup steps in the default onboarding path as product defects
+  unless they are required for account security or informed consent.
+
+## Architecture guardrails
+
+- The managed Mesh homeserver is the zero-configuration default, not the only
+  compatible service.
+- Keep identity, membership, permissions, text history, encryption state, and
+  synchronization on the Matrix-compatible control plane.
+- Treat peer-assisted storage as an optional encrypted data plane with durable
+  anchors, replication targets, integrity verification, repair, quotas, and
+  garbage collection.
+- Preserve standard Matrix interoperability wherever possible so users and
+  communities can bring another compatible homeserver.
+- Infrastructure choices must be migration-ready: stable identity domains,
+  backed-up signing keys, portable databases/media, and configuration separate
+  from secrets.
+
+## Product references
+
+Cinny is a useful reference for its calm interface, familiar
+community/channel organization, and configuration-driven homeserver defaults.
+Mesh should learn from that simplicity while hiding more infrastructure from
+the recommended user path. Do not copy Cinny branding or code without an
+explicit compatibility and licensing review.

mesh/infra/homeserver/.env.example

@@ -0,0 +1,19 @@
+# Public, non-secret service identity. The Matrix server name is permanent
+# once accounts exist, so do not change MESH_SERVER_NAME after launch.
+MESH_SERVER_NAME=mesh.dhawal.org
+MESH_HOMESERVER_HOST=matrix.mesh.dhawal.org
+MESH_RTC_HOST=rtc.mesh.dhawal.org
+MESH_PUBLIC_ENABLED=0
+
+# Keep Synapse private on the Mac. Caddy is the only public HTTP entry point.
+SYNAPSE_CONTROL_BIND=127.0.0.1
+SYNAPSE_CACHE_FACTOR=0.25
+
+POSTGRES_USER=synapse
+POSTGRES_DB=synapse
+
+# setup.sh replaces these placeholders in the untracked .env file.
+POSTGRES_PASSWORD=REPLACE_WITH_RANDOM_SECRET
+REGISTRATION_SHARED_SECRET=REPLACE_WITH_RANDOM_SECRET
+MACAROON_SECRET_KEY=REPLACE_WITH_RANDOM_SECRET
+FORM_SECRET=REPLACE_WITH_RANDOM_SECRET

mesh/infra/homeserver/Caddyfile

@@ -0,0 +1,31 @@
+{
+	email {$ACME_EMAIL}
+	admin off
+}
+
+{$MESH_SERVER_NAME} {
+	@matrix_client path /.well-known/matrix/client
+	header @matrix_client Content-Type "application/json"
+	header @matrix_client Access-Control-Allow-Origin "*"
+	respond @matrix_client `{"m.homeserver":{"base_url":"https://{$MESH_HOMESERVER_HOST}"},"org.matrix.msc4143.rtc_foci":[{"type":"livekit","livekit_service_url":"https://{$MESH_RTC_HOST}/livekit/jwt"}]}` 200
+
+	@matrix_server path /.well-known/matrix/server
+	header @matrix_server Content-Type "application/json"
+	respond @matrix_server `{"m.server":"{$MESH_HOMESERVER_HOST}:443"}` 200
+
+	header {
+		Strict-Transport-Security "max-age=31536000; includeSubDomains"
+		X-Content-Type-Options "nosniff"
+		Referrer-Policy "no-referrer"
+	}
+	respond "Mesh service is online." 200
+}
+
+{$MESH_HOMESERVER_HOST} {
+	header {
+		Strict-Transport-Security "max-age=31536000; includeSubDomains"
+		X-Content-Type-Options "nosniff"
+		Referrer-Policy "no-referrer"
+	}
+	reverse_proxy synapse:8008
+}

mesh/infra/homeserver/README.md

@@ -0,0 +1,95 @@
+# Mesh homeserver runbook
+
+This stack runs the managed Mesh Matrix service on the Mac mini:
+
+- Synapse for accounts, rooms, messages, encryption metadata, and federation;
+- PostgreSQL for durable state;
+- Caddy for public HTTPS and Matrix discovery after DNS/router activation.
+
+The permanent Matrix server name is `mesh.dhawal.org`. User IDs will look like
+`@name:mesh.dhawal.org`.
+
+## Local setup
+
+```sh
+cd mesh/infra/homeserver
+./setup.sh
+./start.sh
+./status.sh
+./backup.sh
+```
+
+The local Synapse control port binds only to `127.0.0.1:8008`. Registration is
+closed by default. Create alpha accounts with `register_new_matrix_user` after
+the service is healthy.
+
+The initial operator account is `@dhawal:mesh.dhawal.org`. Its generated
+password is stored in macOS Keychain and can be retrieved locally with:
+
+```sh
+security find-generic-password \
+  -a '@dhawal:mesh.dhawal.org' \
+  -s 'Mesh Homeserver Admin' \
+  -w
+```
+
+The installed `org.mesh.homeserver` user LaunchAgent opens Docker after login.
+Docker's `unless-stopped` policy then restarts the Mesh services. The
+`org.mesh.homeserver.backup` LaunchAgent makes a local backup daily at 3:15 AM
+under `~/Library/Application Support/Mesh/backups`. Copy those backups to a
+separate disk before treating the service as durable. The scheduled local
+copies are retained for 14 days.
+
+The `org.mesh.homeserver.ddns` LaunchAgent checks the public IPv4 address every
+five minutes and updates only the `mesh.dhawal.org` Cloudflare A record when it
+changes. Its restricted API token is stored in macOS Keychain under
+`Mesh Cloudflare DDNS API Token`.
+
+## Public activation
+
+Do not start the public profile until all of these are true:
+
+1. In Cloudflare DNS, add a DNS-only `A` record named `mesh` pointing to the
+   home connection's public IPv4 address.
+2. Add a DNS-only `CNAME` named `matrix.mesh` targeting `mesh.dhawal.org`.
+3. Reserve the Mac's Ethernet address in the router, then forward TCP 80,
+   TCP 443, and UDP 443 to it.
+4. Enable the macOS firewall and allow Docker's incoming listener.
+5. If the public IP is not static, configure a Cloudflare dynamic-DNS updater.
+6. Confirm that the local stack and a backup restore have passed validation.
+
+Then start the proxy:
+
+```sh
+sed -i '' 's/MESH_PUBLIC_ENABLED=0/MESH_PUBLIC_ENABLED=1/' .env
+./start.sh
+```
+
+Verify from a device that is not on the home Wi-Fi:
+
+```sh
+curl https://mesh.dhawal.org/.well-known/matrix/client
+curl https://matrix.mesh.dhawal.org/_matrix/client/versions
+```
+
+The MatrixRTC stack under `../matrixrtc` is activated separately after the
+homeserver is publicly healthy.
+
+## Critical data
+
+Never lose:
+
+- the PostgreSQL database;
+- `runtime/synapse/mesh.dhawal.org.signing.key`;
+- the local media store;
+- the untracked `.env` operator secrets.
+
+The server name and signing key identify the homeserver in federation. Backups
+must eventually be copied off this Mac and restore-tested.
+
+If operator secrets are exposed, rotate the PostgreSQL password and Synapse
+runtime secrets without changing the server name or signing key:
+
+```sh
+./rotate-runtime-secrets.sh
+```

mesh/infra/homeserver/backup.sh

@@ -0,0 +1,39 @@
+#!/bin/sh
+set -eu
+
+script_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+cd "$script_dir"
+umask 077
+
+if [ ! -f .env ]; then
+  echo "Missing .env. Run ./setup.sh first." >&2
+  exit 1
+fi
+
+set -a
+# shellcheck disable=SC1091
+. ./.env
+set +a
+
+timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
+destination="$script_dir/runtime/backups/$timestamp"
+mkdir -p "$destination"
+
+docker compose exec -T postgres \
+  pg_dump --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" --format=custom \
+  > "$destination/postgres.dump"
+
+tar -czf "$destination/synapse-critical.tar.gz" \
+  -C "$script_dir/runtime/synapse" \
+  homeserver.yaml \
+  "$MESH_SERVER_NAME.signing.key" \
+  "$MESH_SERVER_NAME.log.config"
+
+if [ -d "$script_dir/runtime/synapse/media_store" ]; then
+  tar -czf "$destination/media-store.tar.gz" \
+    -C "$script_dir/runtime/synapse" \
+    media_store
+fi
+
+test -s "$destination/postgres.dump"
+echo "Backup completed: $destination"

mesh/infra/homeserver/configure_synapse.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Apply Mesh's production-safe Synapse settings to a generated config."""
+
+from __future__ import annotations
+
+import os
+import pathlib
+import sys
+
+import yaml
+
+
+def required(name: str) -> str:
+    value = os.environ.get(name, "").strip()
+    if not value or value.startswith("REPLACE_"):
+        raise SystemExit(f"{name} is missing or still contains a placeholder")
+    return value
+
+
+def main() -> None:
+    if len(sys.argv) != 2:
+        raise SystemExit("usage: configure_synapse.py /data/homeserver.yaml")
+
+    config_path = pathlib.Path(sys.argv[1])
+    config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+
+    server_name = required("MESH_SERVER_NAME")
+    homeserver_host = required("MESH_HOMESERVER_HOST")
+
+    config.update(
+        {
+            "server_name": server_name,
+            "public_baseurl": f"https://{homeserver_host}/",
+            "pid_file": "/data/homeserver.pid",
+            "report_stats": False,
+            "listeners": [
+                {
+                    "port": 8008,
+                    "type": "http",
+                    "tls": False,
+                    "x_forwarded": True,
+                    "bind_addresses": ["0.0.0.0"],
+                    "resources": [
+                        {
+                            "names": ["client", "federation"],
+                            "compress": False,
+                        }
+                    ],
+                }
+            ],
+            "database": {
+                "name": "psycopg2",
+                "txn_limit": 10000,
+                "args": {
+                    "user": required("POSTGRES_USER"),
+                    "password": required("POSTGRES_PASSWORD"),
+                    "dbname": required("POSTGRES_DB"),
+                    "host": "postgres",
+                    "port": 5432,
+                    "cp_min": 1,
+                    "cp_max": 5,
+                },
+            },
+            "media_store_path": "/data/media_store",
+            "max_upload_size": "100M",
+            "enable_media_repo": True,
+            "media_retention": {
+                "remote_media_lifetime": "30d",
+            },
+            "url_preview_enabled": False,
+            "enable_registration": False,
+            "enable_registration_without_verification": False,
+            "allow_guest_access": False,
+            "registration_shared_secret": required("REGISTRATION_SHARED_SECRET"),
+            "macaroon_secret_key": required("MACAROON_SECRET_KEY"),
+            "form_secret": required("FORM_SECRET"),
+            "password_config": {
+                "enabled": True,
+                "localdb_enabled": True,
+            },
+            "allow_public_rooms_without_auth": False,
+            "allow_public_rooms_over_federation": False,
+            "serve_server_wellknown": False,
+            "trusted_key_servers": [{"server_name": "matrix.org"}],
+            "suppress_key_server_warning": True,
+        }
+    )
+
+    rendered = yaml.safe_dump(config, sort_keys=False, default_flow_style=False)
+    temporary_path = config_path.with_suffix(".yaml.tmp")
+    temporary_path.write_text(rendered, encoding="utf-8")
+    temporary_path.chmod(0o600)
+    temporary_path.replace(config_path)
+    config_path.chmod(0o600)
+
+
+if __name__ == "__main__":
+    main()