### Setup Test Cluster

Source: https://github.com/element-hq/ess-helm/blob/main/DEVELOPERS.md

Use this script to set up a local test cluster. It installs necessary components like an ingress controller, metrics-server, and cert-manager, and configures local DNS resolution.

```bash
./scripts/setup_test_cluster.sh
```

--------------------------------

### Download Quick Setup Hostnames

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Use this command to download the default quick setup hostnames configuration file.

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

--------------------------------

### Install ESS Migration Tool with uv

Source: https://github.com/element-hq/ess-helm/blob/main/packages/ess-migration-tool/README.md

Installs the ESS Migration Tool using uv. Ensure uv is installed and configured.

```bash
uv tool install ess-migration-tool
```

--------------------------------

### Install ess-migration-tool

Source: https://context7.com/element-hq/ess-helm/llms.txt

Install the `ess-migration-tool` using pip or uv for converting existing Synapse configurations to ESS Helm values. This tool requires Python to be installed.

```bash
# Install the migration tool (requires Python)
pip install ess-migration-tool
# or
uv tool install ess-migration-tool
```

--------------------------------

### Install ESS Migration Tool with pipx

Source: https://github.com/element-hq/ess-helm/blob/main/packages/ess-migration-tool/README.md

Installs the ESS Migration Tool using pipx. Ensure pipx is installed and configured.

```bash
pipx install ess-migration-tool
```

--------------------------------

### Install K3s Kubernetes

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Run this command to install K3s on your server. Ensure firewall rules are configured according to K3s recommendations if a firewall is active.

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

--------------------------------

### Install ESS Community Integration Tests

Source: https://github.com/element-hq/ess-helm/blob/main/tests/README.md

Install the integration tests using pipx or uv. For development, you can install directly from the git repository.

```sh
pipx install ess-community-integration-tests
```

```sh
uvx ess-community-integration-tests
```

```sh
# You can also use any ESS Community version
VERSION=main
uv tool install git+https://github.com/element-hq/ess-helm.git@$VERSION#subdirectory=tests
```

--------------------------------

### Install Helm Package Manager

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Install Helm, the Kubernetes Package Manager, using the provided script. Alternatively, use your OS's package repository.

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

--------------------------------

### Install Cert-Manager Helm Chart

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Installs the Cert-Manager Helm chart into the 'cert-manager' namespace. Ensure the version matches your requirements.

```bash
helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.17.0 \
  --set crds.enabled=true
```

--------------------------------

### Download Let's Encrypt Configuration Fragment

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Downloads a pre-configured YAML fragment for Let's Encrypt setup into the ESS configuration values directory.

```bash
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
```

--------------------------------

### Download Individual Certificates Configuration Fragment

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Downloads a pre-configured YAML fragment for individual certificate setup into the ESS configuration values directory.

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

--------------------------------

### Configure Let's Encrypt TLS with Cert-Manager

Source: https://context7.com/element-hq/ess-helm/llms.txt

Sets up Cert-Manager for automatic TLS certificate provisioning via Let's Encrypt. Requires prior installation of Cert-Manager.

```bash
# 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 and use the Let's Encrypt TLS fragment
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

# Re-deploy with TLS
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

```

--------------------------------

### Download Wildcard Certificate Configuration Fragment

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Downloads a pre-configured YAML fragment for wildcard certificate setup into the ESS configuration values directory.

```bash
curl -L https://raw.githubusercontent.com/element-hq/ess-helm/refs/heads/main/charts/matrix-stack/ci/fragments/quick-setup-wildcard-cert.yaml -o ~/ess-config-values/tls.yaml
```

--------------------------------

### Run ESS Migration Tool and Deploy with Helm

Source: https://context7.com/element-hq/ess-helm/llms.txt

Use the migration tool to prepare Synapse configuration and then apply secrets and deploy the ESS Helm chart. Ensure secrets are applied before installing the chart.

