Getting started with ClickStack Open Source

Run ClickStack Open Source locally, send a test event through its OpenTelemetry Collector, and confirm that the event is available in the ClickStack UI. With ClickStack Open Source, you run and manage the ClickHouse backend, ClickStack UI, and ingestion pipeline. The all-in-one image bundles these components with MongoDB in a single Docker container for local evaluation and testing.

A managed version of ClickStack is also available — see Managed ClickStack.

The steps below use the authenticated all-in-one image. If you want a local UI without creating an account, follow the local mode with Docker walkthrough instead.

Before you begin

Install Docker and confirm that the following ports are available:

8080 for the ClickStack UI
4317 for OTLP over gRPC
4318 for OTLP over HTTP
8123 for the ClickHouse HTTP interface

For sustained or production workloads, review Open source deployment options and Going to production.

Set up ClickStack Open Source with the all-in-one image

Start ClickStack

Run the all-in-one image:

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

The container runs in the foreground. Leave this terminal open and use a second terminal for the remaining commands in this guide.

Persist data and settings

To retain ClickStack settings, ClickHouse data, and ClickHouse logs after removing the container, run the following command instead:

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

$(pwd) resolves to your current directory. This command stores the persistent files in a .volumes directory at that location.

Open ClickStack

After ClickStack starts, open http://localhost:8080 and create an account.ClickStack automatically connects to the bundled ClickHouse instance and creates data sources for logs, traces, metrics, and sessions.

Copy the ingestion API key

In the Get Started section of the left menu, select Add Data, then copy the Ingestion API Key. Telemetry sent to the bundled OpenTelemetry Collector must include this key in the authorization header.

Send test data

In the second terminal, export the ingestion API key:

export CLICKSTACK_API_KEY=<your_ingestion_api_key>

Send an OTLP log with the current timestamp:

NOW_NANO="$(date +%s)000000000"

curl -i "http://localhost:4318/v1/logs" \
  -H "Content-Type: application/json" \
  -H "authorization: ${CLICKSTACK_API_KEY}" \
  --data-binary @- <<EOF
{
  "resourceLogs": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {"stringValue": "clickstack-docs-test"}
      }]
    },
    "scopeLogs": [{
      "scope": {"name": "clickstack-docs-test"},
      "logRecords": [{
        "timeUnixNano": "${NOW_NANO}",
        "severityText": "INFO",
        "body": {"stringValue": "ClickStack ingestion test"}
      }]
    }]
  }]
}
EOF

A successful request returns HTTP/1.1 200 OK.

Confirm ingestion

Open the Search view in ClickStack and search for ClickStack ingestion test.The result should include the test event with the clickstack-docs-test service name.

You now have a local ClickStack instance, a working ingestion endpoint, and a test event that you can inspect in ClickStack.

Next steps

Send application and infrastructure data

Choose a guide for the data that you want to send to ClickStack:

Instrument an application

Send application traces and logs with a supported OpenTelemetry SDK.

Collect host logs

Forward host logs from an OpenTelemetry Collector running in the agent role.

Monitor Kubernetes

Collect logs, metrics, and traces from a Kubernetes cluster.

Explore other integrations

Find guides for additional applications and telemetry sources.

Explore sample data

Use a sample dataset to explore ClickStack with richer telemetry:

Sample logs, traces, and metrics

Load data from the public demo and diagnose an issue.

Local logs and metrics

Collect local files and system metrics on macOS or Linux.

To explore preloaded data without installing Docker, use the hosted ClickStack demo.

Generate synthetic data

Use a generator to test ingestion without an existing application or dataset:

Generate data with otelgen

Send a short burst of synthetic OTLP logs, traces, and metrics.

Generate data with telemetrygen

Generate configurable OpenTelemetry signals across several services.

See all ClickStack sample data and demos.

Prepare for production

Review deployment and production guidance before using ClickStack for sustained workloads:

Going to production

Review ingestion credentials, security, retention, and operational guidance.

Choose a deployment model

Compare open source deployment options for your environment.

Get started

Features

Managing ClickStack

Guides

Integration partners

Getting started with ClickStack Open Source

Before you begin

Set up ClickStack Open Source with the all-in-one image

Start ClickStack

Open ClickStack

Copy the ingestion API key

Send test data

Confirm ingestion

Next steps

Send application and infrastructure data

Instrument an application

Collect host logs

Monitor Kubernetes

Explore other integrations

Explore sample data

Sample logs, traces, and metrics

Local logs and metrics

Generate synthetic data

Generate data with otelgen

Generate data with telemetrygen

Prepare for production

Going to production

Choose a deployment model

​Before you begin

​Set up ClickStack Open Source with the all-in-one image

Start ClickStack

Open ClickStack

​Copy the ingestion API key

Send test data

Confirm ingestion

​Next steps

​Send application and infrastructure data

Instrument an application

Collect host logs

Monitor Kubernetes

Explore other integrations

​Explore sample data

Sample logs, traces, and metrics

Local logs and metrics

​Generate synthetic data

Generate data with otelgen

Generate data with telemetrygen

​Prepare for production

Going to production

Choose a deployment model

Before you begin

Set up ClickStack Open Source with the all-in-one image

Copy the ingestion API key

Next steps

Send application and infrastructure data

Explore sample data

Generate synthetic data

Prepare for production