Getting Started

This guide will help you get ClickLens up and running with your ClickHouse database.

1. Prerequisites

Before installing ClickLens, ensure you have:

• A running ClickHouse server (version 21.8 or later recommended)
• ClickHouse HTTP interface enabled (ports 8123 for HTTP, 8443 for HTTPS)
• A ClickHouse user account with appropriate permissions

2. Installation

2.1. Option 1: Docker (Recommended)

The fastest way to run ClickLens is with Docker:

docker run -d \
  --name clicklens \
  -p 3000:3000 \
  -e CLICKHOUSE_HOST=your-clickhouse-host \
  -e CLICKHOUSE_PORT=8123 \
  -e LENS_USER=lensuser \
  -e LENS_PASSWORD=your-password \
  -e SESSION_SECRET=your-32-character-secret-key-here \
  ghcr.io/ntk148v/clicklens:latest

Then open http://localhost:3000 (opens in a new tab) in your browser.

2.2. Option 2: Docker Compose

Create a docker-compose.yml file:

services:
  app:
    image: ghcr.io/ntk148v/clicklens:latest
    ports:
      - "3000:3000"
    environment:
      - CLICKHOUSE_HOST=your-clickhouse-host
      - CLICKHOUSE_PORT=8123
      - LENS_USER=lensuser
      - LENS_PASSWORD=your-password
      - SESSION_SECRET=your-32-character-secret-key-here
      - NODE_ENV=production
      - DISABLE_SECURE_COOKIES=true
    restart: unless-stopped

Then run:

docker-compose up -d

2.3. Option 3: Local Development

For local development with Bun:

# Clone the repository
git clone https://github.com/ntk148v/clicklens.git
cd clicklens
 
# Install dependencies
bun install
 
# Copy environment file
cp env.sample .env.local
 
# Edit .env.local with your ClickHouse connection details
# Then start the development server
bun dev

The app will be available at http://localhost:3000 (opens in a new tab).

3. Understanding the Service User

ClickLens uses two types of ClickHouse connections:

3.1. Lens Service User (Environment Credentials)

Configured via LENS_USER and LENS_PASSWORD environment variables. This service account is used for:

• Schema introspection and metadata queries
• System table access for monitoring features
• Background operations that don't require user context

Recommended minimal grants:

CREATE USER lensuser IDENTIFIED BY 'your-password';
GRANT SELECT ON system.* TO lensuser;
GRANT SHOW DATABASES ON *.* TO lensuser;
GRANT SHOW TABLES ON *.* TO lensuser;
GRANT SHOW COLUMNS ON *.* TO lensuser;

3.2. User Client (Session Credentials)

When you log in to ClickLens, your ClickHouse username and password are used directly for:

• Executing your SQL queries
• Determining your UI permissions
• All data access operations

4. ClickHouse System Tables

ClickLens relies on ClickHouse's built-in system tables to provide its features. Understanding which tables are used helps with permission planning and troubleshooting.

4.1. System Tables by Feature

4.2. Optional System Tables

Some ClickLens features depend on tables that may not exist by default:

To enable optional logging tables, add to your ClickHouse config.xml:

<clickhouse>
    <!-- Enable text_log for server logs -->
    <text_log>
        <database>system</database>
        <table>text_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    </text_log>
 
    <!-- Enable session_log for login tracking -->
    <session_log>
        <database>system</database>
        <table>session_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    </session_log>
 
    <!-- Enable metric_log for time-series charts -->
    <metric_log>
        <database>system</database>
        <table>metric_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <collect_interval_milliseconds>1000</collect_interval_milliseconds>
    </metric_log>
</clickhouse>

5. First Login

1. Navigate to http://localhost:3000 (opens in a new tab)
2. Enter your ClickHouse credentials:
   • Username: Your ClickHouse user
   • Password: Your ClickHouse password
3. Click Login

Upon successful login, you'll be taken to the Dashboard.

6. The Dashboard

The Dashboard is your starting point in ClickLens. It displays feature cards based on your permissions:

7. Next Steps

• Explore the Features guide to learn about each module
• Read about Deployment for production configuration
• Check the Architecture documentation for technical details