---
title: "Deploy HyperDX"
description: "Search your app's logs, traces and metrics in one place"
category: "Observability"
url: https://railway.com/deploy/hyperdx-otel
---

# Deploy HyperDX

Search your app's logs, traces and metrics in one place

**[Deploy HyperDX on Railway](https://railway.com/template/hyperdx-otel)**

- **Creator:** A3A
- **Category:** Observability

## Template content

### MongoDB https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/mongodb.svg

- **Image:** mongo:8.0
- **Start command:** `docker-entrypoint.sh mongod --ipv6 --bind_ip ::,0.0.0.0 --setParameter diagnosticDataCollectionEnabled=false`

### clickhouse https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/clickhouse.svg

- **Source:** https://github.com/gridalpha/hyperdx-railway
- **Health check:** /ping

### hyperdx https://raw.githubusercontent.com/hyperdxio/hyperdx/main/packages/app/public/favicons/hyperdx/favicon.svg

- **Source:** https://github.com/gridalpha/hyperdx-railway
- **Health check:** /ready
- **Public domain:** Yes

### otel-collector https://raw.githubusercontent.com/open-telemetry/opentelemetry.io/main/static/img/logos/opentelemetry-icon-color.png

- **Image:** clickhouse/clickstack-otel-collector:2.37.0
- **Start command:** `/bin/sh -c 'case "$CLICKHOUSE_ENDPOINT" in ""|tcp://:*) CLICKHOUSE_ENDPOINT="tcp://clickhouse.railway.internal:9000?dial_timeout=10s";; esac; case "$OPAMP_SERVER_URL" in ""|http://:*) OPAMP_SERVER_URL="http://hyperdx.railway.internal:4320";; esac; export CLICKHOUSE_ENDPOINT OPAMP_SERVER_URL; echo "collector: clickhouse=$CLICKHOUSE_ENDPOINT opamp=$OPAMP_SERVER_URL"; exec /entrypoint.sh /opampsupervisor'`
- **Health check:** /
- **Public domain:** Yes

## Documentation

# Deploy and Host HyperDX on Railway

HyperDX is an open-source observability platform that puts logs, traces, metrics and browser session replay behind one search box. Built on ClickHouse and natively OpenTelemetry, it takes OTLP from any service without a vendor agent. Engineers use it the way they would use Datadog — search a log line, jump to the trace that produced it, watch the session that triggered it — on infrastructure they own. MIT licensed, developed by ClickHouse as ClickStack.

Self-host HyperDX on Railway and you get the production topology, not a demo container: the **hyperdx** app (API, UI and alert evaluator), an **otel-collector** terminating OTLP, a **ClickHouse** server holding every log, span and metric point on a volume, and a managed **MongoDB** for accounts and dashboards. Your services send telemetry to the collector over HTTP or gRPC, it writes into ClickHouse, and the app queries ClickHouse on demand. Only the UI and the ingest endpoint face the internet.

![Diagram of the HyperDX, collector, ClickHouse and MongoDB services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1788302772/hyperdx-architecture.png)

## Getting Started with HyperDX on Railway

Open the **hyperdx** service's public URL once the deployment goes green. There are no default credentials: the first visitor gets a setup page and creates the owner account with an email and a password of at least 12 characters including upper, lower, digit and symbol. Register straight away — that sign-up creates the team and permanently closes registration. It also seeds the ClickHouse connection and four data sources (Logs, Traces, Metrics, Sessions) against tables the collector already created.

Then get telemetry in. Copy the ingestion API key from **Team Settings → API & Agents** and point any OpenTelemetry SDK or Collector at the **otel-collector** domain for OTLP/HTTP, or its TCP proxy for OTLP/gRPC. Send the key as the `Authorization` header; without it requests get a 401, which is what makes a public ingest endpoint safe to leave running. Within seconds **Search** lists events, and clicking a row offers *View Trace*.

![HyperDX log search listing events from three instrumented services](https://res.cloudinary.com/rroe4rtk/image/upload/v1788302775/hyperdx-log-search.png)

![HyperDX service dashboard charting error rate, throughput and latency](https://res.cloudinary.com/rroe4rtk/image/upload/v1788302777/hyperdx-service-dashboard.png)

![HyperDX trace waterfall with correlated logs and span attributes](https://res.cloudinary.com/rroe4rtk/image/upload/v1788302782/hyperdx-trace-waterfall.png)

## About Hosting HyperDX

Most observability tooling makes you pick a silo: one product for logs, another for traces, a third for front-end monitoring, and copy-pasting trace IDs between them. HyperDX keeps all of it in one ClickHouse database, linked by trace and session ID, so debugging is one continuous thread. Self-hosting matters because telemetry is the largest and most sensitive stream most teams produce, and its volume is what makes SaaS pricing painful. SigNoz is the closest open-source comparison; the Grafana stack has more components and more query languages.

Key features:

- Lucene and full-text log search with no index schema to define up front
- Distributed tracing with a span waterfall and correlated log lines
- OpenTelemetry metrics: gauges, sums, histograms, exponential histograms
- Browser session replay linked to backend traces from the same session
- Alerts on saved searches and chart thresholds, by webhook or Slack
- A chart builder that compiles to plain ClickHouse SQL

**ClickHouse** owns the volume at `/var/lib/clickhouse`, and the collector runs its schema migrations at boot so tables exist before the first byte arrives. **MongoDB** stores what people create — dashboards, saved searches, alert rules and sessions — which is why signing in survives a redeploy. The **otel-collector** is the only writer to ClickHouse, configured remotely by the app over OpAMP.

## Why Deploy HyperDX on Railway

Railway removes the parts of running an observability stack that are not observability:

- Four services deploy together, wired over the private network
- ClickHouse gets a persistent volume; MongoDB is fully managed
- UI and OTLP ingest endpoint get HTTPS domains automatically
- A TCP proxy carries OTLP/gRPC, which an HTTP edge cannot
- Health checks and restart policies configured per service
- You pay for compute and storage, not per gigabyte ingested

## Common Use Cases

- Replacing a Datadog or New Relic contract, keeping 30 days of logs and traces at storage cost, not per-GB ingest pricing
- Debugging incidents end to end: search an error, open its trace, watch the replay
- Giving a microservice fleet one OTLP endpoint, with API keys gating writes
- Long-retention audit queries over structured logs, as ordinary ClickHouse SQL

## Dependencies for HyperDX

- **hyperdx** — `hyperdx/hyperdx:2.37.0`. API, UI and alert evaluator in one container; the UI proxies `/api/*` internally, so one domain serves it all.
- **otel-collector** — `clickhouse/clickstack-otel-collector:2.37.0`. OpenTelemetry Collector with a ClickHouse exporter, supervised over OpAMP. It also runs the schema migrations.
- **clickhouse** — `clickhouse/clickhouse-server:26.8-alpine`. Columnar store for every signal, 30-day table TTL by default.
- **MongoDB** — managed `mongo:8.0`. Application metadata and session store.

Source: [hyperdxio/hyperdx](https://github.com/hyperdxio/hyperdx), plus a small deployment repository holding the two Dockerfiles this template builds.

### Environment Variables Reference

| Variable | Service | Purpose |
|---|---|---|
| `EXPRESS_SESSION_SECRET` | hyperdx | Signs session cookies; generated for you |
| `MONGO_URI` | hyperdx | MongoDB connection string with `?authSource=admin` |
| `CLICKHOUSE_HOST` / `CLICKHOUSE_USER` / `CLICKHOUSE_PASSWORD` | hyperdx, otel-collector | ClickHouse endpoint and credentials |
| `HYPERDX_OTEL_EXPORTER_TABLES_TTL` | otel-collector | Retention window, `720h` by default |
| `FRONTEND_URL` | hyperdx | Public origin; set only for a custom domain |
| `AI_PROVIDER` / `AI_API_KEY` | hyperdx | Optional AI query assistant |

### Deployment Dependencies

- Runtime: Node.js 22, Go, ClickHouse 26.8 LTS, MongoDB 8
- Images: [hyperdx/hyperdx](https://hub.docker.com/r/hyperdx/hyperdx), [clickhouse/clickstack-otel-collector](https://hub.docker.com/r/clickhouse/clickstack-otel-collector)
- Docs: [ClickStack documentation](https://clickhouse.com/docs/use-cases/observability/clickstack)

## Hardware Requirements for Self-Hosting HyperDX

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 vCPU | 4–8 vCPU, mostly ClickHouse |
| RAM | 4 GB | 8 GB+ (ClickHouse likes 4 GB) |
| Storage | 5 GB volume | 20 GB+, ingest rate × retention |
| Runtime | Linux container | — |

Idle usage is roughly 450 MB app, 250 MB collector, 700 MB ClickHouse, 150 MB MongoDB. Scale ClickHouse first — it reads its container limits correctly, so more memory buys more query and merge headroom.

## Self-Hosting HyperDX with Docker

The quickest local trial is the all-in-one image, bundling ClickHouse, MongoDB and the collector. Run it with Docker:

```
docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:2
```

For anything real, split the components — the app image alone, pointed at an existing ClickHouse cluster and its own MongoDB:

```
docker run -d --name hyperdx -p 8080:8080 \
  -e MONGO_URI="mongodb://mongo:27017/hyperdx" \
  -e EXPRESS_SESSION_SECRET="$(openssl rand -hex 32)" \
  -e FRONTEND_URL="https://hyperdx.example.com" \
  hyperdx/hyperdx:2.37.0
```

The four-service compose file lives upstream; this template is that stack with wiring, health checks and volumes already done.

## How Much Does HyperDX Cost to Self-Host?

HyperDX is free and open source under the MIT licence — no paid self-hosted edition, no feature gate. HyperDX Cloud is a managed alternative from around $20/month, but nothing here calls it. Self-hosting on Railway costs infrastructure only: four containers plus a ClickHouse volume, billed on usage. ClickHouse compresses telemetry hard, so CPU is usually the larger line item.

## FAQ

**What is HyperDX?**
An open-source observability platform for logs, traces, metrics and session replay, built on ClickHouse and OpenTelemetry. MIT licensed, developed by ClickHouse as ClickStack.

**What does this Railway template deploy?**
Four services: the app, an OpenTelemetry Collector for ingest, a ClickHouse server with a volume, and a managed MongoDB — pre-wired privately, with only the app and ingest endpoint public.

**Why does the template include ClickHouse and MongoDB?**
They store different things. ClickHouse holds the telemetry — every log line, span and metric point — and is what makes searching billions of rows fast. MongoDB holds application state: accounts, dashboards, saved searches, alert rules and sessions.

**How do I send OpenTelemetry data to self-hosted HyperDX?**
Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the collector's public URL and `OTEL_EXPORTER_OTLP_HEADERS` to `authorization=`, then use any OTLP exporter. HTTP goes to the domain, gRPC through the TCP proxy.

**Is the OTLP ingest endpoint safe to expose publicly?**
Yes. The team created on first sign-up enables collector authentication, so the receivers require the API key and answer 401 without it. Rotate the key from Team Settings; the collector picks it up without a restart.

**How long is telemetry kept?**
Thirty days by default, as a TTL on the ClickHouse tables via `HYPERDX_OTEL_EXPORTER_TABLES_TTL`. Any Go duration works — `2160h` for 90 days — resize the volume to match.


## Similar templates

- [Pyroscope profiling](https://railway.com/deploy/pyroscope-profiling) — Protected continuous profiling with durable Pyroscope storage.
- [SigOnly](https://railway.com/deploy/sigonly) — Deploy SigNoz with a working demo app & config in one click
- [Unwrapped Spotify Music Stats](https://railway.com/deploy/wide-bold) — Unwrapped Spotify Music Stats, Estatísticas de músicas disponíveis

Open this page in a browser: https://railway.com/deploy/hyperdx-otel