Repository navigation
[HDX-2712] Unified hyperdx entrypoint script for API and tasks - #1951
Merged
kodiakhq[bot] merged 9 commits intoMar 20, 2026
Merged
kodiakhq[bot] merged 9 commits into
kodiakhq[bot] merged 9 commits into
Conversation
Replace duplicated node startup commands across Dockerfiles and entry scripts with a single `packages/api/bin/hyperdx` shell script. This script is the sole place that knows the build output layout and required node flags, so future build changes (like the esbuild introduction/revert that caused HDX-2690) only need updating in one place. The script supports two subcommands: - `hyperdx api` - starts the API server - `hyperdx task <name>` - runs a named task (e.g., check-alerts) Made-with: Cursor
🦋 Changeset detectedLatest commit: dc36740 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Made-with: Cursor
Contributor
E2E Test Results✅ All tests passed • 92 passed • 3 skipped • 931s
Tests ran across 4 shards in parallel. |
Contributor
PR Review✅ No critical issues found. The new
Docker changes look correct — |
The start script is not used by any Docker or CI path, so keep it as the plain node command to avoid silently adding OTel tracing. Made-with: Cursor
Made-with: Cursor
…-for-both-hyperdx-api-and
Made-with: Cursor
dhable
requested review from
a team and
pulpdrew
and removed request for
a team
March 20, 2026 15:58
…-for-both-hyperdx-api-and
The hyperdx script is referenced by full path in all Dockerfiles and entry scripts. The bin field only adds a node_modules/.bin symlink that nothing uses, and it requires a yarn.lock update. Made-with: Cursor
Remove bin field and revert any lockfile drift so these files have no diff against main. Made-with: Cursor
pulpdrew
approved these changes
Mar 20, 2026
kodiakhq
Bot
deleted the
dan/hdx-2712-use-a-single-entry-point-script-for-both-hyperdx-api-and
branch
March 20, 2026 18:27
knudtty
pushed a commit
that referenced
this pull request
Apr 16, 2026
## Summary
The node commands to start the API server and alert task are duplicated across 4+ files, each hardcoding the build output path and node require flags. When the build process changed (esbuild introduction/revert per HDX-2690), the downstream operator and helm chart broke because their entrypoint commands were stale.
This PR introduces `packages/api/bin/hyperdx`, a single shell script that is the **sole source of truth** for how to launch API and task processes. It resolves the build directory relative to its own location, applies the correct node flags (`-r @hyperdx/node-opentelemetry/build/src/tracing`), and exposes two subcommands:
- `hyperdx api` -- starts the API server
- `hyperdx task <name>` -- runs a named task (e.g., `check-alerts`)
All Dockerfiles and entry scripts now delegate to this script instead of inlining the node command. Future build changes only need updating in one place.
### How to test locally or on Vercel
1. **Build the standalone API image** and confirm the entrypoint works:
```bash
docker build . -f packages/api/Dockerfile -t hyperdx-api-test:latest --target prod
docker run -d --name hdx-api-test -p 18000:8000 hyperdx-api-test:latest
sleep 5
docker logs hdx-api-test 2>&1 | head -30
# Should show OpenTelemetry init + MongoStore error (expected without Mongo)
# No "file not found" or "permission denied" errors
docker stop hdx-api-test && docker rm hdx-api-test
```
2. **Build and run the all-in-one image** for a full integration test:
```bash
make build-local
docker run -d --name hdx-aio-test -p 18080:8080 -p 18000:8000 hyperdx/hyperdx-local:2.21.0
# Wait up to 90s for startup, then:
curl -sf http://localhost:18080/api/health # should return {"data":"OK",...}
curl -sf http://localhost:18000/health # should return {"data":"OK",...}
docker exec hdx-aio-test sh -c "ps aux"
# Confirm API, APP, and ALERT-TASK processes are running via the hyperdx script
docker stop hdx-aio-test && docker rm hdx-aio-test
```
3. **Build the prod image** to confirm the entry script changes are valid:
```bash
make build-app
```
**Testing performed:** All three Docker image targets were built and verified locally. The standalone API image started node via `hyperdx api` correctly (crashed on missing MongoDB as expected). The all-in-one image passed health checks on both `localhost:18080/api/health` and `localhost:18000/health`, with all three processes (API, APP, ALERT-TASK) confirmed running inside the container using the new entry point script.
### References
- Linear Issue: [HDX-2712](https://linear.app/clickhouse/issue/HDX-2712/use-a-single-entry-point-script-for-both-hyperdx-api-and-alert-job)
- Related PRs: HDX-2690 (root cause), HDX-2815 (downstream helm chart follow-up)
- **Follow-up needed:** Update helm chart cron job template and operator template in `ClickHouse/ClickStack-helm-charts` to use `./packages/api/bin/hyperdx task check-alerts`
Made with [Cursor](https://cursor.com)
wrn14897
added a commit
to ClickHouse/ClickStack-helm-charts
that referenced
this pull request
Nov 9, 2026
## Summary The `check-alerts` CronJob started its container with `node /app/packages/api/build/tasks/index.js check-alerts`. That bypasses `bin/hyperdx`, the entrypoint the image itself uses in `entry.prod.sh`, so the task never loaded a self-telemetry preload and `OTEL_SERVICE_NAME=hdx-oss-task-check-alerts` was dead config. ClickHouse/ClickStack#3575 swaps the self-instrumentation SDK for `@clickhouse/clickstack-node`, and the preload path moves with it. Mirroring DeploySentinel/hyperdx-operator#314, the CronJob now runs `/app/packages/api/bin/hyperdx task check-alerts` so the image picks its own preload and the chart stops caring where it lives. Linear: [HDX-5951](https://linear.app/hyperdx/issue/HDX-5951) ## Changes - `templates/hyperdx/cronjob-check-alerts.yaml`: the command switch now has three branches, keyed on the image tag: - `< 2.7.0`: `node /app/packages/api/tasks/index check-alerts` (unchanged) - `>= 2.7.0, < 2.22.0`: `node /app/packages/api/build/tasks/index.js check-alerts` (unchanged) - `>= 2.22.0` or non-semver tag (`2-beta`, `latest`): `/app/packages/api/bin/hyperdx task check-alerts` (new; default `appVersion` 2.39.1 takes this path) - `additionalArgs` passthrough is preserved in every branch. - `tests/task-checkAlerts_test.yaml`: `2-beta` and `3.0.0` cases expect the new command; added boundary tests for `2.21.9`, `2.22.0`, the default tag, and `additionalArgs` on the new path. - Changeset (patch). ## Compatibility `bin/hyperdx` first ships in HyperDX 2.22.0 (ClickHouse/ClickStack#1951) and is copied into every stage of the all-in-one image. It `exec`s node so PID 1 and signal handling are unchanged. Post-#3575 the preload only starts the SDK when `HYPERDX_API_KEY` or `OTEL_EXPORTER_OTLP_HEADERS` is set; the chart sets `HYPERDX_API_KEY` by default, so the task starts exporting to the chart's collector like the API pod already does. ## Validation - `make test`: 286/286 - `make coverage`: 99.85% line, 91.19% branch - `helm template --set hyperdx.tasks.enabled=true --set hyperdx.tasks.checkAlerts.additionalArgs.concurrency=4` renders `["/app/packages/api/bin/hyperdx", "task", "check-alerts", "--concurrency", "4"]`
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The node commands to start the API server and alert task are duplicated across 4+ files, each hardcoding the build output path and node require flags. When the build process changed (esbuild introduction/revert per HDX-2690), the downstream operator and helm chart broke because their entrypoint commands were stale.
This PR introduces
packages/api/bin/hyperdx, a single shell script that is the sole source of truth for how to launch API and task processes. It resolves the build directory relative to its own location, applies the correct node flags (-r @hyperdx/node-opentelemetry/build/src/tracing), and exposes two subcommands:hyperdx api-- starts the API serverhyperdx task <name>-- runs a named task (e.g.,check-alerts)All Dockerfiles and entry scripts now delegate to this script instead of inlining the node command. Future build changes only need updating in one place.
How to test locally or on Vercel
Testing performed: All three Docker image targets were built and verified locally. The standalone API image started node via
hyperdx apicorrectly (crashed on missing MongoDB as expected). The all-in-one image passed health checks on bothlocalhost:18080/api/healthandlocalhost:18000/health, with all three processes (API, APP, ALERT-TASK) confirmed running inside the container using the new entry point script.References
ClickHouse/ClickStack-helm-chartsto use./packages/api/bin/hyperdx task check-alertsMade with Cursor