{{- $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 "" }} 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 "" }} 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 }}//auth/callback where 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.