Configuration Options

- **Default:** `8000`
  - **Description:** Port for the HyperDX API server.
  - **Guidance:**
  - Ensure this port is available on your host
  - Change if you have port conflicts
  - Must match the port in your API client configurations
- `HYPERDX_APP_PORT`

  - **Default:** `8000`
  - **Description:** Port for the HyperDX frontend app.
  - **Guidance:**
  - Ensure this port is available on your host
  - Change if you have port conflicts
  - Must be accessible from your browser
- `HYPERDX_APP_URL`

  - **Default:** `http://localhost`
  - **Description:** Base URL for the frontend app.
  - **Guidance:**
  - Set to your domain in production
  - Include protocol (http/https)
  - Don't include trailing slash
- `MONGO_URI`

  - **Default:** `mongodb://db:27017/hyperdx`
  - **Description:** MongoDB connection string.
  - **Guidance:**
  - Use default for local development with Docker
  - For production, use a secure connection string
  - Include authentication if required
  - Example: `mongodb://user:pass@host:port/db`
- `MINER_API_URL`

  - **Default:** `http://miner:5123`
  - **Description:** URL for the log pattern mining service.
  - **Guidance:**
  - Use default for local development with Docker
  - Set to your miner service URL in production
  - Must be accessible from the API service
- `FRONTEND_URL`

  - **Default:** `http://localhost:3000`
  - **Description:** URL for the frontend app.
  - **Guidance:**
  - Use default for local development
  - Set to your domain in production
  - Must be accessible from the API service
- `OTEL_SERVICE_NAME`

  - **Default:** `hdx-oss-api`
  - **Description:** Service name for OpenTelemetry instrumentation.
  - **Guidance:**
  - Use descriptive name for your HyperDX service. Applicable if HyperDX self-instruments.
  - Helps identify the HyperDX service in telemetry data
- `NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT`

  - **Default:** `http://localhost:4318`
  - **Description:** OpenTelemetry collector endpoint.
  - **Guidance:**
  - Relevant of self-instrumenting HyperDX.
  - Use default for local development
  - Set to your collector URL in production
  - Must be accessible from your HyperDX service
- `USAGE_STATS_ENABLED`

  - **Default:** `true`
  - **Description:** Toggles usage statistics collection.
  - **Guidance:**
  - Set to `false` to disable usage tracking
  - Useful for privacy-sensitive deployments
  - Default is `true` for better product improvement
- `IS_OSS`

  - **Default:** `true`
  - **Description:** Indicates if running in OSS mode.
  - **Guidance:**
  - Keep as `true` for open-source deployments
  - Set to `false` for enterprise deployments
  - Affects feature availability
- `IS_LOCAL_MODE`

  - **Default:** `false`
  - **Description:** Indicates if running in local mode.
  - **Guidance:**
  - Set to `true` for local development
  - Disables certain production features
  - Useful for testing and development
- `EXPRESS_SESSION_SECRET`

  - **Default:** `hyperdx is cool 👋`
  - **Description:** Secret for Express session management.
  - **Guidance:**
  - Change in production
  - Use a strong, random string
  - Keep secret and secure
- `ENABLE_SWAGGER`

  - **Default:** `false`
  - **Description:** Toggles Swagger API documentation.
  - **Guidance:**
  - Set to `true` to enable API documentation
  - Useful for development and testing
  - Disable in production
