Skip to content

Advanced

Values documentation

The Helm chart values documentation is available in:

Configuration samples are available in the GitHub repository.

Using a dedicated PostgreSQL instance

By default, the chart deploys a PostgreSQL instance. This is appropriate for development or test environments. In production environments, we strongly recommend you use a PostgresSQL instance run and administered by your database administrators.

The stack can need up to 3 databases:

Each of these databases can be on independent instances or separate databases on the same PostgreSQL instance. They must not be in the same database in the same PostgreSQL instance.

To configure your own PostgreSQL instance in your installation, copy the file charts/matrix-stack/ci/fragments/quick-setup-postgresql.yaml to postgresql.yaml in your ESS configuration values directory and configure it accordingly.

For Group Sync, merge the file charts/matrix-stack/ci/fragments/group-sync-test-postgres.yaml together with charts/matrix-stack/ci/fragments/group-sync-test-postgres-secrets-in-helm.yaml in the postgresql.yaml of your ESS configuration values.

Trusting custom certificate authorities

ESS Pro supports trusting custom certificate authorities across all components that make outbound requests. This includes outbound HTTPS request to e.g. upstream identity providers, external Postgres databases with strict sslMode settings.

This can be configured with either certificates listed in-line in the Helm values file:

# Can be seen in `charts/matrix-stack/ci/fragments/certificate-authorities-in-helm.yaml`
certificateAuthorities:
- certificate: |
    -----BEGIN CERTIFICATE-----
    a PEM encoded CA certificate
    -----END CERTIFICATE-----

Or by referencing existing Secrets in cluster:

# Can be seen in `charts/matrix-stack/ci/fragments/certificate-authorities-externally.yaml`
certificateAuthorities:
- secret: "existing-ca-secret"
  secretKey: "ca.crt"

As many certificate authority certificates as required can be added, using either or both mechanisms. All certificate authority certificates will be trusted, in addition to the default certificate authority certificates.

Configuring the storage path when using K3s

K3s by default deploys the storage in /var/lib/rancher/k3s/storage/. If you want to change the path, you will have to run the K3s setup with the parameter --default-local-storage-path <your path>.

Monitoring

The chart provides ServiceMonitor automatically to monitor the metrics exposed by ESS Pro.

If your cluster has Prometheus Operator or Victoria Metrics Operator installed, the metrics will automatically be scraped.

Configuration

ESS Pro allows you to easily configure its individual components. You basically have to create a values file for each component in which you specify your custom configuration. Below you find sections for each component.

Tip

If you have created new values files for custom configuration, make sure to apply them by passing them with the helm upgrade command (see Setting up the stack).

Configuring Element Web

Element Web configuration is written in JSON. The documentation can be found in the Element Web repository.

To configure Element Web, create a values file with the JSON config to inject as a string under “additional”:

elementWeb:
  additional:
    user-config.json: |
      {
        "some": "settings"
      }

Configuring Synapse

Synapse configuration is written in YAML. The documentation can be found here.

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

Configuring Matrix Authentication Service

Matrix Authentication Service configuration is written in YAML. The MAS documentation can be found here.

See this document for additional ESS MAS documentation.

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

Configuring Well Known Delegation

The Well-Known delegation files are JSON documents that can be configured by providing JSON strings under a specific additional key:

wellKnownDelegation:
  additional:
    # Adds to /.well-known/matrix/server
    server: |
      {
        "more-server-to-server-settings": true
      }
    # Adds to /.well-known/matrix/client
    client: |
      {
        "more-client-to-server-settings": true
      }
    # Adds to /.well-known/matrix/support
    support: |
      {
        "support_page": "https://example.org/support.html"
      }
    # Adds to /.well-known/element/element.json
    element: |
      {
        "brand_color": "#A40FBF"
      }

Configuring GroupSync

GroupSync configuration is written in YAML. The documentation can be found here.

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

External Well-Knowns

Matrix server discovery from both server-side components and clients relies on being able to fetch JSON documents from your server name domain at /.well-known/matrix/server and /.well-known/matrix/client. Additionally the Element Pro applications load some settings from /.well-known/element/element.json.

ESS Pro's wellKnownDelegation component (which is enabled by default), provides appropriate versions of these files for your current settings. However if your server name domain is already in use, and hosted elsewhere, an alternative solution for hosting these JSON documents is required.

There is currently no capability to redirect from the server name domain to another domain hosting the ESS Pro's well-known JSON documents. Additionally SRV delegation for server discovery from server-side components is not supported by ESS Pro and is, in general, strongly discouraged as e.g. there is no corresponding discovery mechanism for clients.

Proxying through to ESS Pro

The reverse proxy that hosts the server name domain may be updated to proxy through the following paths:

  • <serverName>/.well-known/matrix
  • <serverName>/.well-known/element

The reverse proxy should make the request to the address of the ingress controller in the cluster hosting ESS Pro. The Host header and the TLS SNI Client Hello name should both use the server name domain so that the cluster ingress controller can route the request appropriately. Alternatively TLS can be disabled on the server name Ingress with wellKnownDelegation.ingress.tlsEnabled: false and only the Host header needs to be set appropriately.

Hosting copies of the ESS Pro Well-Knowns elsewhere

The well-known JSON documents ESS Pro hosts are dynamically created based on the components in use and the configuration of ESS Pro. For this reason, serving them directly or proxying through to them (as above) is strongly recommended. In some situations this may not be possible and so an alternative is to have ESS Pro generate the files and you separately host copies on your server name domain.

The contents of the well known JSON documents can be fetched with:

# Adjust these as appropriate
ESS_NAMESPACE=ess
ESS_RELEASE_NAME=ess
# /.well-known/matrix/client
kubectl -n $ESS_NAMESPACE get cm $ESS_REELASE_NAME-well-known-haproxy -o jsonpath='{.data.client}' > matrix-client.json
# /.well-known/matrix/server
kubectl -n $ESS_NAMESPACE get cm $ESS_REELASE_NAME-well-known-haproxy -o jsonpath='{.data.server}' > matrix-server.json
# /.well-known/matrix/support
kubectl -n $ESS_NAMESPACE get cm $ESS_REELASE_NAME-well-known-haproxy -o jsonpath='{.data.support}' > matrix-support.json
# /.well-known/element/element.json
kubectl -n $ESS_NAMESPACE get cm $ESS_REELASE_NAME-well-known-haproxy -o jsonpath='{.data.element\.json}' > element.json

The web server that hosts your server name domain can then be updated to host & serve these files. All 4 files should be served with at least the following HTTP headers (other headers, e.g. a restrictive content-security-policy header, can optionally be added):

content-type: application/json
access-control-allow-origin: *
access-control-allow-methods: GET, POST, PUT, DELETE, OPTIONS
access-control-allow-headers: X-Requested-With, Content-Type, Authorization

Whenever the ESS Pro generated well-known JSON documents change, the external copies need to be updated. The contents of these documents can be generated by some other mechanism however they must contain at least the contents that the ESS Pro documents contain or parts of ESS Pro will not work. As per configuring well-known delegation arbitrary extra configuration can be added to the ESS Pro documents so that the complete well-known JSON documents can be maintained by ESS Pro.