```bash
ess-migration-tool \
  --synapse-config /etc/matrix-synapse/homeserver.yaml \
  --output-dir ~/ess-migration-output

# The tool produces:
#   ~/ess-migration-output/values.yaml          (Helm values)
#   ~/ess-migration-output/secrets/             (Kubernetes Secret manifests)
#   ~/ess-migration-output/configmaps/          (Optional: extra config ConfigMaps)

# Apply secrets first, then install the chart
kubectl apply -f ~/ess-migration-output/secrets/ -n ess
helm upgrade --install --namespace ess ess \
  oci://ghcr.io/element-hq/ess-helm/matrix-stack \
  -f ~/ess-migration-output/values.yaml \
  -f ~/ess-config-values/tls.yaml \
  --wait
```

--------------------------------

### Configure K3s Kubeconfig

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

After installing K3s, copy its kubeconfig to your home directory for kubectl access. Add the export command to your ~/.bashrc for persistence.

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

--------------------------------

### Install ESS Helm Chart with Minimal Hostnames

Source: https://context7.com/element-hq/ess-helm/llms.txt

Deploys the ESS Community Helm chart with a basic hostname configuration. Ensure the namespace 'ess' exists before running.

```bash
# 1. Create the namespace
kubectl create namespace ess

# 2. Prepare a hostnames values file (hostnames.yaml)
cat > ~/ess-config-values/hostnames.yaml <<'EOF'
serverName: your.tld

synapse:
  ingress:
    host: matrix.your.tld

matrixAuthenticationService:
  ingress:
    host: account.your.tld

matrixRTC:
  ingress:
    host: mrtc.your.tld

elementWeb:
  ingress:
    host: chat.your.tld

elementAdmin:
  ingress:
    host: admin.your.tld
EOF

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

# Expected: all pods Running, helm returns "STATUS: deployed"

```

--------------------------------

### Add Jetstack Helm Repository

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Adds the Jetstack Helm repository, which is necessary for installing Cert-Manager.

```bash
helm repo add jetstack https://charts.jetstack.io --force-update
```

--------------------------------

### Uninstall Additional Components

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Commands to uninstall other components that might have been installed separately, such as cert-manager, and to uninstall Helm and k3s.

```bash
# Remove cert-manager from cluster
helm uninstall cert-manager -n cert-manager

# Uninstall helm
rm -rf /usr/local/bin/helm $HOME/.cache/helm $HOME/.config/helm $HOME/.local/share/helm

# Uninstall k3s
/usr/local/bin/k3s-uninstall.sh
```

--------------------------------

### Enable and Configure Hookshot with Webhooks

Source: https://context7.com/element-hq/ess-helm/llms.txt

Enable Hookshot and configure generic webhook settings, including enabling HTTP GET requests and JavaScript transformation functions.

```yaml
# hookshot-config.yaml
hookshot:
  enabled: true
  ingress:
    host: hookshot.your.tld   # Optional: dedicated hostname; default is behind Synapse host

  additional:
    webhooks.yaml:
      config: |
        generic:
          enabled: true
          allowJsTransformationFunctions: false
          waitForComplete: true
          enableHttpGet: false
```

--------------------------------

### Apache2 Reverse Proxy Configuration

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Minimal Apache2 vhost example for reverse proxy with TLS termination. Ensure necessary modules are enabled.

```apache
<VirtualHost *:*>
  ServerName <your domain/subdomain>
  SSLEngine on
  SSLCertificateFile /path/to/your/certfile
  SSLCertificateKeyFile /path/to/your/keyfile
  SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
  SSLHonorCipherOrder on
  SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
  Header unset Strict-Transport-Security
  Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"

  ProxyPreserveHost On
  ProxyPass / http://127.0.0.1:8080/ nocanon
  ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>
```

--------------------------------

### Execute Syn2mas Migration

Source: https://github.com/element-hq/ess-helm/blob/main/docs/syn2mas.md

Run this command to perform the syn2mas migration. Ensure `--reuse-values` and `--set matrixAuthenticationService.syn2mas.dryRun=false` are included. If an OAuth Provider was previously used, add `--set synapse.checkConfigHook.enabled=false` to bypass configuration checks, though this may prevent Synapse from starting post-migration.

