How to Self-Host a Matrix Server Using ESS Community

The Element Server Suite Community Edition (ESS Community) is a ready-to-use, open-source Matrix stack that can be deployed on your own server using Kubernetes and Helm. It includes:

• Synapse (Matrix homeserver)
• Element Web (web client)
• Matrix Authentication Service (MAS)
• Element Call RTC Backend
• PostgreSQL (database, optional)
• HAProxy (load balancing)
• Hookshot (bot for integrations)

This guide will walk you through the process of setting up a basic Matrix server for personal or small community use.

Prerequisites

1. A server with at least 2 CPU cores and 2 GB RAM
2. A domain name (e.g., yourdomain.com)
3. Basic knowledge of Linux, DNS, and command line
4. Access to a Kubernetes cluster (we’ll use K3s for simplicity)
5. Helm installed
6. Cert-Manager (optional, for Let’s Encrypt certificates)

Step 1: Set Up DNS

Create the following DNS records pointing to your server’s public IP:

You may also need to open ports 80 (HTTP), 443 (HTTPS), 30881 (TCP), and 30882 (UDP) on your firewall.

Step 2: Install K3s (Lightweight Kubernetes)

On your server, run:

curl -sfL https://get.k3s.io | sh -

Set up kubectl:

mkdir ~/.kube
export KUBECONFIG=~/.kube/config
sudo k3s kubectl config view --raw > "$KUBECONFIG"
chmod 600 "$KUBECONFIG"
chown "$USER:$USER" "$KUBECONFIG"
echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc

Install Helm:

curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Create a namespace for ESS:

kubectl create namespace ess

Step 3: Set Up TLS Certificates

Now for the Certificate. We will use “Let’s Encrypt” which is free and overall pretty good.

Install Cert-Manager:

helm repo add jetstack https://charts.jetstack.io --force-update
helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --version v1.17.0 --set crds.enabled=true

Create a ClusterIssuer for Let’s Encrypt:

kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-prod-private-key
    solvers:
      - http01:
          ingress:
            class: traefik
EOF

Download the TLS configuration for ESS:

mkdir ~/ess-config-values
curl -L https://raw.githubusercontent.com/element-hq/ess-helm/main/charts/matrix-stack/ci/fragments/quick-setup-letsencrypt.yaml -o ~/ess-config-values/tls.yaml

Step 4: Configure Hostnames

Download the hostname configuration and edit it to match your domain:

curl -L https://raw.githubusercontent.com/element-hq/ess-helm/main/charts/matrix-stack/ci/fragments/quick-setup-hostnames.yaml -o ~/ess-config-values/hostnames.yaml

Edit hostnames.yaml to replace placeholders with your actual domain names.

Step 5: Install ESS Community

Run the Helm command to install the stack:

helm upgrade --install --namespace "ess" ess oci://ghcr.io/element-hq/ess-helm/matrix-stack \
  -f ~/ess-config-values/hostnames.yaml \
  -f ~/ess-config-values/tls.yaml \
  --wait

Wait for the installation to complete.

Step 6: Create Your First User

By default, user registration is disabled. To create your first user:

kubectl exec -n ess -it deploy/ess-matrix-authentication-service -- mas-cli manage register-user

Follow the prompts to create a username and password.

Step 7: Verify Your Setup

1. Open your Element Web client (e.g., https://chat.yourdomain.com)
2. Log in with the user you just created.
3. Test federation using Matrix Federation Tester.
4. Try logging in from a mobile client (Element X).

More Stuff

• To allow others to register, you’ll need to configure SMTP for email verification. See the official docs for details.
• For backups, upgrades, and troubleshooting, refer to the Maintenance Guide.
• To uninstall, run:
  helm uninstall ess -n ess
kubectl delete namespace ess
  

You now have a fully functional Matrix server running on your own infrastructure, with a web client, authentication, and all the essentials for a small community or personal use. You can further customize the setup by enabling additional components or integrating with external services.

For more information and other guides, check the ESS-Helm repo

---

Like my content? Support me with a tip!

Recommended Posts

Embraer: Brazil is selling flying cars to Japan

What Is AI Psychosis? A serious new disease

Notepad++ Hijacked by Chinese State-Sponsored Hackers