# 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/>