```bash
helm upgrade --namespace "ess" ess oci://ghcr.io/element-hq/ess-helm/matrix-stack --reuse-values --wait --set matrixAuthenticationService.syn2mas.dryRun=false
```

```bash
helm upgrade --namespace "ess" ess oci://ghcr.io/element-hq/ess-helm/matrix-stack --reuse-values --wait --set matrixAuthenticationService.syn2mas.dryRun=false --set synapse.checkConfigHook.enabled=false
```

--------------------------------

### Set Up Kubernetes Cluster for Testing

Source: https://github.com/element-hq/ess-helm/blob/main/tests/README.md

Use the `setup-ess-cluster` command to provision a Kubernetes cluster for running integration tests.

```bash
setup-ess-cluster
```

--------------------------------

### Download Project Dependencies

Source: https://github.com/element-hq/ess-helm/blob/main/matrix-tools/README.md

Use `go mod download` to fetch all project dependencies. Ensure you are in the project root directory.

```sh
cd path/to/matrix-tools
go mod download
```

--------------------------------

### Run Project Linting

Source: https://github.com/element-hq/ess-helm/blob/main/matrix-tools/README.md

Execute `golangci-lint` to check code quality and style across the project. Run this command from the project root.

```sh
golangci-lint run ./...
```

--------------------------------

### Download External Certificate Configuration

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Use this curl command to download the `quick-setup-external-cert.yaml` file. This is useful if your reverse proxy handles TLS certificates and you want to disable TLS in ESS.

```bash
curl -L https://raw.githubusercontent.com/element-hq/ess-helm/refs/heads/main/charts/matrix-stack/ci/fragments/quick-setup-external-cert.yaml -o ~/ess-config-values/tls.yaml
```

--------------------------------

### Uninstall cert-manager and clean up Helm

Source: https://context7.com/element-hq/ess-helm/llms.txt

Use these commands to uninstall cert-manager and remove Helm from your system. This is useful for cleaning up previous installations.

```bash
helm uninstall cert-manager -n cert-manager
rm -rf /usr/local/bin/helm $HOME/.cache/helm $HOME/.config/helm $HOME/.local/share/helm
```

--------------------------------

### Build the Go Application

Source: https://github.com/element-hq/ess-helm/blob/main/matrix-tools/README.md

Compile the Go application using `go build`. The output executable will be named `matrix-tools`.

```sh
cd matrix-tools
go build -o matrix-tools cmd/main.go
```

--------------------------------

### Basic Synapse Migration

Source: https://github.com/element-hq/ess-helm/blob/main/packages/ess-migration-tool/README.md

Performs a basic migration using only the Synapse configuration file. Specify the path to your homeserver.yaml.

```bash
ess-migration-tool --synapse-config /path/to/synapse/homeserver.yaml
```

--------------------------------

### Generate New Synapse Signing Key

Source: https://github.com/element-hq/ess-helm/blob/main/docs/maintenance.md

Use this command to generate a new Ed25519 signing key with ID 'ed25519:1'. Ensure 'signedjson' and 'pyyaml' are installed.

```bash
$ python3 -c "import signedjson.key; signing_key = signedjson.key.generate_signing_key(1); print(f\"{signing_key.alg} {signing_key.version} {signedjson.key.encode_signing_key_base64(signing_key)}\")"
```

--------------------------------

### Get Traefik External IP

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Use this command to retrieve the external IP address provisioned by Kubernetes for Traefik. This IP is needed for configuring your reverse proxy.

```bash
kubectl get svc/traefik -n kube-system
```

--------------------------------

### Run Project Tests

Source: https://github.com/element-hq/ess-helm/blob/main/matrix-tools/README.md

Execute all unit tests within the project using the `go test` command. This command should be run from the project root.

```sh
go test ./...
```

--------------------------------

### Generate New Synapse Signing Key

Source: https://context7.com/element-hq/ess-helm/llms.txt

Generate a new ed25519 signing key and a throwaway revocation key using Python. Ensure you have `signedjson` and `pyyaml` installed.

