feat: enhance Broker HA mode docs

.gitignore

@@ -2,3 +2,4 @@
 **/.DS_Store
 .idea/
 error-catalog/
+.vscode/settings.json

docs/enterprise-setup/snyk-broker/universal-broker/deployment-tips-and-reference-architectures.md

@@ -20,6 +20,6 @@ Contact your Snyk account team or [Snyk support](https://support.snyk.io/s/) if
 
 ### High Availability Mode
 
-High Availability Mode for a Universal Broker deployment is enabled by default and can be disabled by by setting the `BROKER_HA_MODE_ENABLED=false` environment variable inside the container. When this mode is enabled, the Universal Broker deployment will support up to four Broker client replicas.
+High Availability Mode for a Universal Broker deployment is enabled by default, the Universal Broker deployment will support up to four Broker client replicas.
 
 For more information on High Availability Mode, please refer to the [HA mode documentation page.](../../../implementation-and-setup/enterprise-setup/snyk-broker/high-availability-mode.md)

docs/implementation-and-setup/enterprise-setup/snyk-broker/high-availability-mode.md

@@ -1,30 +1,14 @@
 # High availability mode
 
-Snyk Broker can bring high availability capabilities to both servers and clients, thus increasing the scalability of the current Broker, initially to support the addition of the “git-clone-through-broker” flow for Snyk Code.
+The Snyk Broker client offers high availability capabilities by default for greater scalability of the Broker, initially to support the addition of the “git-clone-through-broker” flow for Snyk Code.
 
-High availability mode allows several Broker Clients to have separate connections, independent of one another. The Snyk platform will spread the requests it makes evenly across the connections to ease the load on each client and provide true redundancy if one is offline. High availability mode also avoids downtime in the fairly infrequent cases when Snyk upgrades the Broker server components.
+High availability mode allows you to run several Broker clients that work independently to one another. The Snyk platform will spread the requests it makes evenly across the connections to ease the load on each client and provide true redundancy if one is offline. High availability mode also avoids downtime in the fairly infrequent cases when Snyk upgrades the Broker server components.
 
 <figure><img src="../../../.gitbook/assets/snyk-broker-ha-mode.png" alt="Operation of multiple Broker clients in high availability"><figcaption><p>Operation of multiple Broker clients in high availability</p></figcaption></figure>
 
-To use high availability mode, deploy more than one replica, either by running more than one container or by increasing the replica count in your Kubernetes deployment. Each container must have the exact same parameters.
+To use high availability mode, we recommend using docker-compose to run multiple replicas (see example here) or by increasing the replica count in your Kubernetes deployment. Each container must have the exact same parameters.
 
-A maximum of four Broker Clients running concurrently in high availability mode is allowed. A fifth tunnel will attempt to connect indefinitely.
-
-## Settings to enable high availability (HA) mode
-
-High availability mode is disabled by default. To activate it, set the following environment variables as shown either in your container or deployment:
-
-```
-BROKER_HA_MODE_ENABLED=true
-```
-
-Helm chart deployments can set these values by enabling the mode using set arguments. Helm chart version 1.7.0 or later is required.
-
-```
---set highAvailabilityMode.enabled=true
-```
-
-Review the chart values file to adjust additional configurations such as increasing replica count, updating broker dispatcher base URL, and so on.
+A maximum of four Broker Clients can run concurrently in high availability mode. Running a fifth Broker Client will attempt to connect indefinitely.
 
 ## **Important notes about settings**
 
@@ -38,7 +22,7 @@ BROKER_DISPATCHER_BASE_URL=https://api.snyk.io
 
 Outbound connection to api.snyk.io or the corresponding api hostname must be allowed. Otherwise, preflight checks will indicate failure upon Broker client startup.
 
-`BROKER_CLIENT_URL` value must remain the same across all the Broker clients in the high availability set. The same BROKER\_TOKEN must also be used.\
+The `BROKER_CLIENT_URL` value must remain the same across all the Broker clients in the high availability set. The same BROKER\_TOKEN must also be used.\
 It is acceptable for this URL to resolve to a particular client.
 
 The multiple tunnels are primarily supporting Snyk=>You flow. The webhooks going You=>Snyk can take any tunnel as well.

docs/implementation-and-setup/enterprise-setup/snyk-broker/universal-broker/prerequisites-for-universal-broker.md

@@ -16,9 +16,9 @@ Before installing the Universal Broker `snyk-broker-config` CLI tool, be sure yo
 * A new/dedicated Snyk Organization. This will be used to administrate your Broker configuration(s) and a dedicated organization will help prevent accidental removal. See [Create an Organization](../../../../snyk-platform-administration/groups-and-organizations/organizations/create-and-delete-organizations.md#create-an-organization) for details.
 * An SCM token or password. Snyk Broker does not support authentication with the mTLS method.
 * Node 20 or higher installed.
-* Docker configured to pull images from Docker Hub in order to install with Docker.
+* Docker Compose install and configured to pull images from Docker Hub.
 
-Snyk recommends that you export SNYK\_TOKEN and TENANT\_ID in your terminal session environment variables now, using the following commands:
+Snyk recommends that you export SNYK_TOKEN and TENANT_ID in your terminal session environment variables now, using the following commands:
 
 Linux/Mac
 

docs/implementation-and-setup/enterprise-setup/snyk-broker/universal-broker/running-your-universal-broker-client.md

@@ -1,21 +1,75 @@
 # Running your Universal Broker client
 
-Run your Broker deployment on your container engine or Kubernetes cluster.
+{% hint style="info" %}
+Ensure you have all of the [prerequisites](prerequisites-for-universal-broker.md) before running the Broker Client:
+  - The DEPLOYMENT_ID, CLIENT_ID, CLIENT_SECRET for your Broker Deployment
+  - A credential reference associated with your deployment
+  - Valid integration credentials required by your connections (e.g. GITHUB_TOKEN)
+{% endhint %}
+
+If references are missing, the connection will not be established, and an error entry will be logged in the Broker client logs.
+
+Run your Broker deployment on your container engine (see example Docker Compose file below) or Kubernetes cluster.
 
 If you are not using broker.snyk.io, target the Broker server for your region by using the command `-e BROKER_SERVER_URL=https://broker.region.snyk.io \` . For details, see [Broker URLs](../../../../snyk-data-and-governance/regional-hosting-and-data-residency.md#broker-server-urls).
 
-Add the environment variable or variables as defined in your credentials references with the associated values. If references are missing, the connection will not be established, and an error entry will be logged in the Broker client logs.
+## Docker Compose
+
+### Usage 
 
+1. Create a .env file with required and optional configuration variables:
+```bash
+  DEPLOYMENT_ID=<your-deployment-id>
+  CLIENT_ID=<your-client-id>
+  CLIENT_SECRET=<your-client-secret>
+  PORT=8000
+  # Add any credentials your integrations need, for example:
+  MY_GITHUB_TOKEN=<secret>
+  # Optional: override for EU or other environments
+  BROKER_SERVER_URL=https://broker.eu.snyk.io
+  BROKER_DISPATCHER_BASE_URL=https://api.eu.snyk.io
 ```
-docker run --restart=always 
--p 8000:8000 
--e DEPLOYMENT_ID=<DEPLOYMENTID> 
--e CLIENT_ID=<CLIENTID> 
--e CLIENT_SECRET=<CLIENTSECRET> 
--e PORT=8000 
--e <YOUR_CREDENTIALS_REFERENCE>=<secret value> 
-snyk/broker:universal
+2. Copy this example file to docker-compose.yaml
+
+```yaml
+services:
+  snyk-broker-universal-1:
+    image: snyk/broker:universal
+    environment:
+      DEPLOYMENT_ID: ${DEPLOYMENT_ID}
+      CLIENT_ID: ${CLIENT_ID}
+      CLIENT_SECRET: ${CLIENT_SECRET}
+      PORT: ${PORT:-8000}
+      BROKER_SERVER_URL: ${BROKER_SERVER_URL:-https://broker.snyk.io}
+      BROKER_DISPATCHER_BASE_URL: ${BROKER_DISPATCHER_BASE_URL:-https://api.snyk.io}
+      GITHUB_TOKEN: ${MY_GH_TOKEN}
+      # Pass through any integration credentials (same as -e KEY=value in docker run)
+      # Example: GITHUB_TOKEN, BROKER_CLIENT_VALIDATION_AUTH_HEADER, etc.
+    env_file:
+      - .env
+    ports:
+      - "${EXTERNAL_PORT_1:-8000}:${PORT:-8000}"
+    restart: unless-stopped
+
+  snyk-broker-universal-2:
+    image: snyk/broker:universal
+    environment:
+      DEPLOYMENT_ID: ${DEPLOYMENT_ID}
+      CLIENT_ID: ${CLIENT_ID}
+      CLIENT_SECRET: ${CLIENT_SECRET}
+      PORT: ${PORT:-8000}
+      BROKER_SERVER_URL: ${BROKER_SERVER_URL:-https://broker.snyk.io}
+      BROKER_DISPATCHER_BASE_URL: ${BROKER_DISPATCHER_BASE_URL:-https://api.snyk.io}
+      GITHUB_TOKEN: ${MY_GH_TOKEN}
+    env_file:
+      - .env
+    ports:
+      - "${EXTERNAL_PORT_2:-8001}:${PORT:-8000}"
+    restart: unless-stopped
 ```
+3. Run `docker compose up -d` to start the containers
+
+## Helm
 
 A [Helm chart](https://github.com/snyk/snyk-universal-broker-helm) is available for use on Kubernetes clusters. Refer to the readme for details.