docs: add optional variables section to OpenTelemetry configuration g…

docs/how-tos/chain-events/opentelemetry.md

@@ -21,7 +21,12 @@ Add these to your `.env`:
 OTEL_ENABLED=true
 OTEL_SERVICE_NAME=trustvc-chain-events
 OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otlp-endpoint
-OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=explicit_bucket_histogram
+```
+
+### Optional Variables
+
+| Variable | Default | Description |
+|---|---|---|
 | `OTEL_EXPORTER_OTLP_HEADERS` | — | Auth headers required by your backend (see examples below) |
 | `OTEL_INSTANCE_ID` | `<hostname>-<pid>` | Custom instance identifier shown in metrics labels |
 | `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | — | Set to `explicit_bucket_histogram` for Prometheus-compatible histograms |

docs/how-tos/chain-events/quick-start.md

@@ -13,6 +13,14 @@ Get `trustvc-chain-events` running locally in under 5 minutes.
 
 ## Step 1 — Pull the Image
 
+**Docker Hub (recommended)**
+
+```bash
+docker pull trustvc/trustvc-chain-events:latest
+```
+
+**GitHub Container Registry (alternative)**
+
 ```bash
 docker pull ghcr.io/trustvc/trustvc-chain-events:latest
 ```
@@ -106,15 +114,15 @@ docker run -d \
   --env-file .env \
   -p 8080:8080 \
   --name trustvc-events \
-  ghcr.io/trustvc/trustvc-chain-events:latest
+  trustvc/trustvc-chain-events:latest
 ```
 
 **With Docker Compose**
 
 ```yaml title="docker-compose.yml"
 services:
   trustvc-events:
-    image: ghcr.io/trustvc/trustvc-chain-events:latest
+    image: trustvc/trustvc-chain-events:latest
     ports:
       - "8080:8080"
     volumes:

docs/how-tos/chain-events/registry-api.md

@@ -9,7 +9,7 @@ sidebar_position: 5
 
 The container exposes a REST API on port `8080` that lets you add and remove Token Registry contracts at runtime — without restarting the container or editing `config.json`.
 
-:::note Database required
+:::warning Database required
 All registry management endpoints require `DB_HOST` to be configured. They return `503 Service Unavailable` if no database is connected. Registries added via the API are persisted to the database and survive container restarts.
 :::
 
@@ -130,7 +130,7 @@ docker run -d \
   -v $(pwd)/config.json:/app/config.json:ro \
   --env-file .env \
   -p 8080:8080 \
-  ghcr.io/trustvc/trustvc-chain-events:latest
+  trustvc/trustvc-chain-events:latest
 ```
 
 **Step 2 — Deploy your Token Registry**

docs/how-tos/chain-events/scaling.md

@@ -25,6 +25,19 @@ By default, each chain runs in its own child process (`workerProcesses: true` in
 
 ## Horizontal Scaling
 
+:::warning A database is required for scaling and HA
+
+Running more than one replica **without a database will cause duplicate events** — every replica polls the chain independently, so your webhook endpoint receives multiple copies of the same event.
+
+The database solves this in two ways:
+
+- **One replica owns each chain at a time** — replicas compete for a lease stored in the database. Only the winner polls; the others wait on standby.
+- **Progress survives restarts** — the last processed block is persisted, so a restarting replica resumes exactly where it left off instead of replaying from scratch.
+
+**Set `DB_HOST` before running more than one container.**
+
+:::
+
 To run multiple instances of the container in parallel — for redundancy or higher throughput — you must connect a database. The container uses a **distributed lease** mechanism (one active worker per chain at a time) to prevent duplicate event delivery when multiple instances are running.
 
 ```bash
@@ -42,7 +55,7 @@ If the active instance crashes or loses its lease, another instance picks it up
 ```yaml
 services:
   trustvc-events:
-    image: ghcr.io/trustvc/trustvc-chain-events:latest
+    image: trustvc/trustvc-chain-events:latest
     deploy:
       replicas: 2
     ports:
@@ -94,7 +107,7 @@ For production deployments on AWS, run the container as a Fargate service. The t
   "containerDefinitions": [
     {
       "name": "trustvc-chain-events",
-      "image": "ghcr.io/trustvc/trustvc-chain-events:latest",
+      "image": "trustvc/trustvc-chain-events:latest",
       "portMappings": [
         { "containerPort": 8080, "protocol": "tcp" }
       ],