Skip to content

Configuring Synapse

See how to download example files from the helm chart here.

Configuration

For a quick setup using the default settings, see the minimal fragment example in charts/matrix-stack/ci/fragments/synapse-minimal.yaml.

Configuring a PostgreSQL database

If you want to use an external PostgreSQL, see the following fragments examples:

  • charts/matrix-stack/ci/fragments/synapse-postgres.yaml
  • charts/matrix-stack/ci/fragments/synapse-postgres-secrets-in-helm.yaml or charts/matrix-stack/ci/fragments/synapse-postgres-secrets-externally.yaml

Credentials

Credentials are generated if possible. Alternatively they can either be provided inline in the values with value or if you have an existing Secret in the cluster in the same namespace you can use secret andsecretKey to reference it.

If you don't want the chart to generate the secret, please refer to the following values fragments examples to see the secrets to configure.

Synapse requires registrationSharedSecret, signingKey and macaroon secrets:

  • charts/matrix-stack/ci/fragments/synapse-secrets-in-helm.yaml
  • charts/matrix-stack/ci/fragments/synapse-secrets-externally.yaml

If you are configuring S3 storage, see the following values fragments examples to see the secrets to configure:

  • charts/matrix-stack/ci/fragments/synapse-s3-secrets-in-helm.yaml
  • charts/matrix-stack/ci/fragments/synapse-s3-secrets-externally.yaml

Additional configuration

Additional Synapse configuration can be provided inline in the values as a string with

synapse:
  additional:
    ## Either reference config to inject by:
    1-custom-config:
      config: |
        admin_contact: "mailto:admin@example.com"
    ## Either reference an existing `Secret` by:
    2-custom-config:
      configSecret: custom-synapse-config
      configSecretKey: shared.yaml

Multi-Tenancy

Synapse can be configured to be deployed as a tenant of a Synapse Shards Cluster. The following applies when deploying Synapse as a tenant:

Note: Because the Shards controller will manage tenants and shards in a single namespace, you will need to deploy multiple ESS Pro instances in the same namespace as the synapse-shards cluster to profit of the sharding feature.

To deploy Synapse as a tenant of a Synapse Shards, you need to provide the following values:

synapse:
  asTenantHook:
    enabled: true
    clusterId: # the synapse-shards cluster id
    # namespace: # the synapse-shards cluster namespace, if deployed in cluster scope

If during this ESS lifecycle, you need to scale the Synapse instance to a dedicated process and deploy workers, simply disable the synapse.asTenantHook.enabled value. Synapse tenant will be disabled, its workloads will be deployed and managed by the matrix-stack chart.

synapse:
  asTenantHook:
    enabled: false

Note: Multi-Tenancy is still in active development, and is released as a preview feature. For now, you will have to delete the generated secret named <release name>-synapse-tenant and restart the shards to disable the configured tenant when doing so.

Workers

Workers are not compatible with Multi-Tenancy.

The following Synapse workers are disabled by default and can be enabled on a per-worker basis:

  • appservice
  • background
  • client-reader
  • encryption
  • event-creator
  • event-persister
  • federation-sender
  • initial-synchrotron
  • media-repository
  • presence-writer
  • pusher
  • receipts-account
  • sliding-sync
  • sso-login
  • synchrotron
  • typing-persister
  • user-dir

Synapse workers can be configured in the values with:

synapse:
  workers:
    <worker name>:
      enabled: true

Each worker comes with a different options (static replicas, horizontal scaling, resources, etc). These options can be seen under synapse.workers.<name> section of helm show values for this chart.

The following Synapse pro workers are enabled by default:

  • federation-reader

They can be disabled in the values with:

synapse:
  workers:
    <worker name>:
      enabled: false

Full details on available configuration options can be found at https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html

S3 Configuration Parameters

ESS Pro supports using S3-compatible object storage for media repository.

If you are using AWS S3, you will need to inject AWS CA certificates into the chart using certificateAuthorities values.

When using S3 Storage, Synapse will still store media locally. A sidecar container is running to cleanup the media on a regular basis. The cleanup job will run every 10 minutes by default, and remove local media not used in the last hour. You can change the frequency of the cleanup job by setting the frequency value in the localCleanup section.

synapse:
  media:
    s3:
      endpoint: https://s3.example.com  # S3-compatible storage endpoint
      region: us-east-1  # AWS region or equivalent. Comment out if your S3 provider does not use any region.
      bucket: synapse-media  # Bucket name for media storage
      ## S3 Secret Access Key.
      ## It can either be provided inline in the Helm chart e.g.:
      ## secretAccessKey:
      ##   value: SecretValue
      ##
      ## Or it can be provided via an existing Secret e.g.:
      ## secretAccessKey:
      ##   secret: existing-secret
      ##   secretKey: key-in-secret
      secretAccessKey: {}
      ## S3 Access Key Id.
      ## It can either be provided inline in the Helm chart e.g.:
      ## accessKeyId:
      ##   value: SecretValue
      ##
      ## Or it can be provided via an existing Secret e.g.:
      ## accessKeyId:
      ##   secret: existing-secret
      ##   secretKey: key-in-secret
      accessKeyId: {}
      localCleanup:
        # How often to run the cleanup job
        frequency: "600s"
        # At what threshold to consider locally cached media old enough to delete from local storage
        # `m` here unfortunately means months, do not use. Use s / h / d
        threshold: "1h"

Disabling Synapse

Synapse is enabled for deployment by default can be disabled with the following values

synapse:
  enabled: false