helm-charts/bulwark/templates/NOTES.txt

{{- $settings := fromYaml (include "bulwark.settings" .) -}}
{{- $replicas := int (include "bulwark.replicas" (dict "scaleDown" .Values.scaleDown "replicas" $settings.replicas)) -}}
{{- $sfs := printf "%s-%s-sfs" .Release.Name .Chart.Name -}}
{{- $svc := printf "%s-%s-service" .Release.Name .Chart.Name -}}
{{- $url := include "bulwark.publicUrl" . -}}
Bulwark Webmail {{ .Chart.AppVersion }} installed as release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.

{{ $replicas }} replica(s). This is a CLIENT: it holds no mail and has no database.
The messages and the accounts belong to the Stalwart server at
  {{ $settings.jmapServerUrl }}
If that server is away, this release is still Ready and still green - see
"WHAT THE PROBES DO NOT TELL YOU" below.

ENDPOINTS
{{ if .Values.ingress.enabled }}  Web:        {{ $url }}
{{ else }}  Web:        no Ingress (ingress.enabled: false) - in-cluster only
{{ end }}  In-cluster: http://{{ $svc }}.{{ .Release.Namespace }}.svc.cluster.local:{{ $settings.port | int64 }}
{{ if .Values.ingress.enabled }}  Admin:      {{ $url }}/admin/login
{{ else }}  Admin:      /admin/login on the in-cluster address above. With no Ingress, reach it with
                kubectl -n {{ .Release.Namespace }} port-forward statefulset/{{ $sfs }} 3000:{{ $settings.port | int64 }}
              and open http://localhost:3000/admin/login
{{ end }}{{ if .Values.ingress.enabled }}
  Bulwark is served at the ROOT of that host and cannot be moved under a path:
  NEXT_PUBLIC_BASE_PATH is compiled into the image.
{{ end }}
THE 1PASSWORD ITEMS, AND WHICH FIELDS THEY MUST CARRY
The operator materializes one Secret key per item FIELD. A missing or misnamed
field here does NOT stop the pod - the two file-form secrets simply read as
absent - so the symptom is a feature that is quietly off rather than an error.

  {{ .Values.secrets.appSecretRef | default "<secrets.appSecretRef NOT SET>" }}
    session-secret    openssl rand -base64 32
                      MANDATORY. Persistent sessions and the encryption of the
                      synchronized settings both hang on it, and the second
                      fails SILENTLY without it: settings sync is computed as
                      "enabled AND a secret exists", so with no secret it is
                      simply off and nothing says so.
    admin-password    the admin dashboard's initial password. CONSUMED ONCE -
                      see step 5 below.
{{ if $settings.oauth.enabled }}
  {{ .Values.secrets.oauthSecretRef | default "<secrets.oauthSecretRef NOT SET>" }}
    oauth-client-secret   the confidential OIDC client's secret, as issued by
                          the identity provider when the client was registered.
{{ else }}
  (no OAuth item - bulwark.oauth.enabled is false, so sign-in is by password)
{{ end }}
  The file-form secret{{ if $settings.oauth.enabled }}s are{{ else }} is{{ end }} mounted as a DIRECTORY, not with subPath, and
  re-read on every use - so rotating {{ if $settings.oauth.enabled }}either field{{ else }}that field{{ end }} in the vault takes effect
  WITHOUT a restart. admin-password is the exception and no restart helps it.

