Skip to main content
When deploying ClickStack Open Source in production, consider the following security, stability, and configuration practices.

Network and port security

By default, Docker Compose exposes ports on the host, making them accessible from outside the container - even if tools like ufw (Uncomplicated Firewall) are enabled. This behavior is due to the Docker networking stack, which can bypass host-level firewall rules unless explicitly configured. Recommendation: Only expose ports that are necessary for production use. Typically the OTLP endpoints, API server, and frontend. For example, remove or comment out unnecessary port mappings in your docker-compose.yml file:
Refer to the Docker networking documentation for details on isolating containers and hardening access.

Session secret configuration

In production, you must set a strong, random value for the EXPRESS_SESSION_SECRET environment variable for ClickStack UI - to protect session data and prevent tampering. Here’s how to add it to your docker-compose.yml file for the app service:
You can generate a strong secret using openssl:
Avoid committing secrets to source control. In production, consider using environment variable management tools (e.g. Docker Secrets, HashiCorp Vault, or environment-specific CI/CD configs).

Secure ingestion

All ingestion should occur via the OTLP ports exposed by ClickStack distribution of the OpenTelemetry (OTel) collector. By default, this requires a secure ingestion API key generated at startup. This key is required when sending data to the OTel ports, and can be found in the ClickStack UI under Team Settings → API Keys.
Ingestion keys
Additionally, enabling TLS for OTLP endpoints is recommended.

Create an ingestion user

Creating a dedicated user for the OTel collector for ingestion into ClickHouse and ensuring ingestion is sent to a specific database e.g. otel is recommended. See “Creating an ingestion user” for further details.

ClickHouse

Users managing their own ClickHouse instance should adhere to the following best practices.

Security best practices

If you’re managing your own ClickHouse instance, it’s essential to enable TLS, enforce authentication, and follow best practices for hardening access. See this blog post for context on real-world misconfigurations and how to avoid them. ClickHouse OSS provides robust security features out of the box. However, these require configuration: See also external authenticators and query complexity settings for managing users and ensuring query/resource limits.

User permissions for ClickStack UI

The ClickHouse user for the ClickStack UI should have readonly = 2. The UI sets its own settings, such as date_time_output_format, on every query, and raw SQL charts also set readonly = 2, so a readonly = 1 user fails these queries with Cannot modify '...' setting in readonly mode. With readonly = 2 the UI can also set max_rows_to_read, read_overflow_mode and cancel_http_readonly_queries_on_client_close; if you constrain max_rows_to_read, allow at least 1 million. wait_end_of_query is an HTTP interface parameter rather than a setting, so it needs no grant. For example:
By default, the default user in both OSS and ClickHouse Cloud has these permissions, but we recommend creating a dedicated user.

Configure Time To Live (TTL)

Ensure the Time To Live (TTL) has been appropriately configured for your ClickStack deployment. This controls how long data is retained for - the default of 30 days may need adjusting.

MongoDB guidelines

Follow the official MongoDB security checklist.