Install with Helm

The recommended way to install Vesicle is the Helm chart published to Google Artifact Registry.

Release artifacts are immutable SemVer tags (for example 0.0.1-rc.1). Staging still uses Harbor chart 0.0.1-dev plus digest pins; that channel is not the public install path.

The published chart name is vesicle.

Prerequisites

Kubernetes 1.30 or later
Helm 3.8 or later (OCI registry support)
kubectl configured for the target cluster
An ingress controller. The examples below use Traefik with Gateway API
DNS for the Matrix server_name and satellite hostnames

Public charts and first-party images are on Google Artifact Registry (europe-west3-docker.pkg.dev/vesicle) and can be pulled without a GCP login.

Pull the chart (optional)

helm pull oci://europe-west3-docker.pkg.dev/vesicle/charts/vesicle --version 0.0.1-rc.1

Values overlay

Create my-values.yaml. Replace matrix.example.com with your Matrix server_name, and point parentRefs at your Gateway.

Do not copy production secrets from an existing cluster into this file. Generate your own passwords, MAS client credentials, and Matrix RTC secret.

First-party images default to europe-west3-docker.pkg.dev/vesicle/vesicle/vesicle-* at the chart appVersion. Leave global.images.registry unset unless you use a private mirror.

global:
  serverName: matrix.example.com

gateway:
  route:
    enabled: true
    parentRefs:
      - name: traefik-gateway
        namespace: kube-system

matrix-authentication-service:
  ingress:
    enabled: false
  route:
    enabled: true
    parentRefs:
      - name: traefik-gateway
        namespace: kube-system

elementWeb:
  enabled: true
  route:
    enabled: true
    parentRefs:
      - name: traefik-gateway
        namespace: kube-system

elementAdmin:
  enabled: true
  route:
    enabled: true
    parentRefs:
      - name: traefik-gateway
        namespace: kube-system

matrixRTC:
  enabled: true
  route:
    enabled: true
    parentRefs:
      - name: traefik-gateway
        namespace: kube-system

postgresql:
  enabled: true

nats:
  enabled: true

When route or ingress hosts are left empty, the chart derives them from global.serverName:

Role	Hostname
Homeserver / federation	`matrix.example.com`
Matrix Authentication Service	`account.matrix.example.com`
Element Web	`chat.matrix.example.com`
Element Admin	`admin.matrix.example.com`
Matrix RTC	`mrtc.matrix.example.com`

See DNS and hostnames and Ingress.

Install

helm install vesicle oci://europe-west3-docker.pkg.dev/vesicle/charts/vesicle \
  --version 0.0.1-rc.1 \
  --namespace vesicle \
  --create-namespace \
  -f my-values.yaml

Upgrade later with the same chart reference:

helm upgrade vesicle oci://europe-west3-docker.pkg.dev/vesicle/charts/vesicle \
  --version 0.0.1-rc.1 \
  --namespace vesicle \
  -f my-values.yaml

First-party images

Release installs pull first-party images from Artifact Registry (vesicle/vesicle-gateway, vesicle/vesicle-client-api, vesicle/vesicle-fed-api, vesicle/vesicle-auth) at europe-west3-docker.pkg.dev/vesicle. Third-party images (Element Web, PostgreSQL, NATS, Matrix Authentication Service) stay on their upstream registries unless you set a mirror.

Override global.images.registry and per-component image.registry when you use a private mirror such as Harbor.

After install

Confirm DNS and TLS for every hostname in the table above.
Open https://chat.<serverName>/ for Element Web. Browser GET / on the homeserver host redirects there; /_matrix, /_synapse, and /.well-known stay on the gateway.
Change default database and MAS credentials before exposing the install.

A full install in the vesicle namespace typically shows two replicas of each first-party service (Gateway, Client API, Federation API, Auth), plus platform and add-on pods:

kubectl -n vesicle get pods
NAME                                           READY   STATUS    RESTARTS   AGE
vesicle-auth-…                                 1/1     Running   0          …
vesicle-auth-…                                 1/1     Running   0          …
vesicle-client-api-…                           1/1     Running   0          …
vesicle-client-api-…                           1/1     Running   0          …
vesicle-element-admin-…                        1/1     Running   0          …
vesicle-element-web-…                          1/1     Running   0          …
vesicle-fed-api-…                              1/1     Running   0          …
vesicle-fed-api-…                              1/1     Running   0          …
vesicle-gateway-…                              1/1     Running   0          …
vesicle-gateway-…                              1/1     Running   0          …
vesicle-matrix-authentication-service-…        1/1     Running   0          …
vesicle-matrix-rtc-authorisation-…             1/1     Running   0          …
vesicle-matrix-rtc-sfu-…                       1/1     Running   0          …
vesicle-nats-0                                 2/2     Running   0          …
vesicle-nats-box-…                             1/1     Running   0          …
vesicle-postgresql-0                           1/1     Running   0          …

How traffic reaches those pods, and which of them you scale independently, is on Architecture.