Skip to content

oss.md

Latest commit

 

History

History
139 lines (93 loc) · 6.53 KB

oss.md

File metadata and controls

139 lines (93 loc) · 6.53 KB
slug /use-cases/observability/clickstack/getting-started/oss
title Getting Started with Open Source ClickStack
sidebar_label Open Source
pagination_prev
pagination_next use-cases/observability/clickstack/example-datasets/index
description Getting started with Open Source ClickStack
doc_type guide
keywords
ClickStack Open Source
getting started
Docker deployment
HyperDX UI
local deployment

import Image from '@theme/IdealImage'; import hyperdx_login from '@site/static/images/use-cases/observability/hyperdx-login.png'; import hyperdx_logs from '@site/static/images/use-cases/observability/hyperdx-logs.png'; import hyperdx from '@site/static/images/use-cases/observability/hyperdx-1.png'; import hyperdx_2 from '@site/static/images/use-cases/observability/hyperdx-2.png'; import add_connection from '@site/static/images/use-cases/observability/add_connection.png'; import hyperdx_cloud from '@site/static/images/use-cases/observability/hyperdx-cloud.png'; import edit_cloud_connection from '@site/static/images/use-cases/observability/edit_cloud_connection.png'; import delete_source from '@site/static/images/use-cases/observability/delete_source.png'; import delete_connection from '@site/static/images/use-cases/observability/delete_connection.png'; import created_sources from '@site/static/images/use-cases/observability/created_sources.png'; import edit_connection from '@site/static/images/use-cases/observability/edit_connection.png'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

To deploy ClickStack Open Source, where you run and manage ClickHouse and the ClickStack UI yourself, we provide prebuilt Docker images that bundle the UI, an OpenTelemetry collector, and ClickHouse into a single container - making local development, testing, and self-managed deployments straightforward to get started.

These images are based on the official ClickHouse Debian package and are available in multiple distributions to suit different use cases.

The simplest option is a single-image distribution that includes all core components of the stack bundled together:

  • HyperDX UI
  • OpenTelemetry (OTel) collector
  • ClickHouse

This all-in-one image allows you to launch the full stack with a single command, making it ideal for testing, experimentation, or quick local deployments.

Deploy the stack with docker {#deploy-stack-with-docker}

The following will run an OpenTelemetry collector (on port 4317 and 4318), the HyperDX UI (on port 8080) and ClickHouse (8123).

docker run --name clickstack -p 8123:8123 -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest clickstack

:::note Image Name Update ClickStack images are now published as clickhouse/clickstack-* (previously docker.hyperdx.io/hyperdx/*). :::

:::tip Persisting data and settings To persist data and settings across restarts of the container, you can modify the above docker command to mount the paths /data/db, /var/lib/clickhouse and /var/log/clickhouse-server.

For example:

# modify command to mount paths
docker run \
  --name clickstack \
  -p 8123:8123 \
  -p 8080:8080 \
  -p 4317:4317 \
  -p 4318:4318 \
  -v "$(pwd)/.volumes/db:/data/db" \
  -v "$(pwd)/.volumes/ch_data:/var/lib/clickhouse" \
  -v "$(pwd)/.volumes/ch_logs:/var/log/clickhouse-server" \
  clickhouse/clickstack-all-in-one:latest

:::

Navigate to the ClickStack UI {#navigate-to-hyperdx-ui}

Visit http://localhost:8080 to access the ClickStack UI (HyperDX).

Create a user, providing a username and password that meets the complexity requirements.

HyperDX UI

HyperDX will automatically connect to the local cluster and create data sources for the logs, traces, metrics, and sessions - allowing you to explore the product immediately.

Explore the product {#explore-the-product}

With the stack deployed, try one of our same datasets.

To continue using the local cluster:

  • Example dataset - Load an example dataset from our public demo. Diagnose a simple issue.
  • Local files and metrics - Load local files and monitor system on OSX or Linux using a local OTel collector.

Alternatively, you can connect to a demo cluster where you can explore a larger dataset:

Alternative deployment models {#alternative-deployment-models}

Local mode {#local-mode}

Local mode is a way to deploy HyperDX without needing to authenticate.

Authentication is not supported.

This mode is intended to be used for quick testing, development, demos and debugging use cases where authentication and settings persistence is not necessary.

For further details on this deployment model, see "Local Mode Only".

Hosted version {#hosted-version}

You can use a hosted version of ClickStack in local mode available at play-clickstack.clickhouse.com.

Self-hosted version {#self-hosted-version}

Run with docker {#run-local-with-docker}

The self-hosted local mode image comes with an OpenTelemetry collector, the ClickStack UI and a ClickHouse server pre-configured as well. This makes it easy to consume telemetry data from your applications and visualize it with minimal external setup. To get started with the self-hosted version, simply run the Docker container with the appropriate ports forwarded:

docker run -p 8080:8080 clickhouse/clickstack-local:latest

Unlike the "All in one" image, you will not be promoted to create a user as local mode does not include authentication.

Complete connection credentials {#complete-connection-credentials}

To connect to your own external ClickHouse cluster, you can manually enter your connection credentials.

Alternatively, for a quick exploration of the product, you can also click Connect to Demo Server to access preloaded datasets and try ClickStack with no setup required.

Credentials

If connecting to the demo server, you can explore the dataset with the demo dataset instructions.