```python
import signedjson.key
k = signedjson.key.generate_signing_key(1)
print(f'{k.alg} {k.version} {signedjson.key.encode_signing_key_base64(k)}')
```

```python
import yaml, time, signedjson.key
k = signedjson.key.generate_signing_key(0)
ts = int(time.time()*1000)
print(yaml.dump({'old_signing_keys': {'ed25519:0': {
  'key': signedjson.key.encode_verify_key_base64(k),
  'expired_ts': ts
}}}))
```

--------------------------------

### Create Initial User with mas-cli

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Executes the mas-cli command within the Matrix Authentication Service pod to register an initial user interactively.

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

--------------------------------

### Register First User with MAS CLI

Source: https://github.com/element-hq/ess-helm/blob/main/charts/matrix-stack/templates/NOTES.txt

Use this command to register the initial user after deploying the Matrix Authentication Service. Ensure the release namespace and release name are correctly specified.

```bash
kubectl exec -n {{ $.Release.Namespace }} -it deployment/{{ $.Release.Name }}-matrix-authentication-service -- mas-cli manage register-user
```

--------------------------------

### Deploy to Test Cluster

Source: https://github.com/element-hq/ess-helm/blob/main/DEVELOPERS.md

Deploy the ESS chart to a test cluster using Helm. This command upgrades or installs the chart in a specified namespace with provided values files.

```bash
helm -n <namespace> upgrade -i ess charts/matrix-stack -f charts/matrix-stack/ci/test-cluster-mixin.yaml( -f <additional values file>)+
```

```bash
helm -n ess upgrade -i ess charts/matrix-stack -f charts/matrix-stack/ci/test-cluster-mixin.yaml -f charts/matrix-stack/ci/example-default-enabled-components-values.yaml
```

--------------------------------

### Prepare ESS Configuration Directory

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Create a directory named 'ess-config-values' in your home directory to store the Element Server Suite configuration values.

```bash
mkdir ~/ess-config-values
```

--------------------------------

### Uninstall ESS Components

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Commands to uninstall the ESS Helm release, associated secrets, configmaps, and persistent volume claims. Adjust commands based on enabled components during installation.

```bash
helm uninstall ess -n ess
# If initSecrets is enabled, you may need to delete this
kubectl delete secrets/ess-generated -n ess
# If deploymentMarkers is enabled, you may need to delete this
kubectl delete configmap/ess-deployment-markers -n ess
# If synapse is enabled, you may need to delete this
kubectl delete pvc/ess-synapse-media -n ess
# If postgres is enabled and either synapse or matrixAuthenticationService is enabled, you may need to delete this
kubectl delete pvc/ess-postgres-data -n ess
```

--------------------------------

### Caddy Reverse Proxy Configurations

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Two Caddy reverse proxy configurations for ESS Community with TLS termination. The first is for a dedicated domain, the second for adding ESS to an existing Caddy setup.

```caddy
example.com matrix.example.com account.example.com mrtc.example.com chat.example.com admin.example.com {
  reverse_proxy http://127.0.0.1:8080
}
```

```caddy
example.com {
  # Other directives or matcher definitions i.e. your personal homepage or a blog under example.com/blog/ could be in here as well
  #
  reverse_proxy /.well-known/matrix/* http://127.0.0.1:8080
}

admin.example.com chat.example.com account.example.com mrtc.example.com matrix.example.com {
  reverse_proxy http://127.0.0.1:8080
}
```

--------------------------------

### Migrate Synapse Auth to Matrix Authentication Service (Step 1)

Source: https://context7.com/element-hq/ess-helm/llms.txt

Step 1 of the syn2mas migration: Deploy MAS in read-only/dry-run mode. This allows MAS to initialize its database and for users to log in via Synapse while the migration is being prepared.

```bash
# Step 1: Deploy MAS in read-only/dry-run mode
helm upgrade --install --namespace ess ess \
  oci://ghcr.io/element-hq/ess-helm/matrix-stack \
  -f ~/ess-config-values/hostnames.yaml \
  --set matrixAuthenticationService.syn2mas.enabled=true \
  --wait
# Result: deployment-marker = legacy_auth, MAS initialises DB, users log in via Synapse
```

