> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 5.3: Upgrade guide

> Review proxy trust and Hub images, then verify sign-in and scheduled work.

**Applies to:** installations entering or updating within 5.3, Docker/one-click and Kubernetes, both editions.
The base-release steps apply when crossing 5.3.0; for later updates within 5.3, review the [patch actions](#patch-actions).
Apply earlier [5.x notes](https://formbricks.com/docs/self-hosting/advanced/migration.md#version-5) when coming from an older source.

## Before

Review proxy trust, Hub/Cube configuration and optional scheduling settings below. The release adds
workflow, archive and 2FA-lockout data structures; allow the target migration runner to apply them.
No new mandatory environment variable is introduced for a standard v5.2 installation.

### Client IP resolution behind a proxy (recommended)

v5.3 resolves the client IP from the `X-Forwarded-For` chain using a configurable number of trusted proxy
hops:

* `TRUSTED_PROXY_HOP_COUNT` — optional, **defaults to `1`**. Set it to the number of trusted proxies /
  load balancers in front of Formbricks (e.g. an ingress plus a CDN = `2`). An explicit `0` trusts no
  proxy at all: the runtime exposes no socket peer address, so the client IP then resolves to a fixed
  "untrusted" placeholder that rate limiting and response audit logging record in place of a real address.
  A forwarding chain shorter than the configured count, or a malformed selected hop, also fails closed.
  Ports appended by gateways such as
  [Azure Application Gateway](https://learn.microsoft.com/en-us/azure/application-gateway/how-application-gateway-works#modifications-to-the-request)
  are removed, and IPv6 addresses are normalized to their `/64` network. Leave the setting at `1` (or
  your real hop count) unless you deliberately want to stop capturing client IPs.

> [!WARNING]
>
> Setting `TRUSTED_PROXY_HOP_COUNT` **higher** than your real hop count lets a client spoof its IP by
> sending a forged `X-Forwarded-For` header. Set it to the exact number of proxies in front of the app —
> no higher. The default of `1` is correct for a single reverse proxy / ingress.

### Renamed configuration

* **Scheduling variables renamed.** `NEXT_PUBLIC_SURVEY_SCHEDULING_*` → `SURVEY_SCHEDULING_*` (the
  `NEXT_PUBLIC_` prefix was dropped). This only affects you if you ran a v5.3 release candidate that used
  the old names; a clean v5.2 → v5.3 upgrade never set them.

### Optional new configuration

None of the following is required to run v5.3. Add them only if you want the associated feature.

#### Survey scheduling

The new survey-scheduling feature runs on a fixed daily local time. All three are optional and defaulted:

* `SURVEY_SCHEDULING_TIME_ZONE` — a valid IANA time zone. Default `Europe/Berlin`.
* `SURVEY_SCHEDULING_LOCAL_HOUR` — default `0`.
* `SURVEY_SCHEDULING_LOCAL_MINUTE` — default `0`.

#### Password breach check

* `PASSWORD_HIBP_CHECK_DISABLED` — set to `"1"` to disable the "Have I Been Pwned" breached-password
  check on sign-up and password reset (`"0"` or unset keeps it on).

### Analytics (Cube)

Two Cube-related deltas in v5.3. Neither changes the Cube schema, so there is **no schema refresh to run**:

* **`CUBEJS_EXTERNAL_DEFAULT` now defaults to `false`** (in both `docker/docker-compose.yml` and the Helm
  chart). Cube Store is used only when you explicitly opt into external pre-aggregations — a safe default
  for most self-hosters. Set it back to `true` only if you run external pre-aggregations.
* **Hub images must be pinned together.** Read the selected patch's Helm values/release notes for its
  Hub version. Set `HUB_IMAGE_REF=:<selected-hub-tag>` in Compose's `.env`, keeping the leading colon
  and replacing the placeholder. Check `docker compose config --images` shows the same Hub image for
  API and migration services (and a worker if present). Do not assume all 5.3 patches ship the same Hub image.

### Patch actions

Apply each change you cross on this release line, even when installing a later patch.
These entries do not add intermediate installation stops.

| First affected patch | Additional action |
| - | - |
| 5.3.5 | Nothing extra. The storage setup helper now uses the RustFS CLI; keep your existing MinIO or S3 data and settings. See [5.3.5](https://formbricks.com/docs/platform/changelog.md#release-5-3-5). |

## During

Follow the [4.x/5.x maintenance procedure](https://formbricks.com/docs/self-hosting/upgrade/legacy.md). Merge the target's deployment
changes using the [merge checklist](https://formbricks.com/docs/self-hosting/upgrade/configuration.md#merge-the-release-configuration) before pulling; preserve local settings and run migrations with writers stopped.
Do not enable optional AI services just because they appear in the reference Compose file.

## After

* Test sign-in, 2FA, password reset and client-IP handling through your actual proxy chain.
* Create/schedule a test survey, open dashboard charts and verify enabled workflows process work.
* Complete the [shared acceptance checks](https://formbricks.com/docs/self-hosting/upgrade/rehearse.md#acceptance-at-every-stop).

## Recovery

The v5.3 application schema additions do not by themselves require a database restore for v5.2, but this
is not a guarantee for changed Hub versions or work accepted by new features. Keep maintenance active,
restore coordinated state when needed, and check jobs before reopening. See [recovery](https://formbricks.com/docs/self-hosting/operate/backup-restore.md).

Source: [5.2.2 → 5.3.0](https://github.com/formbricks/formbricks/compare/5.2.2...5.3.0) and later 5.3 patch tags.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.