[HDX-2712] Unified hyperdx entrypoint script for API and tasks

[dhable]

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:

   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:

   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:

   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
• 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

[changeset-bot]

🦋 Changeset detected

Latest commit: dc36740

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Patch
@hyperdx/app	Patch
@hyperdx/otel-collector	Patch

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Mar 20, 2026 4:35pm

[github-actions]

E2E Test Results

✅ All tests passed • 92 passed • 3 skipped • 931s

Status	Count
✅ Passed	92
❌ Failed	0
⚠️ Flaky	1
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

PR Review

✅ No critical issues found.

The new packages/api/bin/hyperdx shell script is clean and correctly structured:

• SCRIPT_DIR resolution using cd "$(dirname "$0")" && pwd is the correct POSIX approach
• Unquoted $NODE_REQUIRE_FLAGS for intentional word-splitting is properly documented with shellcheck disable
• shift 2>/dev/null || true correctly handles zero-arg invocations
• File is marked 100755 so Docker COPY will preserve executable bit
• exec is used correctly to replace the shell process

Docker changes look correct — bin/ is copied in both build and final stages, and the relative-path ENTRYPOINT resolves against the WORKDIR /app correctly.