vps/docs/matrix-upstream.md

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:

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/