--------------------------------

### Apply New Signing Key and Revocation to Values

Source: https://context7.com/element-hq/ess-helm/llms.txt

Configure the new signing key and the revocation details in the Helm values. Replace placeholders with the actual output from the key generation scripts.

```yaml
synapse:
  signingKey:
    value: "ed25519 1 BUIaPWxxx..."

  additional:
    revoke_bad_signing_key.yml:
      config: |
        old_signing_keys:
          ed25519:0:
            key: <throwaway verifying key output above>
            expired_ts: <timestamp output above>
```

--------------------------------

### Extract Deployment Markers ConfigMap

Source: https://github.com/element-hq/ess-helm/blob/main/docs/maintenance.md

Copy the chart's deployment markers ConfigMap to a local file. This ensures `helm upgrade` maintains a valid installation state. Adjust the namespace ('ess') if required.

```sh
kubectl get configmap -l "app.kubernetes.io/managed-by=matrix-tools-deployment-markers"  -n ess -o yaml > configmaps.yaml
```

--------------------------------

### Check Licenses with reuse

Source: https://github.com/element-hq/ess-helm/blob/main/DEVELOPERS.md

Ensure all files have correct copyright and licensing information by running the `reuse lint` command from the project root.

```bash
reuse lint
```

--------------------------------

### Start Event Resigning Background Job

Source: https://github.com/element-hq/ess-helm/blob/main/docs/maintenance.md

Manually trigger the 'event_resign' background job using the Synapse Admin API. This is necessary when upgrading from older versions to ensure all events are re-signed with the new key.

```json
curl -s https://<your synapse host>/_synapse/admin/v1/background_updates/start_job -H 'Authorization: Bearer <admin access token>' -H 'Content-type: application/json' -d '{"job_name": "event_resign"}'
```

--------------------------------

### Migration with Well-Known Delegation Files (Individual Files)

Source: https://github.com/element-hq/ess-helm/blob/main/packages/ess-migration-tool/README.md

Migrates Synapse configuration and specifies individual well-known delegation files. Use this if files are not in a single directory.

```bash
ess-migration-tool --synapse-config /path/to/synapse/homeserver.yaml \
  --well-known-client /path/to/client.json \
  --well-known-server /path/to/server.json \
  --well-known-support /path/to/support.json
```

--------------------------------

### Configure Hookshot Permissions in Helm Chart

Source: https://github.com/element-hq/ess-helm/blob/main/CHANGELOG.md

Example of setting default permissions for Hookshot in the Helm chart. This configuration ensures local users can manage integrations and connections, while specific users are granted admin privileges.

```yaml
hookshot:
  additional:
    permissions.yaml:
      config: |
        permissions:
        - actor: {{ $.Values.serverName | quote }}
          services:
          - service: "*"
            level: manageConnections
        - action: "@an-admin-user:{{ $.Values.serverName }}"
          services:
          - service: "*"
            level: admin
```

--------------------------------

### Migration with Well-Known Delegation Files (Directory)

Source: https://github.com/element-hq/ess-helm/blob/main/packages/ess-migration-tool/README.md

Migrates Synapse configuration along with well-known delegation files from a specified directory. Ensure client.json, server.json, and support.json are present in the directory.

```bash
ess-migration-tool --synapse-config /path/to/synapse/homeserver.yaml --well-known-dir /path/to/well-known/
```

--------------------------------

### Register User with mas-cli

Source: https://context7.com/element-hq/ess-helm/llms.txt

Use the `mas-cli` tool to register a user non-interactively. Ensure the `ess-matrix-authentication-service` deployment is running.

```bash
kubectl exec -n ess -it deploy/ess-matrix-authentication-service \
  -- mas-cli manage register-user --yes alice
```

--------------------------------

### Configure SFU IP Advertisement: STUN

Source: https://github.com/element-hq/ess-helm/blob/main/docs/troubleshooting.md

Configure the SFU to use STUN to discover its public IP address. This is the default behavior if `useStunToDiscoverPublicIP` is true and `manualIP` is not set.