{{ if $settings.oauth.enabled }}
BEFORE YOU INSTALL - THE OIDC CLIENT HAS TO EXIST FIRST
{{ if $settings.oauth.only }}
  THIS IS NOT ADVICE AND IT IS NOT A FOLLOW-UP STEP. bulwark.oauth.only is ON,
  which means the password form is hidden, which means that WITHOUT A WORKING
  OIDC CLIENT THE FIRST SIGN-IN IS IMPOSSIBLE. There is no fallback for users.
{{ end }}
  Register a CONFIDENTIAL client with the provider at
    {{ $settings.oauth.issuerUrl }}
  client id:     {{ $settings.oauth.clientId }}
  secret:        into the vault item's oauth-client-secret field

  THE REDIRECT URI CARRIES THE UI LANGUAGE, AND THAT IS THE ONE THING THAT WILL
  COST YOU THE FIRST SIGN-IN IF YOU REGISTER A SINGLE URI. Bulwark builds it as
    {{ $url }}/<locale>/auth/callback
  where <locale> is the language the VISITOR'S BROWSER resolved to - so a German
  browser sends /de/auth/callback and an English one /en/auth/callback, from the
  same deployment. The language is not in the visible URL (the locale prefix is
  "never" in this image), which is exactly why this is surprising: the address
  bar shows no language and the redirect_uri contains one.

  Register ONE PER LANGUAGE YOU EXPECT, or a wildcard if the provider allows it.
  On Keycloak the wildcard is the practical answer:
    {{ $url }}/*
  Otherwise the 27 locales Bulwark supports are:
    ar ca cs da de en es fa fr he hu it ja ko lv mn nb nl pl pt ro ru sk tr uk
    zh zh-TW

  If a sign-in fails with a redirect_uri mismatch, read the URI out of the
  failed request rather than guessing which language it was - that is the value
  the provider compares byte for byte.

  POST-LOGOUT, IF YOU USE IT: bulwark.oauth.endSession is {{ $settings.oauth.endSession }}, and a
  post-logout redirect URI is only sent when OAUTH_POST_LOGOUT_REDIRECT_URI is
  set (this chart does not render it). If you add it through bulwark.env, it has
  to be registered with the provider too.

  The issuer must be reachable BY THE POD, and the endpoints it advertises must
  share the issuer's origin or be publicly routable - Bulwark rejects a
  discovered endpoint on a private address from a different origin. A
  split-horizon DNS setup needs OAUTH_ALLOW_PRIVATE_ENDPOINTS through
  bulwark.env; this chart does not render it.
{{ end }}
FIRST INSTALL

  1. kubectl -n {{ .Release.Namespace }} rollout status statefulset/{{ $sfs }}
     Ready means the HTTP server is accepting. It does NOT mean the mail server
     is reachable - nothing in this chart checks that.

  2. Confirm the setup wizard really is OFF. It is, as long as
     bulwark.jmapServerUrl is set, and the chart refuses to render without it -
     but this is the one thing worth seeing rather than trusting, because a
     wizard that ran once changes the rules for good (step 4):
       kubectl -n {{ .Release.Namespace }} logs statefulset/{{ $sfs }} | grep -i "SETUP REQUIRED"
     Nothing found is the correct result. A "SETUP REQUIRED" banner with a token
     means Bulwark is in bootstrap mode and something is wrong with the value.

  3. Sign in{{ if $settings.oauth.only }} through the identity provider{{ end }} at {{ $url }}

  4. READ THIS BEFORE YOU OPEN THE ADMIN DASHBOARD. The dashboard writes
     OVERRIDES into config.json on the volume, and an override BEATS this chart
     for that key - for good, and silently.

     Priority is: admin override  >  environment variable  >  default.

     So if you save a server URL in the dashboard, changing bulwark.jmapServerUrl
     and running helm upgrade afterwards does nothing and reports success. The
     same is true of every other key the dashboard can write. What the chart
     sets is a DEFAULT, not a setting.

     To see which keys are currently overridden:
       kubectl -n {{ .Release.Namespace }} exec {{ $sfs }}-0 -- cat /app/data/admin/config.json
     An empty object, or a file that does not exist, means this chart is in
     force.

  5. THE ADMIN PASSWORD IS CONSUMED EXACTLY ONCE. On the first start it is
     hashed into /app/data/admin/admin.json and the environment variable is
     never read again. Rotating the vault field afterwards has NO EFFECT -
     changing the password goes through the dashboard, or by deleting admin.json
     from the volume and restarting. Know that before you treat the vault field
     as the source of truth.

IF NOBODY CAN SIGN IN - THE WAY BACK, AND IT IS NOT A helm upgrade

  Read this now, not when it happens, because the obvious repair does not work.

  The situation: the identity provider is down, or its configuration is wrong,
  and bulwark.oauth.only hides the password form. No user can get in.

  WHAT DOES NOT WORK RELIABLY: helm upgrade with bulwark.oauth.only=false.
  oauthOnly is an ordinary config key, and every part of the app reads it
  through the priority chain above - not from the environment. If the admin
  dashboard's OAuth setup has ever been used, "oauthOnly": true is sitting in
  config.json on the volume, and from then on the chart's value is ignored. The
  upgrade succeeds and changes nothing.

  WHAT DOES WORK, and it does not depend on the identity provider:

    a) Open {{ $url }}/admin/login and sign in with the admin-password field
       from the vault item. This door has its own password and is not behind
       OIDC.{{ if eq $settings.stalwartAdminAccess "auto" }} (bulwark.stalwartAdminAccess is "auto", so a Stalwart
       admin also gets in here without that password.){{ end }}
    b) In the dashboard, REVERT the override - the dashboard's own "remove
       override" on the OAuth settings. That is what puts the chart's value back
       in charge.

  IF THE DASHBOARD ITSELF IS UNREACHABLE, the last resort is the volume:
    kubectl -n {{ .Release.Namespace }} exec {{ $sfs }}-0 -- cat /app/data/admin/config.json
    # remove the "oauthOnly" key (and any other override in the way), then
    kubectl -n {{ .Release.Namespace }} rollout restart statefulset/{{ $sfs }}
  Deleting admin.json in the same directory resets the admin password to
  whatever the vault field currently holds, on the next start.

WHAT THE PROBES DO NOT TELL YOU

  All three probes are a plain HTTP GET on /api/health, and that endpoint returns
  200 whatever state the application is in - for an unauthenticated caller the
  body even says "healthy" unconditionally. So a green pod here means: the
  process is alive, HTTP is being accepted, the event loop is free, and Next.js
  can route.

  IT SAYS NOTHING ABOUT THE MAIL SERVER. With Stalwart completely gone, this
  release is Ready, green, and serves a web app that cannot fetch a single
  message. Monitor the stalwart release for that - there is no endpoint here
  that could cover it, and the one that would (/api/setup/test-jmap) sits behind
  the setup token this chart disables.

  It also says nothing about the reported state: /api/health reports "degraded"
  on high V8 heap usage, but only to an authenticated caller asking for details,
  and always with HTTP 200. A memory limit set too low therefore produces a pod
  that is permanently degraded and permanently Ready.

BACKUPS - THE VOLUME ALONE IS NOT ONE, AND IT MAY NEED PROTECTING ITSELF

  Two statements, both of them about {{ .Release.Name }}-{{ .Chart.Name }}-pvc:

  1. A BACKUP OF THE VOLUME ALONE IS NOT A BACKUP.{{ if $settings.settingsSync }} The synchronized user
     settings on it are encrypted with session-secret.{{ else }} The user settings are not
     synchronized in this release, but persistent sessions still are.{{ end }} Lose the vault
     item and that data is unreadable out of a perfectly intact volume. Back up
     the 1Password item together with the volume, or the restore is a directory
     of ciphertext.

  2. A BACKUP OF THE VOLUME MAY CONTAIN A SECRET IN CLEARTEXT. If anybody has
     used the dashboard's OAuth setup, the OIDC client secret is written as
     PLAINTEXT into config.json on this volume. So the backup may need the same
     protection the vault gets. Check with:
       kubectl -n {{ .Release.Namespace }} exec {{ $sfs }}-0 -- grep -l oauthClientSecret /app/data/admin/config.json

TRAPS WORTH KNOWING BEFORE YOU NEED THEM

  - WEB PUSH GOES THROUGH THE VENDOR'S RELAY until somebody changes it, and the
    change is NOT a chart value. The built-in default is
    https://notifications.relay.bulwarkmail.org and it is compiled into the
    image. A self-hosted relay CAN be made the effective default and even
    mandatory for all users - through the settings policy in the admin
    dashboard, because that setting has no environment variable at all. So this
    is a choice you have, not a limitation you are stuck with; it just lives in
    the dashboard.

  - THERE IS NO ConfigMap IN THIS CHART, so no checksum/config annotation, and
    that is not an omission: there is no rendered config file whose change could
    fail to restart anything. Repointing secrets.* at a different vault item
    DOES roll the pod (checksum/secret-ref). Changing a value INSIDE an item
    does not - but for the two file-form secrets it does not need to, because
    they are re-read on every use.
{{ if $settings.adminConfigReadOnly }}
  - bulwark.adminConfigReadOnly IS ON. The chart is authoritative and no
    override can appear - and three things are frozen with it: the settings
    policy (so Web Push cannot be moved to your own relay any more), any
    override that was ALREADY on the volume (it cannot be removed either), and -
    if this release has never started with it off - the admin password, which
    means the admin dashboard never comes up and its login answers HTTP 500
    while this pod stays Ready.
    If you have just enabled this on a fresh install, turn it off, let the pod
    start once so admin.json is written, and only then turn it back on.
{{ else }}
  - bulwark.adminConfigReadOnly is OFF, which is the default and keeps the
    dashboard working. The cost is the precedence trap of step 4: the volume can
    override this chart at any time. Turning it on makes the chart authoritative
    but freezes the settings policy, freezes any override already present, and
    must never be the state of a FIRST install - see values.yaml for the
    sequence.
{{ end }}
  - THE SETTINGS POLICY, THE THEMES AND THE BRANDING ARE NOT IN THIS CHART.
    They live in policy.json on the volume and are set in the dashboard. This
    chart neither renders nor backs them up beyond the volume itself.

WHAT THIS CHART DOES NOT RENDER

  - No ConfigMap (see above) and no NetworkPolicy. The pod needs egress to the
    JMAP server and to the OIDC issuer; a policy added later has to allow both,
    or sign-in breaks in a way that looks like a provider outage.
  - No PodDisruptionBudget: with one replica a minAvailable of 1 would forbid
    every voluntary eviction and make `kubectl drain` hang forever on a pod
    nothing may move (README, guideline 11).
  - No sub-path Ingress, and no value that could add one - the base path is
    compiled into the image.
  - No proxy-body-size annotation. Attachment uploads go through the Ingress and
    nginx's default of 1m rejects larger ones with a 413 that reads like an
    application fault; the right number is the mail server's limit, which this
    chart does not know. Set it in ingress.annotations.