- `BETA_CH_OTEL_JSON_SCHEMA_ENABLED`

  - **Default:** `false`
  - **Description:** Enables Beta support for the JSON type in HyperDX. See also [`OTEL_AGENT_FEATURE_GATE_ARG`](#otel-collector) to enable JSON support in the OTel collector.
  - **Guidance:**
  - Set to `true` to enable JSON support in ClickStack.

## OpenTelemetry collector[​](#otel-collector "Direct link to OpenTelemetry collector")

See ["ClickStack OpenTelemetry Collector"](/docs/use-cases/observability/clickstack/ingesting-data/otel-collector) for more details.

- `CLICKHOUSE_ENDPOINT`

  - **Default:** *None (required)* if standalone image. If All-in-one or Docker Compose distribution this is set to the integrated ClickHouse instance.
  - **Description:** The HTTPS URL of the ClickHouse instance to export telemetry data to.
  - **Guidance:**
    - Must be a full HTTPS endpoint including port (e.g., `https://clickhouse.example.com:8443`)
    - Required for the collector to send data to ClickHouse
- `CLICKHOUSE_USER`

  - **Default:** `default`
  - **Description:** Username used to authenticate with the ClickHouse instance.
  - **Guidance:**
    - Ensure the user has `INSERT` and `CREATE TABLE` permissions
    - Recommended to create a dedicated user for ingestion
- `CLICKHOUSE_PASSWORD`

  - **Default:** *None (required if authentication is enabled)*
  - **Description:** Password for the specified ClickHouse user.
  - **Guidance:**
    - Required if the user account has a password set
    - Store securely via secrets in production deployments
- `HYPERDX_LOG_LEVEL`

  - **Default:** `info`
  - **Description:** Log verbosity level for the collector.
  - **Guidance:**
    - Accepts values like `debug`, `info`, `warn`, `error`
    - Use `debug` during troubleshooting
- `OPAMP_SERVER_URL`

  - **Default:** *None (required)* if standalone image. If All-in-one or Docker Compose distribution this points to the deployed HyperDX instance.
  - **Description:** URL of the OpAMP server used to manage the collector (e.g., HyperDX instance). This is port `4320` by default.
  - **Guidance:**
    - Must point to your HyperDX instance
    - Enables dynamic configuration and secure ingestion
    - If omitted, secure ingestion is disabled unless an `OTLP_AUTH_TOKEN` value is specified.
- `OTLP_AUTH_TOKEN`

  - **Default:** *None*. Used only for standalone image.
  - **Description:** Allows an OTLP authentication token to be specified. If set, all communication requires this bearer token.
  - **Guidance:**
    - Recommended if using the standalone collector image in production.
- `HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE`

  - **Default:** `default`
  - **Description:** ClickHouse database the collector writes telemetry data to.
  - **Guidance:**
    - Set if using a custom database name
    - Ensure the specified user has access to this database
- `OTEL_AGENT_FEATURE_GATE_ARG`

  - **Default:** `<empty string>`
  - **Description:** Enables feature flags to enabled in the collector. If set to `--feature-gates=clickhouse.json` enables Beta support for the JSON type in collector, ensuring schemas are created with the type. See also [`BETA_CH_OTEL_JSON_SCHEMA_ENABLED`](#hyperdx) to enable JSON support in HyperDX.
  - **Guidance:**
  - Set to `true` to enable JSON support in ClickStack.

## ClickHouse[​](#clickhouse "Direct link to ClickHouse")

ClickStack Open Source ships with a default ClickHouse configuration designed for multi-terabyte scale, but users are free to modify and optimize it to suit their workload.

To tune ClickHouse effectively, you should understand key storage concepts such as [parts](/docs/parts), [partitions](/docs/partitions), [shards and replicas](/docs/shards), and how [merges](/docs/merges) occur at insert time. We recommend reviewing the fundamentals of [primary indices](/docs/primary-indexes), [sparse secondary indices](/docs/optimize/skipping-indexes), and data skipping indices, along with techniques for [managing data lifecycle](/docs/observability/managing-data) e.g. using a TTL lifecycle.

ClickStack supports [schema customization](/docs/use-cases/observability/schema-design) - you may modify column types, extract new fields (e.g. from logs), apply codecs and dictionaries, and accelerate queries using projections.

Additionally, materialized views can be used to [transform or filter data during ingestion](/docs/use-cases/observability/schema-design#materialized-columns), provided that data is written to the source table of the view and the application reads from the target table. Materialized views can also be used to [accelerate queries natively](/docs/use-cases/observability/clickstack/materialized_views) in ClickStack.