Initial VPS operations handbook

2026-08-03 12:26:42 +08:00
commit b73125e5bc
97 changed files with 3641 additions and 0 deletions
@@ -0,0 +1,109 @@
+# Matrix (Element Server Suite) Upstream References
+
+Matrix homeserver deployed via **Element Server Suite (ESS) Community** OCI chart.
+
+## Chart
+
+| Property | Value |
+|---|---|
+| Chart name | `matrix-stack` |
+| OCI registry | `oci://ghcr.io/element-hq/ess-helm/matrix-stack` |
+| Version deployed | `26.7.2` |
+| Chart source | <https://github.com/element-hq/ess-helm> |
+| Documentation | <https://element-hq.github.io/ess-helm/> |
+
+## Components
+
+| Component | Docker image | Role |
+|---|---|---|
+| Synapse | `ghcr.io/element-hq/synapse:*` | Matrix homeserver |
+| MAS | `ghcr.io/element-hq/matrix-authentication-service:*` | OIDC/OAuth authentication |
+| Element Web | `ghcr.io/element-hq/element-web:*` | Web client |
+| Element Admin | `ghcr.io/element-hq/element-admin:*` | Admin console |
+| HAProxy | `haproxy:*` | Internal routing/health |
+| PostgreSQL | `postgres:17` | Synapse + MAS database |
+
+All images should be locked via digest in production; the chart's `appVersion` may not match default image tags.
+
+## Domain configuration
+
+| Hostname | Component |
+|---|---|
+| `chans.xyz` | Matrix identity (`serverName`) + well-known discovery |
+| `synapse.chans.xyz` | Client-Server API, Federation API |
+| `chat.chans.xyz` | Element Web |
+| `account.chans.xyz` | Matrix Authentication Service (local passwords) |
+| `admin.chans.xyz` | Element Admin (MAS admin auth) |
+| `mrtc.chans.xyz` | Reserved for MatrixRTC — **not deployed** |
+
+## TLS & Ingress
+
+- Ingress controller: K3s built-in Traefik (IngressClass `traefik`)
+- Certificate issuer: cert-manager + Let's Encrypt HTTP-01 (`letsencrypt-prod` ClusterIssuer)
+- All TLS enabled: `global.ingress.tls.enabled=true`
+- Issuer annotation: `cert-manager.io/cluster-issuer: letsencrypt-prod`
+
+## Architecture
+
+```
+Internet :80/:443
+  → K3s Traefik (hostPort)
+  → ESS Ingresses (Traefik class)
+  → ClusterIP Services
+  → Pods (Synapse, MAS, Element, Admin, HAProxy)
+  → PostgreSQL (StatefulSet, 20Gi PVC)
+```
+
+## Deployment
+
+The ESS chart is deployed via Ansible (`ansible/playbooks/matrix-stack.yml`) with non-secret values at `/etc/ess/*.yaml` on the target host.
+
+**Secrets** (signing key, database passwords, SMTP password, MAS keys) are **not** in Git. They are stored:
+1. On the VPS at `/etc/matrix-bootstrap/` (root:root 0600 files)
+2. In pre-created Kubernetes Secrets in the `ess` namespace
+
+## Upgrades
+
+```bash
+# Pull latest chart version
+helm pull oci://ghcr.io/element-hq/ess-helm/matrix-stack --version <new-version>
+
+# Review changes
+helm diff upgrade ess oci://ghcr.io/element-hq/ess-helm/matrix-stack \
+  -n ess -f /etc/ess/hostnames.yaml -f /etc/ess/tls.yaml
+
+# Apply
+helm upgrade --install ess oci://ghcr.io/element-hq/ess-helm/matrix-stack \
+  -n ess -f /etc/ess/hostnames.yaml -f /etc/ess/tls.yaml --wait
+```
+
+Before upgrading:
+- Matrix backup automation is currently paused; establish and test a reviewed backup design before treating the deployment as recoverable.
+- Review chart changelog and database migration notes
+- Test in isolation if possible
+
+## Recovery
+
+When the planned backup automation is enabled, recovery will require the following from `/var/backups/matrix/`:
+
+1. PostgreSQL dumps (synapse + mas)
+2. Media store archive
+3. Bootstrap secrets archive (`/etc/matrix-bootstrap/`)
+4. Non-secret values files (`/etc/ess/*.yaml`)
+5. Non-secret playbook templates (from this repo)
+
+Steps:
+1. Deploy K3s + Traefik + cert-manager per Ansible
+2. Restore bootstrap secrets + create Kubernetes Secrets
+3. Restore PostgreSQL dumps
+4. Restore media store to PVC
+5. Deploy ESS chart with same values
+
+## References
+
+- ESS Helm docs: <https://element-hq.github.io/ess-helm/>
+- ESS Community setup: <https://github.com/element-hq/element-server-suite>
+- Synapse: <https://github.com/element-hq/synapse>
+- Matrix Authentication Service: <https://github.com/element-hq/matrix-authentication-service>
+- Matrix spec: <https://spec.matrix.org/>
+- Federation tester: <https://federationtester.matrix.org/>