From e7195a47d6b08b4c47a7a82852987dae60d7a05d Mon Sep 17 00:00:00 2001 From: manishdex25 Date: Mon, 1 Jun 2026 12:52:47 +0530 Subject: [PATCH 1/6] docs: add optional variables section to OpenTelemetry configuration guide Introduced a new section detailing optional environment variables for OpenTelemetry configuration, enhancing clarity and usability for users. --- docs/how-tos/chain-events/opentelemetry.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/how-tos/chain-events/opentelemetry.md b/docs/how-tos/chain-events/opentelemetry.md index 64640b1..c19a318 100644 --- a/docs/how-tos/chain-events/opentelemetry.md +++ b/docs/how-tos/chain-events/opentelemetry.md @@ -22,6 +22,12 @@ 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` | `-` | Custom instance identifier shown in metrics labels | | `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | — | Set to `explicit_bucket_histogram` for Prometheus-compatible histograms | From a02709d29d79de04f8b7189fb7b5c30e4486463f Mon Sep 17 00:00:00 2001 From: manishdex25 Date: Mon, 1 Jun 2026 13:26:45 +0530 Subject: [PATCH 2/6] fix: remove outdated environment variable from OpenTelemetry documentation Removed the `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` entry to streamline the OpenTelemetry configuration guide and eliminate potential confusion for users. --- docs/how-tos/chain-events/opentelemetry.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/how-tos/chain-events/opentelemetry.md b/docs/how-tos/chain-events/opentelemetry.md index c19a318..6034ba8 100644 --- a/docs/how-tos/chain-events/opentelemetry.md +++ b/docs/how-tos/chain-events/opentelemetry.md @@ -30,7 +30,6 @@ OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=explicit_bucket_histogr |---|---|---| | `OTEL_EXPORTER_OTLP_HEADERS` | — | Auth headers required by your backend (see examples below) | | `OTEL_INSTANCE_ID` | `-` | Custom instance identifier shown in metrics labels | -| `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | — | Set to `explicit_bucket_histogram` for Prometheus-compatible histograms | --- From 9d30fa0ba742321ff85b6b477e44859ad0ad0242 Mon Sep 17 00:00:00 2001 From: manishdex25 Date: Mon, 1 Jun 2026 13:28:35 +0530 Subject: [PATCH 3/6] docs: clarify optional environment variable for OpenTelemetry configuration Reintroduced the `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` variable in the optional variables section to provide clear guidance on its usage for Prometheus-compatible histograms. --- docs/how-tos/chain-events/opentelemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-tos/chain-events/opentelemetry.md b/docs/how-tos/chain-events/opentelemetry.md index 6034ba8..8b8165d 100644 --- a/docs/how-tos/chain-events/opentelemetry.md +++ b/docs/how-tos/chain-events/opentelemetry.md @@ -21,7 +21,6 @@ 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 @@ -30,6 +29,7 @@ OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=explicit_bucket_histogr |---|---|---| | `OTEL_EXPORTER_OTLP_HEADERS` | — | Auth headers required by your backend (see examples below) | | `OTEL_INSTANCE_ID` | `-` | Custom instance identifier shown in metrics labels | +| `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | — | Set to `explicit_bucket_histogram` for Prometheus-compatible histograms | --- From ef59023ef1547b55f1cd731f5e258f6f0bec9afb Mon Sep 17 00:00:00 2001 From: manishdex25 Date: Tue, 2 Jun 2026 11:07:46 +0530 Subject: [PATCH 4/6] docs: add warning about database requirement for horizontal scaling Included a warning in the scaling documentation to emphasize the necessity of a database when running multiple replicas to prevent duplicate events. Explained how the database facilitates lease management and progress persistence for replicas. --- docs/how-tos/chain-events/scaling.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/how-tos/chain-events/scaling.md b/docs/how-tos/chain-events/scaling.md index 2e77d05..b7926f3 100644 --- a/docs/how-tos/chain-events/scaling.md +++ b/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 From b65ebf6fd7b0f290ec6205c92aba074fc62e93c2 Mon Sep 17 00:00:00 2001 From: manishdex25 Date: Tue, 2 Jun 2026 14:47:38 +0530 Subject: [PATCH 5/6] docs: update container image references in chain events documentation Replaced instances of the GitHub Container Registry image with the Docker Hub image for consistency across the quick start, registry API, and scaling documentation. This change simplifies the instructions for users by standardizing the image source. --- docs/how-tos/chain-events/quick-start.md | 12 ++++++++++-- docs/how-tos/chain-events/registry-api.md | 2 +- docs/how-tos/chain-events/scaling.md | 4 ++-- 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/how-tos/chain-events/quick-start.md b/docs/how-tos/chain-events/quick-start.md index 39da51c..8947620 100644 --- a/docs/how-tos/chain-events/quick-start.md +++ b/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,7 +114,7 @@ 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** @@ -114,7 +122,7 @@ docker run -d \ ```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: diff --git a/docs/how-tos/chain-events/registry-api.md b/docs/how-tos/chain-events/registry-api.md index f282933..b93b0dd 100644 --- a/docs/how-tos/chain-events/registry-api.md +++ b/docs/how-tos/chain-events/registry-api.md @@ -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** diff --git a/docs/how-tos/chain-events/scaling.md b/docs/how-tos/chain-events/scaling.md index b7926f3..7c93135 100644 --- a/docs/how-tos/chain-events/scaling.md +++ b/docs/how-tos/chain-events/scaling.md @@ -55,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: @@ -107,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" } ], From cac34a91257b33077309a9bfc3e9d8f634be24b9 Mon Sep 17 00:00:00 2001 From: manishdex25 Date: Wed, 3 Jun 2026 13:33:36 +0530 Subject: [PATCH 6/6] docs: update warning about database requirement in registry API documentation Changed the note regarding database requirements to a warning to better emphasize the necessity of configuring `DB_HOST` for registry management endpoints. This update enhances clarity for users regarding the implications of not having a connected database. --- docs/how-tos/chain-events/registry-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-tos/chain-events/registry-api.md b/docs/how-tos/chain-events/registry-api.md index b93b0dd..7efd6ff 100644 --- a/docs/how-tos/chain-events/registry-api.md +++ b/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. :::