Skip to main content

Customize containers ran by ESS

Issue

  • In some deployments, you might want to customize the containers, because you want to add contents, change the web clients features, etc.

Environment

  • Element Server Suite (ESS) On-Premise

Resolution

The steps are:

  • Create a new configmap definition with the overrides you need to configure and inject it into the cluster.
  • Configure the installer to use the new Images Digests Config Map.
  • Generate secret for the registry (if it requires authentication) and add it to ESS.
Creating the new Images Digests Config Map

In order to override images used by ESS during the install, you will need to inject a new ConfigMap which specifies the image to use for each component. To do that, you will need to inject a ConfigMap. It's structure maps the components of the ESS, all of them can be overridden :

data:
  images_digests: |# Copyright 2023 New Vector Ltd
    adminbot:
      access_element_web:
      haproxy:
      pipe:
    auditbot:
      access_element_web:
      haproxy:
      pipe:
    element_call:
      element_call:
      sfu:
      jwt:
      redis:
    element_web:
      element_web:
    groupsync:
      groupsync:
    hookshot:
      hookshot:
    hydrogen:
      hydrogen:
    integrator:
      integrator:
      modular_widgets:
      appstore:
    irc_bridges:
      irc_bridges:
    jitsi:
      jicofo:
      jvb:
      prosody:
      web:
      sysctl:
      prometheus_exporter:
      haproxy:
      user_verification_service:
    matrix_authentication_service:
      init:
      matrix_authentication_service:
    secure_border_gateway:
      secure_border_gateway:
    sip_bridge:
      sip_bridge:
    skype_for_business_bridge:
      skype_for_business_bridge:
    sliding_sync:
      api:
      poller:
    sydent:
      sydent:
    sygnal:
      sygnal:
    synapse:
      haproxy:
      redis:
      synapse:
    synapse_admin:
      synapse_admin:
    telegram_bridge:
      telegram_bridge:
    well_known_delegation:
      well_known_delegation:
    xmpp_bridge:
      xmpp_bridge:

Each container on this tree needs at least the following properties to override the source of download :

image_repository_path: elementdeployment/vectorim/element-web
image_repository_server: localregistry.local

You can also override the image tag and the image digest if you want to enforce using digests in your deployment :

image_digest: sha256:ee01604ac0ec8ed4b56d96589976bd84b6eaca52e7a506de0444b15a363a6967
image_tag: v0.2.2

For example, the required configmap manifest (e.g. images_digest_configmap.yml) format would be, to override the element_web/element_web container source path :

apiVersion: v1
kind: ConfigMap
metadata:
  name: <config map name>
  namespace: <namespace of your deployment>
data:
  images_digests: |
    element_web:
      element_web:
        image_repository_path: mycompany/custom-element-web
        image_repository_server: docker.io
        image_tag: v2.1.1-patched

Notes:

  • the image_digest: may need to be regenerated, or it can be removed.
  • The image_repository_path needs to reflect the path in your local repository.
  • The image_repository_server should be replaced with your local repository URL

The new ConfigMap can then be injected into the cluster with:

kubectl apply -f images_digest_configmap.yml -n <namespace of your deployment>

You will also need to configure the ESS Installer to use the new Images Digests Config Map by adding the <config map name> into the Cluster advanced section.

If your registry requires authentication, you will need to create a new secret. So for example, if your registry is called myregistry and the URL of the registry is myregistry.tld, the command would be:

kubectl create secret docker-registry myregistry --docker-username=<registry user> --docker-password=<registry password> --docker-server=myregistry.tld -n <your namespace>

The new secret can then be added into the ESS Installer GUI advanced cluster Docker Secrets:

Handling new releases of ESS

If you are overriding image, you will need to make sure that your images are compatbile with the new releases of ESS. You can use a staging environment to tests the upgrades for example.

Back to top