112 lines
4.0 KiB
Markdown
112 lines
4.0 KiB
Markdown
# 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
|
|
|
|
Update the pinned `matrix_stack_chart_version` in
|
|
`ansible/inventory/hosts.yml` through normal review, then apply the chart via
|
|
the gated Ansible playbook:
|
|
|
|
```bash
|
|
cd ansible
|
|
ansible-playbook playbooks/matrix-preflight.yml
|
|
ansible-playbook playbooks/matrix-stack.yml --limit matrix \
|
|
-e 'matrix_stack_enabled=true'
|
|
```
|
|
|
|
Use `helm diff` on the target only as a read-only supplement when the plugin is
|
|
installed; do not apply a release with a hand-written `helm upgrade` command.
|
|
|
|
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/>
|
|
- Home Assistant Matrix integration: [home-assistant-matrix.md](home-assistant-matrix.md)
|