helm-charts/outline/templates/NOTES.txt

{{- $replicas := include "outline.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.outline.replicas) -}}
{{- $startup := fromYaml (include "outline.startupProbe" .Values.outline.startupProbe) -}}
{{- $upload := .Values.outline.maxUploadSize | toString -}}
{{- $httpRoute := .Values.httpRoute | default dict -}}
{{- $hostnames := $httpRoute.hostnames | default list -}}
{{- if not $hostnames -}}
{{- $hostnames = list .Values.ingress.domain -}}
{{- end -}}
Outline {{ .Chart.AppVersion }} — release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.

{{- if .Values.ingress.enabled }}

ACCESS — INGRESS MODE (ingress.enabled: true, httpRoute.enabled: false)
  https://{{ .Values.ingress.domain }}

  The certificate is requested by cert-manager through the "{{ .Values.ingress.clusterIssuer }}"
  cluster issuer. Until it has been issued the browser shows a warning; follow it with

    kubectl -n {{ .Release.Namespace }} get certificate tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress
{{- else if $httpRoute.enabled }}

ACCESS — GATEWAY MODE (httpRoute.enabled: true, ingress.enabled: false)
{{- range $hostnames }}
  https://{{ . }}
{{- end }}

  This release renders an HTTPRoute ({{ .Release.Name }}-{{ .Chart.Name }}-httproute) and NOTHING
  else of the routing path — no Gateway, no class, no Certificate. Three things
  therefore belong to the cluster and not to this chart, and if any is missing
  the address above does not answer:

    1. The Gateway-API CRDs. Without them this install would have failed.
    2. The Gateway named in httpRoute.parentRefs
{{- range $httpRoute.parentRefs }}
         {{ .name }}{{ if .namespace }} in namespace {{ .namespace }}{{ end }}{{ if .sectionName }}, listener {{ .sectionName }}{{ end }}
{{- end }}
       must exist AND its listener must allow routes from this namespace
       ({{ .Release.Namespace }}) in allowedRoutes. A rejected attachment shows
       up only in the route's status:

         kubectl -n {{ .Release.Namespace }} get httproute {{ .Release.Name }}-{{ .Chart.Name }}-httproute -o yaml

       Read status.parents[].conditions — "Accepted: True" and
       "ResolvedRefs: True" is a working attachment. An empty status means no
       controller has looked at the route at all.
    3. The TLS certificate for the hostname, on the Gateway's listener.
       ingress.clusterIssuer is NOT used in this mode and is not required: the
       chart renders no Certificate, so there is no
       tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress secret and nothing for cert-manager to do.

  ingress.domain is still required in this mode and is {{ .Values.ingress.domain }}: it becomes
  Outline's URL variable, which builds every generated link, every share URL
  and the OIDC redirect URI. The route does not replace it. If you set
  httpRoute.hostnames to a name ingress.domain does not carry, the route
  publishes one host while the app hands out links for another — and an OIDC
  login then fails on a redirect_uri the provider does not know. Set both
  together.

  ingress.annotations is inert in this mode: the Gateway API has no annotation
  channel. WebSockets need none — Outline's realtime editing upgrades on the
  same port and a plain HTTPRoute passes that through, exactly as the Ingress
  did without an annotation.
{{- else }}

ACCESS — NEITHER INGRESS NOR HTTPROUTE
  ingress.enabled and httpRoute.enabled are both false, so this release is not
  published: no Ingress, no HTTPRoute and no certificate.
  ingress.domain is still required: it becomes Outline's URL variable, which
  builds every generated link, every share URL and the OIDC redirect URI.
  Reach the instance inside the cluster with

    kubectl -n {{ .Release.Namespace }} port-forward svc/{{ .Release.Name }}-{{ .Chart.Name }}-service 8080:80

  and open http://localhost:8080. Links on the page will still point at
  https://{{ .Values.ingress.domain }}/, and an OIDC login will only complete if
  that host actually resolves for the browser.
{{- end }}
{{ if eq $replicas "0" }}
SCALED TO ZERO
  {{ if .Values.scaleDown }}scaleDown: true{{ else }}outline.replicas: 0{{ end }} — the StatefulSet runs with replicas: 0, so the endpoint
  above does not answer until you set it back and upgrade again. PVC, Secrets,
  Service{{ if .Values.ingress.enabled }} and Ingress stay in place, so neither the uploads nor the
  certificate are touched.{{ else if $httpRoute.enabled }} and HTTPRoute stay in place, so the uploads are not touched — the
  route then resolves to a Service with no endpoints and the Gateway answers
  its own error.{{ else }} and the uploads on the PVC stay in place.{{ end }}
{{ end }}
WHAT THE THREE 1PASSWORD ITEMS MUST CONTAIN
  The chart creates OnePasswordItem CRs; the operator turns each into a
  Kubernetes Secret whose keys are the FIELD NAMES of the 1Password item. A
  missing field does not fail the install — the release goes through and the
  pod then hangs in CreateContainerConfigError naming the key it could not
  find (kubectl -n {{ .Release.Namespace }} describe pod).

  secrets.configSecretRef → {{ .Values.secrets.configSecretRef }}
    Secret {{ .Release.Name }}-{{ .Chart.Name }}-secret, fields:
      outline-secret-key      SECRET_KEY, 32 random bytes hex (openssl rand -hex 32)
      outline-utils-secret    UTILS_SECRET, a second, independent value
      discovery-url           OIDC issuer URL (the .well-known discovery endpoint)
      client-id               OIDC client id
      client-secret           OIDC client secret

  secrets.dbSecretRef → {{ .Values.secrets.dbSecretRef }}
    Secret {{ .Release.Name }}-{{ .Chart.Name }}-db-secret, field:
      connection-url          postgres://user:password@host:5432/database

  secrets.redisSecretRef → {{ .Values.secrets.redisSecretRef }}
    Secret {{ .Release.Name }}-{{ .Chart.Name }}-redis-secret, field:
      connection-url          redis://host:6379

  On the identity provider's side the client needs this redirect URI:

    https://{{ .Values.ingress.domain }}/auth/oidc.callback

  The login button is labelled "{{ .Values.outline.oidc.displayName }}" (outline.oidc.displayName).
  Nothing about OIDC is exercised before someone actually signs in, so a wrong
  issuer, secret or redirect URI surfaces as a failed login on a healthy pod.
  The first account to sign in creates the workspace and becomes its admin —
  on a fresh install, sign in yourself before handing the URL to anyone.

CHANGING A SECRET'S CONTENT RESTARTS NOTHING
  Helm never sees the content of a OnePasswordItem, so it cannot hash it, and
  this chart carries no checksum annotation for secrets (it has no ConfigMap
  either). Pointing a *SecretRef at a DIFFERENT item rolls the pods; editing a
  value INSIDE the same item does not — the operator updates the Kubernetes
  Secret while the running container keeps the old value in its environment.
  After such a rotation:

    kubectl -n {{ .Release.Namespace }} rollout restart statefulset/{{ .Release.Name }}-{{ .Chart.Name }}-sfs

  Rotating outline-secret-key invalidates existing sessions; rotating it
  without keeping the old value also makes previously encrypted data
  unreadable. Rotate the database or Redis URL and the pod restarts into
  whatever that new endpoint contains, empty or not.

POSTGRES AND REDIS ARE NOT PART OF THIS CHART
  Both have to exist and be reachable before the first start. /_health checks
  them, and all three probes use it, so a missing database does not produce a
  useful error: the pod simply never turns Ready and the startup probe kills
  it after about {{ mul $startup.failureThreshold $startup.periodSeconds }}s. Read the container log, not the pod events.

  The chart pins PGSSLMODE=disable next to the connection URL. That fits a
  Postgres reached over the cluster network; a database anywhere less trusted
  needs TLS asked for explicitly, and this chart has no value for it — the
  outline.env block below is the place to set it.

THE FIRST START MIGRATES, AND THE STARTUP PROBE IS THE CLOCK
  Outline runs its database migrations when the container starts. The startup
  probe grants {{ $startup.failureThreshold }} × {{ $startup.periodSeconds }}s = {{ mul $startup.failureThreshold $startup.periodSeconds }}s before the kubelet restarts the
  container — and a restart lands in the middle of a migration. Raise
  outline.startupProbe.failureThreshold BEFORE a large app-version jump or a
  first import, not after the crash loop has started.

  Back up the database before any app-version bump. Migrations are one-way; a
  helm rollback returns the old image to a database the new one has already
  rewritten.

ONE REPLICA, ONE VOLUME
  Uploads are stored locally (FILE_STORAGE=local), on the ReadWriteOnce PVC
  {{ .Release.Name }}-{{ .Chart.Name }}-pvc under /outline-data/data — there is no object storage in
  this chart. That PVC is a plain chart object, not a StatefulSet
  volumeClaimTemplate, so all replicas would share the single RWO volume and
  the second pod usually never schedules.
{{- if gt (int $replicas) 1 }}

  outline.replicas is {{ $replicas }}. Expect the extra pods to stay Pending on
  "Multi-Attach error for volume" unless the storage class is genuinely RWX.
{{- end }}

BACKUP IS TWO THINGS AT THE SAME TIME
  The database holds the documents and one row per attachment; the PVC holds
  the attachment bytes. Restoring one without the other gives a wiki with
  broken images or files nobody references. Snapshot them together.

  Because the PVC is rendered by the chart, helm uninstall deletes it and the
  uploads with it, unless the storage class reclaim policy says otherwise. The
  external database survives that — which makes an accidental uninstall look
  recoverable while the attachments are already gone.
{{- if .Values.ingress.enabled }}

TWO UPLOAD CEILINGS, THE SMALLER ONE WINS
  outline.maxUploadSize   {{ $upload }}{{ if regexMatch "^[0-9]+$" $upload }} bytes (~{{ div (int64 $upload) 1048576 }} MiB){{ else }} — Outline reads this as a plain byte count{{ end }}
  ingress.maxUploadFileSize   {{ .Values.ingress.maxUploadFileSize }}

  The smaller of the two decides, and the Ingress limit fails the more
  confusingly: a file above it never reaches Outline, so the user gets the
  ingress controller's 413 page instead of a message from the app. With the
  chart defaults the Ingress is the tighter of the two by a factor of ten.
  Raise both, or neither.
{{- else if $httpRoute.enabled }}

YOUR UPLOAD CEILING IS NOT ingress.maxUploadFileSize ANY MORE — IT IS THE GATEWAY'S
  outline.maxUploadSize        {{ $upload }}{{ if regexMatch "^[0-9]+$" $upload }} bytes (~{{ div (int64 $upload) 1048576 }} MiB){{ else }} — Outline reads this as a plain byte count{{ end }}
  ingress.maxUploadFileSize    {{ .Values.ingress.maxUploadFileSize }} — NOT ENFORCED in this mode

  The chart renders ingress.maxUploadFileSize into
  nginx.ingress.kubernetes.io/proxy-body-size, and the Gateway API has NO
  counterpart — it knows no body size at all, that is implementation-specific
  policy — so this chart deliberately renders no policy object, which would
  bind it to one implementation. The ceiling that actually bites is therefore
  the smaller of outline.maxUploadSize and WHATEVER THE GATEWAY ENFORCES, and
  the chart can only name the first of those two. Set the limit at the Gateway
  or through its implementation's own policy object, next to the Gateway and
  not here.

  Read that next to Gitea #12, which is about exactly this pair: with the chart
  defaults the two documented numbers are a factor of ten apart. In this mode
  the ingress half is gone, so neither of them is necessarily the one that
  decides — which moves that defect rather than fixing it. Check the Gateway's
  own limit before trusting either number.
{{- else }}

UPLOAD CEILING
  outline.maxUploadSize   {{ $upload }}{{ if regexMatch "^[0-9]+$" $upload }} bytes (~{{ div (int64 $upload) 1048576 }} MiB){{ else }} — Outline reads this as a plain byte count{{ end }}

  With neither routing mode on, this is the only limit the chart sets —
  whatever proxy you put in front adds its own, usually much smaller,
  body-size cap. ingress.maxUploadFileSize ({{ .Values.ingress.maxUploadFileSize }}) is rendered nowhere.
{{- end }}

THE CHART CONFIGURES NO MAIL
  Outline sends invitations, document notifications and digest mails over
  SMTP. This chart sets no SMTP_* variable at all, so those mails are quietly
  never sent and nothing in the UI says so. The place to add them is
  outline.env, which also supports the secretKeyRef form for the password.
{{- if .Values.outline.env }}

  outline.env currently adds {{ len .Values.outline.env }} variable(s), rendered after the ones the chart
  sets itself.
{{- end }}
{{- if has (.Values.outline.forceHttps | toString) (list "true" "1") }}

FORCE_HTTPS IS ON
  outline.forceHttps is set. The chart defaults it to "false" because the
  Ingress already terminates TLS and Outline trusts the forwarded protocol
  header. Turned on, Outline redirects to https itself — which loops
  endlessly if that header does not reach the pod.
{{- end }}
{{- if .Values.networkPolicy.enabled }}

NETWORKPOLICY IS ACTIVE — WHAT IT CAPS, AND WHAT IT DOES NOT
  {{ .Release.Name }}-{{ .Chart.Name }}-networkpolicy selects this workload's pods.
  Inbound: TCP 3000 only. Outbound: DNS, TCP 5432 (Postgres), 6379 (Redis),
  443 (OIDC discovery){{ with .Values.networkPolicy.egress }}{{ with .extraPorts }}, plus TCP {{ join ", " . }}{{ end }}{{ end }}.

  THOSE EGRESS PORTS ARE THE STANDARD ONES, NOT YOUR CONFIGURED ONES. The
  database, Redis and OIDC URLs all live inside 1Password items that this chart
  never parses, so it cannot know where your dependencies listen. A dependency
  on another port is blocked — and since all three probes hit /_health, which
  checks Postgres and Redis, the symptom is a pod that never becomes Ready
  rather than a connection error anyone sees. Add the real port to
  networkPolicy.egress.extraPorts.

  Three limits belong in the same breath, because none of them is visible in
  the object itself:

  - EGRESS IS BY PORT, NEVER BY DESTINATION. A NetworkPolicy matches CIDRs and
    selectors and cannot express a hostname, so every egress rule permits its
    port to ANY address. That is a limit of the object, not a shortcut — this
    cluster's CNI (Canal: Flannel plus Calico) has no FQDN rule either. An
    outbound port the chart does not know about is BLOCKED: add it to
    networkPolicy.egress.extraPorts, and expect to find out through an
    application-level connection error rather than through this object.
{{- if .Values.networkPolicy.probeSources }}
  - THE PROBE PATH IS RESTRICTED in this release, because
    networkPolicy.probeSources is set to
      {{ join ", " .Values.networkPolicy.probeSources }}
    Probes come from the IP of the WORKER NODE running the pod. If none of those
    CIDRs covers the node this pod lands on, the kubelet's probes are dropped
    and THE POD NEVER BECOMES READY — the rollout then times out and the symptom
    looks like a broken application. Compare

      kubectl -n {{ .Release.Namespace }} describe pod -l app={{ .Release.Name }}-{{ .Chart.Name }}-sfs

    against `kubectl get node -o wide`.
{{- else }}
  - THE PROBED PORT IS OPEN INSIDE THE CLUSTER. networkPolicy.probeSources is
    empty, so that rule carries no source selector at all and any pod the CNI
    routes to can reach it. Not from the internet — but this is NOT pod-level
    isolation. Narrowing it means listing the worker node IPs in
    networkPolicy.probeSources, because the kubelet probes from the node's own
    address and the chart cannot know it; a wrong guess there leaves the pod
    permanently un-Ready.
{{- end }}
  - IT IS ONLY A BOUNDARY WHERE THE CNI ENFORCES POLICIES. Where it does not,
    this object is accepted and filters nothing, so everything reads as
    configured while nothing is filtered. `kubectl -n {{ .Release.Namespace }} get networkpolicy`
    shows the object exists; only a connection attempt from an unrelated
    namespace shows that it bites.

  Switch it off with networkPolicy.enabled: false.
{{- end }}