Operations
@nx/searchhas no independent deployment. It runs inside the host (commerce) container and shares its lifecycle, replicas, and resources. Operating it means operating Typesense, the Debezium connector, and the CDC consumer running in commerce.
1. Deployment
| Property | Value |
|---|---|
| Image | N/A — packaged into the commerce image |
| Replicas | N/A — equals commerce replicas |
| Resources | Adds Kafka consumer + Typesense client memory to the host |
| Probes | Host probes; TypesenseHelper.getHealth() gates collection sync + circuit breaker |
| Migration mode | On-boot schema-drift check (no auto-apply); manual backfill scripts for changes |
| Snowflake ID range | N/A |
Dependencies that must be reachable
| Dependency | Required for | If down |
|---|---|---|
| Typesense | search + indexing | Bootstrap skips collection sync (logs warn); circuit breaker pauses CDC |
| Kafka + Debezium | CDC sync | Index stops updating; consumer reconnects; offsets uncommitted |
No Traefik labels — the routes mount under the host service's base path (
/v1/api/commerce/...).
2. Observability
| Signal | Source | Where to look |
|---|---|---|
| Logs | Host stdout (structured key-value) | commerce pod logs — filter component scopes (ApplicationCdcComponent, TypesenseSearchEngineComponent) |
| CDC startup | log line Starting CDC consumer | Brokers… | DLQ… | CircuitBreaker… | confirms topics + breaker state |
| Schema sync | log Schema divergence detected | Collection: … | indicates manual migration needed |
| Indexing throughput | SearchIndexingService batch metrics | log fields per batch |
| Health | TypesenseHelper.getHealth() | breaker probe + bootstrap gate |
Sync diagnostic
| Operation | Command |
|---|---|
| Check Typesense ↔ source row counts | scripts/check_sync_status.sh |
| Dry-run reference backfill | bun run migrate:references:dry |
| Dry-run denorm backfill | bun run migrate:denorm:dry |
3. Security
| Concern | Mitigation |
|---|---|
| AuthN | Search routes inherit host JWT/Basic (AuthenticateStrategy.JWT, .BASIC) |
| AuthZ | search:search / search:search-count; mixin requires consumer authorize config |
| Tenant isolation | resolveSearchScope() and-merges a where scope into every query |
| Typesense API key | APP_ENV_TYPESENSE_API_KEY from host secrets; never in code |
| Kafka SASL | APP_ENV_KAFKA_SASL_* when broker requires auth |
| No client writes | Documents mutated only via CDC — no public write API |
4. Runbook
4.1 Alert classes
| Alert | Trigger | Check | Fix | Escalate |
|---|---|---|---|---|
searchSchemaDivergence | log Schema divergence detected on boot | Compare config vs live Typesense schema | Run backfill script for additive change; recreate collection only if data-loss-safe | backend on-call |
searchCdcLag | CDC consumer falling behind / circuit OPEN | Typesense health, Kafka consumer-group lag | Recover Typesense; breaker closes after quiet window | SRE on-call |
searchDlqGrowth | messages accumulating in nx.seller.cdc.dlq | Inspect DLQ payloads + failure metadata | Fix mapper/data, replay from DLQ | backend on-call |
searchStale | results missing recently-changed rows | scripts/check_sync_status.sh | Backfill or replay affected topics | backend on-call |
4.2 Common operations
| Operation | Command / Action |
|---|---|
| Tail CDC logs | kubectl logs -f deploy/commerce | grep -E 'Cdc|Typesense' |
| Verify sync counts | bun run check_sync_status (or scripts/check_sync_status.sh) |
| Backfill references / denorm | bun run migrate:references / bun run migrate:denorm |
| Reindex after schema change | Recreate the diverged collection (data-loss-safe window) then backfill |
| Replay a CDC topic | Reset the Debezium connector / consumer-group offsets (infra-owned) |
5. Related Pages
- Configuration
/runbook/— central runbook for cross-service incidents- Decisions