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

# Operations

> Environment variables, the health probe and troubleshooting the Pusher realtime layer.

## Environment variables (server)

All four keys are required to enable the publisher; the fifth is optional.

| Variable                     | Required | Purpose                                  |
| ---------------------------- | -------- | ---------------------------------------- |
| `INTEGRATION_PUSHER_APP_ID`  | Yes      | Pusher application id.                   |
| `INTEGRATION_PUSHER_KEY`     | Yes      | Public key (also shipped to the client). |
| `INTEGRATION_PUSHER_SECRET`  | Yes      | Server secret.                           |
| `INTEGRATION_PUSHER_CLUSTER` | Yes      | Cluster (e.g. `us2`).                    |
| `INTEGRATION_PUSHER_USE_TLS` | No       | Defaults to `true`.                      |

<Note>
  When any of the four required keys is missing, `getPusherClient()` returns
  `null`, the publisher degrades to log-only mode and the health probe reports
  the component as down.
</Note>

## Health probe

The integration health service issues a cheap authenticated `GET /channels`
against the Pusher HTTP API (`checkPusher()`), combined with real publish
traffic recorded via `recordIntegrationOutcome("pusher", ...)`. Better Stack
tracks the component as `INT-06` on the status page.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Client shows status: disabled">
    `NEXT_PUBLIC_PUSHER_KEY` is empty. Set it for the environment (public value)
    and redeploy the app so the build-time variable is baked in.
  </Accordion>

  <Accordion title="Private channel subscription fails with AuthError">
    The auth endpoint is misconfigured or the caller lacks `pusher:auth`. Verify
    the app proxies to `POST /api/v3/realtime/pusher/auth` and the channel
    matches `private-(contract|account)-{uuid}`.
  </Accordion>

  <Accordion title="Events are published but never received">
    Confirm the client cluster matches the server cluster
    (`INTEGRATION_PUSHER_CLUSTER` vs `NEXT_PUBLIC_PUSHER_CLUSTER`) and that both
    sides use the same Pusher app.
  </Accordion>

  <Accordion title="Health shows Pusher down but publishing works">
    A `4xx` never flips the verdict, but a missing `GET /channels` capability or
    a network error will. Check the server credentials and outbound network.
  </Accordion>
</AccordionGroup>

## Client-side debug

`usePusherChannel` prints verbose lifecycle logs when either
`localStorage.setItem("bbl:pusher:debug", "1")` is set from the browser console
or `?pusher_debug=1` is appended to the URL.