```yaml
matrixRTC:
  sfu:
    useStunToDiscoverPublicIP: true
```

--------------------------------

### ESS Migration Tool Usage

Source: https://github.com/element-hq/ess-helm/blob/main/packages/ess-migration-tool/README.md

Displays the command-line usage and available options for the ESS migration tool. Use this to understand how to configure the migration process.

```bash
usage: ess-migration-tool [-h] --synapse-config SYNAPSE_CONFIG [--mas-config MAS_CONFIG]
                          [--well-known-dir WELL_KNOWN_DIR] [--well-known-client WELL_KNOWN_CLIENT]
                          [--well-known-server WELL_KNOWN_SERVER] [--well-known-support WELL_KNOWN_SUPPORT]
                          [--element-web-config ELEMENT_WEB_CONFIG] [--hookshot-config HOOKSHOT_CONFIG]
                          [--output-dir OUTPUT_DIR] [--verbose] [--debug] [--quiet]
                          [--database-mode {existing,ess-managed}]

Migrate Matrix Stack configurations to Element Server Suite Helm values

options:
  -h, --help            show this help message and exit
  --synapse-config SYNAPSE_CONFIG
                        Path to Synapse homeserver.yaml configuration file. This is the main Synapse
                        configuration that contains server_name, database, listeners, etc.
  --mas-config MAS_CONFIG
                        Path to Matrix Authentication Service config.yaml configuration file.
  --well-known-dir WELL_KNOWN_DIR
                        Path to directory containing well-known delegation files (client.json, server.json,
                        support.json). These files configure Matrix delegation for your domain.
  --well-known-client WELL_KNOWN_CLIENT
                        Path to a well-known client delegation file (client or client.json). Takes precedence
                        over --well-known-dir if both are specified.
  --well-known-server WELL_KNOWN_SERVER
                        Path to a well-known server delegation file (server or server.json). Takes precedence
                        over --well-known-dir if both are specified.
  --well-known-support WELL_KNOWN_SUPPORT
                        Path to a well-known support delegation file (support or support.json). Takes precedence
                        over --well-known-dir if both are specified.
  --element-web-config ELEMENT_WEB_CONFIG
                        Path to Element Web config.json configuration file.
  --hookshot-config HOOKSHOT_CONFIG
                        Path to Hookshot hookshot-config.yaml configuration file.
  --output-dir OUTPUT_DIR
                        Output directory for generated files (default: output). The migration will create Helm
                        values.yaml and any ConfigMap files in this directory.
  --verbose             Enable verbose logging. Shows detailed information about the migration process.
  --debug               Enable debug logging. Shows debug information about the migration process.
  --quiet               Disable migration summary output.
  --database-mode {existing,ess-managed}
                        Database migration mode. 'existing' to use existing database, 'ess-managed' to use ESS-
                        managed Postgres. If not specified, user will be prompted.
```

--------------------------------

### Configure Manual Public IP

Source: https://github.com/element-hq/ess-helm/blob/main/docs/advanced.md

If your host is behind NAT and STUN is disabled, set `manualIP` to your node's public IP address.

```yaml
matrixRTC:
  sfu:
    manualIP: "<your node public IP>"
```

--------------------------------

### Migration with Element Web Configuration

Source: https://github.com/element-hq/ess-helm/blob/main/packages/ess-migration-tool/README.md

Migrates Synapse configuration and custom Element Web settings. Provide the path to your element-web/config.json.

```bash
ess-migration-tool --synapse-config /path/to/synapse/homeserver.yaml --element-web-config /path/to/element-web/config.json
```

--------------------------------

### Create First User with MAS CLI

Source: https://context7.com/element-hq/ess-helm/llms.txt

Registers the initial user for the Matrix Authentication Service (MAS) when self-registration is disabled. This command must be run interactively within the MAS pod.

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

# Interactive prompts:
# ✔ Username · alice
# ✔ What do you want to do next? · Set a password
# ✔ Password · ********

