Deploy and Host HyperDX 2.44.0 on Railway

Deploy HyperDX, the open-source interface behind ClickStack, with a dedicated OpenTelemetry collector, ClickHouse telemetry storage, and MongoDB metadata storage. This RailGenius template uses official container images and preconfigures the database connections and the Logs, Traces, Metrics, and Sessions sources.

About Hosting HyperDX

ClickStack app (HyperDX) and collector, both pinned to the official 2.44.0 image digests.
ClickHouse 26.8.36.3-alpine, with a persistent volume at /var/lib/clickhouse.
MongoDB 5.0.32-focal, matching the upstream HyperDX deployment configuration, with persistent storage at /data/db and authenticated access over the private network.
Separate public HTTPS domains for the dashboard and OTLP/HTTP collector. Databases have no public domain or TCP proxy.
Fresh database passwords, a session-signing secret, and a 32-byte hex integration-token encryption key generated separately for each deployment.
Preconfigured service references, so there are no provider API keys to supply before deploying.

Common Use Cases

Search application logs and jump from an error to its distributed trace.
Collect OpenTelemetry logs, traces, and metrics from services in one workspace.
Investigate browser session replay alongside backend telemetry.
Keep telemetry in a self-hosted ClickHouse database you can query with SQL.

Dependencies for HyperDX Hosting

All four infrastructure services are included. You need a Railway workspace able to run the stack and an application instrumented with OpenTelemetry to supply useful telemetry. No third-party monitoring subscription is required for this deployment.

Deployment Dependencies

Why Deploy HyperDX on Railway?

This template wires the app, collector, and databases together using Railway private networking and generated secrets. Separate services let you inspect logs and adjust resources individually, while managed HTTPS domains expose the dashboard and authenticated ingestion endpoint. You retain responsibility for access, data retention, backups, and infrastructure costs.

First login

Deploy the template and wait for all four services to start.
Open the generated domain on the app service.
Register your first user promptly. That user creates and owns the team. This template does not ship a shared admin password or a pre-created user.
In Team Settings, copy the ingestion API key.

Create your account before sending telemetry. The collector receives its authenticated pipeline configuration from the app using OpAMP. Before the first team exists, the collector container may be running while its ingestion ports are not yet available. Allow a short interval after registration for the configuration to propagate.

Already configured

No manual database creation, ClickHouse connection entry, collector configuration file, infrastructure-secret generation or custom domain is needed for a fresh install. Keep the generated service references and configured sources intact. You still need to register the first owner, obtain the team ingestion key, and instrument your application. The collector domain is an ingestion endpoint, not a second dashboard.

Send telemetry

For an OpenTelemetry SDK sending from outside this Railway project:

OTEL_EXPORTER_OTLP_ENDPOINT=https://YOUR-COLLECTOR-DOMAIN
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=authorization=YOUR-INGESTION-API-KEY

For services in the same Railway environment, use private networking:

OTEL_EXPORTER_OTLP_ENDPOINT=http://${{otel-collector.RAILWAY_PRIVATE_DOMAIN}}:4318

Keep the protocol and authorization header configured. Standard OTLP/HTTP paths are /v1/logs, /v1/traces, and /v1/metrics. OTLP/gRPC is available on port 4317 inside the private network; the generated public collector domain routes HTTP on port 4318.

What changed in 2.44.0

HyperDX’s own telemetry now uses standard OpenTelemetry keys such as http.request.method, http.response.status_code, and url.full. Browser identity uses user.id, user.email, and user.name. Browser console output is sent as logs. The navigation event and capture of browser request and response headers and bodies were removed. Browser sessions restart once when upgrading an existing installation.

Browser logs and traces now use gzip compression. If you send them to a custom collector or proxy, allow authorization, content-type, and content-encoding in CORS and forward Content-Encoding unchanged. Review the linked release notes before updating dashboards or alerts that query HyperDX’s own telemetry.

Costs, retention, and backups

This is a four-service stack with databases running continuously. It has a baseline resource cost even when no telemetry is arriving. ClickHouse CPU, memory, and persistent storage grow with ingestion, retention, session replay, and query workload. Railway bills infrastructure separately from any external tools you connect.

Before sending production traffic, set appropriate telemetry retention and SDK sampling, then watch workspace usage. Review the actual table TTLs after initialization; this template does not impose a custom retention policy. Session replay can substantially increase data volume. Avoid sending secrets or personal information in logs.

Volumes persist across container restarts, but persistence is not a backup. Configure and test independent backups for both ClickHouse and MongoDB. Deleting your deployed project removes the running stack and its data; keep backups before doing so.

Operations and limitations

MongoDB uses the official initialization entrypoint with IPv6 and a data directory inside the mounted volume. Keep this startup command intact so fresh installations create the authenticated database user.
The app healthcheck calls /api/installation, which queries MongoDB. A healthy dashboard alone does not prove that ingestion is working; send and query a sample event after installation.
The collector has no Railway HTTP healthcheck on its routed ingestion port because unauthenticated requests receive 401. This does not indicate a failed collector.
Register the first owner immediately after deployment. Review access controls and backup requirements before production use.
MongoDB 5.0 is retained for compatibility with the upstream deployment configuration. Review its support lifecycle and your organization’s requirements before adopting this stack for sensitive production workloads.
The app and collector are pinned by digest. Existing installations are not silently upgraded when this template changes. Review upstream release notes and database migration requirements before updating.
Session replay and metrics sources are configured, but the validation described below covers login and log and trace ingestion and querying; it is not a load, high-availability, or full-feature certification.

Validation

RailGenius validated first-user registration and login, browser CORS preflight, authenticated gzip OTLP log and trace ingestion, rejection without an ingestion key, and retrieval of the stored events through the HyperDX app. The same events remained queryable after ClickHouse, MongoDB, and the app restarted. These checks passed on two independent fresh deployments.

Attribution and support

HyperDX is developed by its upstream maintainers. This is an independently maintained Railway deployment template by RailGenius, with service wiring initially adapted from the Two Workspaces marketplace template. RailGenius is not an official HyperDX or ClickHouse representative.

Report application issues upstream; use this template’s Railway discussion for deployment-specific problems.