Deploy and Host HyperDX 2.43.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

HyperDX app and collector, both pinned to 2.43.0.
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.

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.

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.
Image tags are pinned. 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 ingestion/querying; it is not a load, high-availability, or full-feature certification.

Validation

RailGenius validated first-user registration, authenticated API access, rejection of unauthenticated collector requests, authenticated OTLP log ingestion, and retrieval of the same log from ClickHouse through the HyperDX app. A clean installation of the generated template is checked before publication.

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.