Skip to content

DEPLOY.md

Latest commit

 

History

History
85 lines (62 loc) · 3.43 KB

DEPLOY.md

File metadata and controls

85 lines (62 loc) · 3.43 KB
Raw

HyperDX Deployment Guide

HyperDX helps engineers quickly figure out why production is broken by making it easy to search & visualize logs and traces on top of any ClickHouse cluster (imagine Kibana, for ClickHouse). You can learn more about HyperDX in our README.

HyperDX can be deployed in a few different ways:

Bring Your Own ClickHouse

If you already have an existing ClickHouse cluster, you can simply deploy a HyperDX container that connects to your ClickHouse cluster. You'll need a separate MongoDB instance to persist your users, dashboards, searches and more.

To get started, you can run the following image:

docker run -e MONGO_URI=mongodb://YOUR_MONGODB_URI -p 8080:8080 docker.hyperdx.io/hyperdx/hyperdx:2-beta

You'll need to set the MONGO_URI environment variable to the URI of your MongoDB instance. Afterwards, you'll want to visit http://localhost:8080 to set up your connection with ClickHouse.

Before deploying into production, set the EXPRESS_SESSION_SECRET environment variable to a random string (e.g. openssl rand -hex 32). Without it the API generates one per process, which signs users out on every restart and prevents replicas from sharing sessions. The old public value hyperdx is cool 👋 is also replaced with a per-process secret when authentication is enabled.

To customize the frontend URL, set the FRONTEND_URL environment variable to the URL your HyperDX instance is hosted on.

All-in-one Docker Compose Stack

The easiest way to get started with HyperDX from scratch is to use our all-in-one Docker Compose stack. This stack will start ClickHouse, an OpenTelemetry collector, and HyperDX with a MongoDB instance.

To get started, clone this repository and run the following command:

docker compose up -d

This will start the HyperDX stack and open a port for the UI, API, and OTel collector.

When deploying into production, you'll want to disable any extra ports outside of the otel collector and api container. Beware that exposing any port in Docker Compose will make it publicly accessible even when using iptable-based firewalls such as ufw. See the Docker docs for more information.

Generate a secret once with openssl rand -hex 32, then set EXPRESS_SESSION_SECRET=<generated value> in .env.local, which Git ignores. Do not put the secret in the tracked root .env. Compose forwards this value to the app container when you load .env.local after .env:

docker compose --env-file .env --env-file .env.local up -d

Reuse the same secret across restarts and all replicas. Without it the API generates one per process, which signs users out on every restart and prevents replicas from sharing sessions. The old public value is not a production secret.

Local Development Mode

HyperDX can also be deployed alongside your existing local development stack to help you debug issues locally. This mode will start an OpenTelemetry collector, ClickHouse, and HyperDX with a MongoDB in a single instance, without any authentication or configuration persistence.

To get started, spin up the local mode container:

docker run -p 8080:8080 docker.hyperdx.io/hyperdx/hyperdx-local:2-beta