```

--------------------------------

### Enable Turn-TLS

Source: https://github.com/element-hq/ess-helm/blob/main/docs/advanced.md

Enable Turn-TLS for the SFU by setting `enabled` to `true`. Configure the `domain` and optionally the `tlsSecret` for the advertised turn address.

```yaml
matrixRTC:
  sfu:
    exposedServices:
      turnTLS:
        enabled: true
        domain: <turn domain advertised to the clients>
        tlsSecret: <tls secret for the turn domain. Optional if cert manager is enabled>
```

--------------------------------

### Dump Postgres Database

Source: https://github.com/element-hq/ess-helm/blob/main/docs/maintenance.md

Create a full dump of the provided Postgres database using `pg_dumpall`. Ensure the namespace and release name are correctly specified.

```sh
kubectl exec --namespace ess -it sts/ess-postgres -- pg_dumpall -U postgres > dump.sql
```

--------------------------------

### Configure Wildcard TLS Certificate from File

Source: https://context7.com/element-hq/ess-helm/llms.txt

Applies a pre-existing wildcard TLS certificate stored in a Kubernetes Secret. Ensure the secret 'ess-certificate' is created in the 'ess' namespace.

```bash
# Import an existing wildcard certificate
kubectl create secret tls ess-certificate -n ess \
  --cert=path/to/cert.crt \
  --key=path/to/cert.key

# tls.yaml — reference the secret globally
cat > ~/ess-config-values/tls.yaml <<'EOF'
ingress:
  tlsSecret: ess-certificate
EOF

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

```

--------------------------------

### Minimal Synapse Deployment Configuration

Source: https://github.com/element-hq/ess-helm/blob/main/charts/matrix-stack/README.md

A basic set of values required to deploy Synapse, including setting the server name and ingress host.

```yaml
serverName: ess.localhost

synapse:
  ingress:
    host: synapse.ess.localhost
```

--------------------------------

### Lint Chart with chart-testing

Source: https://github.com/element-hq/ess-helm/blob/main/DEVELOPERS.md

Run chart-testing locally to lint the chart. This wrapper around `helm lint` performs additional Helm-based checks.

```bash
scripts/ct-lint.sh
```

```bash
scripts/ct-lint.sh --charts . --validate-maintainers=false
```

--------------------------------

### Build Changelog

Source: https://github.com/element-hq/ess-helm/blob/main/DEVELOPERS.md

Build the changelog from newsfragments in the chart directory. The changelog is also injected into the `Chart.yaml`.

```bash
towncrier build
```

--------------------------------

### Configure Synapse Additional Settings

Source: https://github.com/element-hq/ess-helm/blob/main/docs/advanced.md

Add custom Synapse settings by providing a YAML string under 'additional.user-config.yaml'. Ensure correct indentation for the settings.

```yaml
synapse:
  additional:
    user-config.yaml:
      config: |
        # Add your settings below, taking care of the spacing indentation
        some: settings
```

--------------------------------

### Enable and Configure Hookshot

Source: https://github.com/element-hq/ess-helm/blob/main/docs/advanced.md

Enable Hookshot by setting 'enabled: true'. Further configuration, such as enabling generic webhooks, is done under the 'additional' key using a YAML string.

```yaml
hookshot:
  enabled: true
```

```yaml
hookshot:
  additional:
    user-config.yaml:
      config: |
        generic:
          enabled: true
          allowJsTransformationFunctions: false
          waitForComplete: true
          enableHttpGet: false
```

--------------------------------

### Migration with Matrix Authentication Service

Source: https://github.com/element-hq/ess-helm/blob/main/packages/ess-migration-tool/README.md

Migrates Synapse and Matrix Authentication Service (MAS) configurations. Provide paths to both homeserver.yaml and mas-config.yaml.

```bash
ess-migration-tool --synapse-config /path/to/synapse/homeserver.yaml --mas-config /path/to/mas/config.yaml
```

--------------------------------

### Configure Let's Encrypt ClusterIssuer

Source: https://github.com/element-hq/ess-helm/blob/main/README.md

Applies a ClusterIssuer resource to configure Cert-Manager for Let's Encrypt production certificates using the HTTP01 challenge.

```yaml
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
```