{"id":25735971,"url":"https://github.com/small-hack/matrix-chart","last_synced_at":"2026-01-12T13:58:36.697Z","repository":{"id":182797046,"uuid":"668609997","full_name":"small-hack/matrix-chart","owner":"small-hack","description":"Helm chart for deploying a Matrix homeserver stack","archived":false,"fork":false,"pushed_at":"2024-05-22T21:34:34.000Z","size":2429,"stargazers_count":6,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-23T00:14:26.314Z","etag":null,"topics":["element","helm","matrix","synapse"],"latest_commit_sha":null,"homepage":"https://small-hack.github.io/matrix-chart/","language":"Smarty","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"Arkaniad/matrix-chart","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/small-hack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-20T07:56:13.000Z","updated_at":"2024-05-27T11:58:25.140Z","dependencies_parsed_at":"2024-04-09T12:39:14.114Z","dependency_job_id":"337e21a8-3282-421d-88f7-3e2a21e06dd8","html_url":"https://github.com/small-hack/matrix-chart","commit_stats":null,"previous_names":["jessebot/matrix-chart","small-hack/matrix-chart"],"tags_count":83,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/small-hack%2Fmatrix-chart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/small-hack%2Fmatrix-chart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/small-hack%2Fmatrix-chart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/small-hack%2Fmatrix-chart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/small-hack","download_url":"https://codeload.github.com/small-hack/matrix-chart/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240800730,"owners_count":19859725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["element","helm","matrix","synapse"],"created_at":"2025-02-26T05:34:46.955Z","updated_at":"2026-01-12T13:58:36.602Z","avatar_url":"https://github.com/small-hack.png","language":"Smarty","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Matrix Chart\n\u003ca href=\"https://github.com/small-hack/matrix-chart/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/small-hack/matrix-chart?style=plastic\u0026labelColor=blue\u0026color=green\u0026logo=GitHub\u0026logoColor=white\"\u003e\u003c/a\u003e\n\nA Helm chart for deploying a Matrix homeserver stack on Kubernetes.\n\n## TLDR\n\nSee the [`README.md`](https://github.com/small-hack/matrix-chart/blob/main/charts/matrix/README.md) for docs auto-generated from the [`values.yaml`](https://github.com/small-hack/matrix-chart/blob/main/charts/matrix/values.yaml).\n\nRead through the parameters and modify them locally before installing the chart:\n\n```bash\n# add the helm repo locally\nhelm repo add matrix https://small-hack.github.io/matrix-chart\n\n# downloads the values.yaml locally\nhelm show values matrix/matrix \u003e values.yaml\n\n# You should then edit the values.yaml to your liking.\n\n## NOTE: The most important helm parameter is matrix.hostname\n## without it, this chart may not work!\n\n# install the chart\nhelm install my-release-name matrix/matrix --values values.yaml\n```\n\n\u003e [!IMPORTANT]\n\u003e The most important helm parameter is `matrix.hostname`. Without it, this chart may not work!**\n\n\u003e [!WARNING]\n\u003e This chart used to support the Sliding Sync Proxy, but as it is deprecated, we no longer support it. See this [matrix blog post](https://matrix.org/blog/2024/11/14/moving-to-native-sliding-sync/) for more info.\n\n\n## Current Features ✨\n\n- Latest version of [Synapse](https://github.com/element-hq/synapse) (the official matrix homeserver)\n- Ingress definitions for federated Synapse (aka Matrix homeserver) and Element (default client for matrix)\n\n### Optional Features\n\n- Use existing Persistent Volume Claims\n- Use existing Kubernetes Secrets for confidential data, such as passwords\n- Use OIDC configs for SSO either directly via Synapse (see [docs](https://github.com/element-hq/synapse/blob/develop/docs/openid.md) for more info) or via MAS\n  - Use MAS ([matrix-org/matrix-authentication-service](https://github.com/matrix-org/matrix-authentication-service)) via [matrix-authentication-service-chart](https://github.com/small-hack/matrix-authentication-service-chart) as a sub chart for using [element-x] which recommends  for OIDC auth\n- Latest version of the [Element web app](https://element.io/) to provide a web interface for chat (you can disable this and still use element apps)\n- Use s3 to store media using [element-hq/synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider/tree/main)\n- [small-hack/matrix-alertmanager](https://github.com/small-hack/matrix-alertmanager) - Prometheus Alertmanager bridge for syncing between matrix and Alertmanager\n\n#### ⚠️ Untested Features\n\nThese features still need to be tested, but are technically baked into the chart from the fork or from previous versions of this chart:\n\n- [mautrix/discord](https://github.com/mautrix/discord) - Discord bridge for syncing between matrix and Discord (we no longer test this directly but we're open to PRs to improve support!)\n- [Coturn TURN server subchart](https://github.com/small-hack/coturn-chart) for VoIP calls (may not be needed in Matrix 2.0 API)\n- Use of lightweight Exim relay\n- [matrix-org/matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) IRC bridge\n- [tulir/mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp) WhatsApp bridge (we may deprecate this feature in the future, as to not support Big Tech)\n\n# Notes\n\n* [Databases](#databases)\n* [Ingress](#ingress)\n* [Federation](#federation)\n    * [Federation not Working](#federation-not-working)\n    * [Addiing Trusted Key Servers from an existing Secret](#addiing-trusted-key-servers-from-an-existing-secret)\n* [Notes on using MAS (Matrix Authentication Service)](#notes-on-using-mas-matrix-authentication-service)\n* [Bridges](#bridges)\n    * [Alertmanager](#alertmanager)\n    * [Discord](#discord)\n* [About and Status](#about-and-status)\n\n\n## Databases\n\nYou must select one of the following options:\n\n- Use the [Bitnami PostgreSQL subchart](https://github.com/bitnami/charts/tree/main/bitnami/postgresql) (set `postgresql.enabled` to `true`)\n- Use your own external database, which can also be PostgreSQL. (set `externalDatabase.enabled` to `true`)\n\n\u003e [!NOTE]\n\u003e\n\u003e You cannot enable both `externalDatabase` and `postgresql`. You must select _one_.\n\n## Ingress\n\nA previous version of this chart supported using the `synapse.ingress.host` parameter. This option has been removed. You must now set a `synapse.ingress.hosts`. Because of this, you must now also set `matrix.hostname` or certain functionality will not work. Example of how to setup ingress and hostname:\n\n```yaml\nmatrix:\n  # used for setting up config files that require your homeserver hostname\n  # such as bridging between your matrix homeserver (synapse) and other services\n  # such as discord or WhatsApp\n  hostname: my-synapse-hostname.com\n\nsynapse:\n  ingress:\n    className: \"nginx\"\n    annotations:\n      # required for TLS certs issued by cert-manager\n      cert-manager.io/cluster-issuer: letsencrypt-staging\n\n      # -- This annotation is required for the Nginx ingress provider. You can\n      # remove it if you use a different ingress provider\n      nginx.ingress.kubernetes.io/configuration-snippet: |\n        proxy_intercept_errors off;\n\n    hosts:\n      - host: \"my-synapse-hostname.com\"\n        paths:\n          - path: /\n            pathType: ImplementationSpecific\n            # if mas.enabled is set to true, you want pathType for / to be Prefix\n            # pathType: Prefix\n\n          # if mas.enabled is set to true, you want to uncomment the following:\n          # - path: \"/_matrix/client/(r0|v3)/(refresh|login|logout).*\"\n          #   pathType: ImplementationSpecific\n          #   backend:\n          #     service:\n          #       value: release-name-mas\n          #       port:\n          #         name: http\n    # -- enable tls for synapse ingress\n    tls:\n      - secretName: \"matrix-tls\"\n        hosts:\n          - my-synapse-hostname\n```\n\n## Federation\n\n### Federation not Working\n\nThis can be broken for a number of reasons, and some of them are listed in the official [synapse docs](https://element-hq.github.io/synapse/latest/federate.html#setting-up-federation), but one that was persistent for the devs here was constantly getting a 401 when testing.\n\nI managed to finally get past that by adding the following to my values.yaml:\n\n```yaml\nmatrix:\n  hostname: my-synapse-hostname.com\n  federation:\n    enabled: true\n\nsynapse:\n  ingress:\n    # replace matrix.mydomain.com with your actual matrix domain\n    nginx.ingress.kubernetes.io/configuration-snippet: |\n      location /.well-known/matrix/server {\n        return 200 '{\"m.server\": \"matrix.mydomain.com:443\"}';\n        add_header Content-Type application/json;\n      }\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e By the way, you can test by going to `https://federationtester.matrix.org/api/report?server_name=matrix.mydomain.com` where `matrix.mydomain.com` is replaced by your synapse server.\n\nLater on, I realized I could also use [`serve_server_wellknown`](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#serve_server_wellknown) in the synapse config, so I've added it to the Chart's parameters and you can use it like this in your values.yaml:\n\n```yaml\nmatrix:\n  hostname: my-synapse-hostname.com\n  federation:\n    enabled: true\n  serve_server_wellknown: true\n```\n\n### Addiing Trusted Key Servers from an existing Secret\n\nIf you'd like to get your [`trusted_key_servers`](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#trusted_key_servers) from an existing Kubernetes Secret, you can do so with an in-line yaml block. Here's an example values.yaml:\n\n```yaml\nmatrix:\n  hostname: my-synapse-hostname.com\n  federation:\n    enabled: true\n  security:\n    trustedKeyServersExistingSecret: \"trusted-key-servers\"\n    trustedKeyServersSecretKey: \"trustedKeyServers\"\n```\n\nHere's an example Kubernetes Secret using in-line YAML (NOTE the `trusted_key_servers`):\n\n```yaml\napiVersion: v1\nkind: Secret\nmetadata:\n  name: trusted-key-servers\n  namespace: matrix\ntype: Opaque\nstringData:\n  # friend.com is the matrix server you'd like to federate with :)\n  trustedKeyServers: |-\n    trusted_key_servers:\n      - server_name: friend.com\n        verify_keys:\n          ed25519:auto: abcdefghijklmnopqrstuvwxyz1234567890\n```\n\n## Notes on using MAS (Matrix Authentication Service)\n\nMAS is currently the only way to use OIDC with [element-x]. If you're using MAS (Matrix Authentication Service), you'll need to set `mas.enabled` to `true`. You'll also need to setup proper routes for synapse to redirect to MAS. See example below:\n\n```yaml\nmatrix:\n  hostname: my-synapse-hostname.com\n  experimental_features:\n    msc3861:\n      # Likely needed if using OIDC on synapse and you want to allow usage of Element-X (the beta of element)\n      enabled: true\n      # -- Synapse will call `{issuer}/.well-known/openid-configuration` to get the OIDC configuration\n      issuer: http://my-mas-domain.com/\n      # -- Matches the `mas.mas.client_id` in the auth service config\n      client_id: 0000000000000000000SYNAPSE\n      # -- Matches the `mas.mas.client_auth_method` in the auth service config\n      client_auth_method: client_secret_basic\n      # -- Matches the `mas.mas.clients.client_secret` in the auth service config\n      client_secret: \"SomeRandomSecret\"\n      # -- Matches the `mas.mas.matrix.secret` in the auth service config\n      admin_token: \"special-secret-for-msc3861\"\n      # -- URL to advertise to clients where users can self-manage their account\n      account_management_url: \"https://my-mas-domain.com/account\"\n\nsynapse:\n  enabled: true\n  ingress:\n    enabled: true\n    className: \"nginx\"\n    annotations:\n      # you need for the routing to work properly\n      nginx.ingress.kubernetes.io/use-regex: \"true\"\n      # -- This annotation is required for the Nginx ingress provider. You can\n      # remove it if you use a different ingress provider\n      nginx.ingress.kubernetes.io/configuration-snippet: |\n        proxy_intercept_errors off;\n      # -- required for TLS certs issued by cert-manager\n      cert-manager.io/cluster-issuer: letsencrypt-staging\n    hosts:\n      - host: 'my-synapse-hostname.com'\n        paths:\n          - path: \"/_matrix/client/(r0|v3)/(refresh|login|logout).*\"\n            pathType: ImplementationSpecific\n            backend:\n              service:\n                # this assumes you passed in mas.fullnameOverride=\"mas\"\n                name: mas\n                port:\n                  name: http\n\n          - path: /\n            pathType: Prefix\n    tls:\n      - secretName: matrix-tls\n        hosts:\n          - 'my-synapse-hostname.com'\n\nmas:\n  enabled: true\n  # sets all MAS resources to be called mas\n  fullnameOverride: \"mas\"\n  postgresql:\n    enabled: true\n\n  ingress:\n    enabled: true\n    className: \"nginx\"\n    annotations:\n      cert-manager.io/cluster-issuer: 'letsencrypt-prod'\n    hosts:\n      - host: 'my-mas-domain.com'\n        paths:\n          - path: /\n            pathType: Prefix\n    tls:\n      - secretName: matrix-authentication-service-tls\n        hosts:\n          - 'my-mas-domain.com'\n\n  # templates out the Matrix Authentication Service config file\n  mas:\n    database:\n      # if blank, this can be autogenerated from mas.postgres or mas.externalDatabase\n      # settings, or you set this to a valid postgres URI\n      # https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS\n      uri: \"\"\n\n    http:\n      # -- Public URL base used when building absolute public URLs\n      public_base: \"https://my-mas-domain.com/\"\n      # List of HTTP listeners, see below\n      listeners:\n        # The name of the listener, used in logs and metrics\n        - name: web\n          # List of resources to serve\n          resources:\n            - name: discovery\n            - name: human\n            - name: oauth\n            - name: compat\n            - name: graphql\n            - name: assets\n          binds:\n            - host: 0.0.0.0\n              port: 8080\n\n    policy:\n      client_registration:\n        # don't require URIs to be on the same host. default: false\n        allow_host_mismatch: true\n        # allow non-SSL and localhost URIs. default: false\n        allow_insecure_uris: true\n\n    # this is mostly ignored in favor of the above masClientSecret variable\n    clients:\n      - client_id: \"0000000000000000000SYNAPSE\"\n        client_auth_method: client_secret_basic\n        client_secret: \"SomeRandomSecret\"\n\n    matrix:\n      homeserver: \"my-synapse-hostname.com\"\n      endpoint: \"https://my-synapse-hostname.com\"\n      secret: \"special-secret-for-msc3861\"\n\n    upstream_oauth2:\n      existingSecret: \"synapse-oidc\"\n      secretKeys:\n        # -- key in secret with the issuer\n        issuer: \"issuer\"\n        # -- key in secret with the client_id\n        client_id: \"client_id\"\n        # -- key in secret with the client_secret\n        client_secret: \"client_secret\"\n\n      # this below example is compatible with zitadel\n      providers:\n        # -- A unique identifier (ULID) for the provider: https://www.ulidtools.com\n        # in the valid redirect uris, you want to use this id\n        - id: \"01HYZ2G7QS9P2BHSDS94F3GR80\"\n          issuer: https://example-zitadel-domain.com/\n          client_id: \"idgenreatedbyyourupstreamoidcprovider\"\n          client_secret: \"secretgenreatedbyyourupstreamoidcprovider\"\n\n          token_endpoint_auth_method: client_secret_basic\n          claims_imports:\n            subject:\n              template: \"{{ user.sub }}\"\n\n            localpart:\n              action: require\n              template: \"{{ user.preferred_username }}\"\n\n            displayname:\n              action: suggest\n              template: \"{{ user.name }}\"\n\n            email:\n              action: suggest\n              template: \"{{ user.email }}\"\n              set_email_verification: always\n```\n\n## Bridges\n\nWe've only recently started adding/testing [bridges](https://matrix.org/ecosystem/bridges/) to this stack, so there may be some bugs, but so far, we've got the discord bridge upgraded. The rest of the bridges are in a beta/alpha state and although we want to support them, we haven't had the time to test them out since the major fork. If you find something wrong with them, please feel free to submit an Issue or Pull Request.\n\nSo far we've tested and gotten working two bots/bridges: Alertmanager and Discord. We wanted to get hookshot working, but try as we might, we could never get the bot to respond to queries in a matrix chat.\n\n### Alertmanager\n\nCheck out the [upstream repo](https://github.com/small-hack/matrix-alertmanager) for more info (especially [`.env.default`](https://github.com/small-hack/matrix-alertmanager/blob/main/.env.default)), but here's the gist for configuring it via this chart.\n\n```yaml\nbridges:\n  alertmanager:\n    enabled: false\n\n    existingSecret:\n      # -- optional secret to replace the entire registration.yaml\n      registration: \"\"\n\n    # this section is for registering the application service with matrix\n    # read more about application services here:\n    # https://spec.matrix.org/v1.11/application-service-api/\n    registration:\n      # -- url of the alertmanager service. if not provided, we will template it\n      # for you like http://matrix-alertmanager-service:3000\n      url: \"\"\n      # A secret token that the application service will use to authenticate\n      # requests to the homeserver.\n      as_token: \"\"\n      # -- Use an existing Kubernetes Secret to store your own generated appservice\n      # and homeserver tokens. If this is not set, we'll generate them for you.\n      # Setting this won't override the ENTIRE registration.yaml we generate for\n      # the synapse pod to authenticate mautrix/discord. It will only replaces the tokens.\n      # To replaces the ENTIRE registration.yaml, use\n      # bridges.alertmanager.existingSecret.registration\n      existingSecret: \"\"\n      existingSecretKeys:\n        # -- key in existingSecret for as_token (application service token). If\n        # provided and existingSecret is set, ignores bridges.alertmanager.registration.as_token\n        as_token: \"as_token\"\n        # -- key in existingSecret for hs_token (home server token)\n        hs_token: \"hs_token\"\n\n    encryption: false\n\n    config:\n      # -- secret key for the alertmanager webhook config URL\n      app_alertmanager_secret: \"\"\n      # -- your homeserver url, e.g. https://homeserver.tld\n      homeserver_url: \"\"\n\n      bot:\n        # -- optional: display name to set for the bot user\n        display_name: \"\"\n        # -- optional: mxc:// avatar to set for the bot user\n        avatar_url: \"\"\n        # -- rooms to send alerts to, separated by a |\n        # Each entry contains the receiver name (from alertmanager) and the\n        # internal id (not the public alias) of the Matrix channel to forward to.\n        # example: reciever1/!789fhdsauoh48:mymatrix.hostname.com\n        rooms: \"\"\n        # -- Set this to true to make firing alerts do a `@room` mention.\n        # NOTE! Bot should also have enough power in the room for this to be useful.\n        mention_room: false\n\n      # -- set to enable Grafana links, e.g. https://grafana.example.com\n      grafana_url: \"\"\n      # -- grafana data source, e.g. default\n      grafana_datasource: \"\"\n      # -- set to enable silence link, e.g. https://alertmanager.example.com\n      alertmanager_url: \"\"\n```\n\n### Discord\n\nWe previously had the halfshot/discord bridge as a part of this stack, but as of July 2024 the image was no longer being updated and hadn't been updated in 3 years, see: [#589](https://github.com/small-hack/matrix-chart/issues/589) for more info. Instead we now offer the [mautrix/discord](https://github.com/mautrix/discord) bridge. You can read their docs [here](https://docs.mau.fi/bridges/go/discord/index.html).\n\nHere's how we got it mostly working on our end via the values.yaml:\n\n```yaml\nmatrix:\n  hostname: my-synapse-hostname.com\n\nbridges:\n  discord_mautrix:\n    enabled: true\n    # this just keeps the replicasets from getting\n    # out of control, feel free to set to 10 to\n    # keep more history for rollbacks\n    revisionHistoryLimit: 1\n\n    # -- extra volumes for the mautrix/discord deployment\n    # we created this separately from the chart\n    extraVolumes:\n      - name: sqllite\n        persistentVolumeClaim:\n          claimName: mautrix-discord-bridge-sqlite\n\n    extraVolumeMounts:\n      - name: sqllite\n        mountPath: /sql\n\n    admin_users:\n      - friend\n      - admin\n\n    config:\n      # Homeserver details\n      homeserver:\n        address: \"https://my-synapse-hostname.com\"\n        domain: \"my-synapse-hostname.com\"\n\n      appservice:\n        # Database config - we used sqllite because it's easy\n        database:\n          type: sqlite3-fk-wal\n          uri: file:/sql/mautrixdiscord.db?_txlock=immediate\n\n      bridge:\n        encryption:\n          # -- Allow encryption, work in group chat rooms with e2ee enabled\n          allow: true\n          # -- Default to encryption, force-enable encryption in all portals the bridge creates\n          # This will cause the bridge bot to be in private chats for the encryption to work properly.\n          default: true\n```\n\nExample PVC for the sqllite file to persist:\n\n```yaml\napiVersion: v1\nkind: PersistentVolumeClaim\nmetadata:\n  name: mautrix-discord-bridge-sqlite\n  namespace: matrix\nspec:\n  accessModes:\n    - ReadWriteOnce\n  resources:\n    requests:\n      storage: 2Gi\n  storageClassName: local-path\n```\n\nAfter you set this up, you'll still need to authenticate the matrix bot (mautrix/discord) with your Discord bot. For that, you'll need to follow the instructions in the [mautrix discord docs](https://docs.mau.fi/bridges/go/discord/authentication.html).\n\n\n## About and Status\n\nThis is a fork of [Arkaniad/matrix-chart](https://github.com/Arkaniad/matrix-chart), which is a fork of [typokign/matrix-chart](https://github.com/typokign/matrix-chart). We recently transferred this chart from [@jessebot](https://github.com/jessebot) to the [small-hack](https://github.com/small-hack) org to help with maintanence longterm :) Working on full stability, but always happy to receive GitHub Issues or PRs! Please star the repo if you like our work 💙\n\nOur goal is to provide regular updates using renovatebot and provide some level of basic security from a k8s perspective. We're also trying to standardize the chart more by following predictable values.yaml patterns.\n\n\u003c!-- links --\u003e\n[element-x]: https://element.io/labs/element-x \"element x link\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmall-hack%2Fmatrix-chart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmall-hack%2Fmatrix-chart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmall-hack%2Fmatrix-chart/lists"}