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
• Redis server (optional, for improved caching performance)

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 \
  -e REDIS_URL=redis://redis-host:6379 \
  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
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
    restart: unless-stopped
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    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 Dual Client Architecture

ClickLens uses two types of ClickHouse connections to separate metadata operations from user queries:

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
• Permission derivation at login time
• Background operations that don't require user context

Required grants:

-- Single node
CREATE USER lensuser IDENTIFIED BY 'password';
GRANT ACCESS MANAGEMENT ON *.* TO lensuser;
GRANT SELECT ON system.* TO lensuser;
GRANT SHOW DATABASES ON *.* TO lensuser;
GRANT SHOW TABLES ON *.* TO lensuser;
GRANT SHOW COLUMNS ON *.* TO lensuser;
 
-- Cluster
CREATE USER lensuser ON CLUSTER cluster-name IDENTIFIED BY 'password';
GRANT ACCESS MANAGEMENT ON *.* ON CLUSTER cluster-name TO lensuser;
GRANT SELECT ON system.* ON CLUSTER cluster-name TO lensuser;
GRANT SHOW DATABASES ON *.* ON CLUSTER cluster-name TO lensuser;
GRANT SHOW TABLES ON *.* ON CLUSTER cluster-name TO lensuser;
GRANT SHOW COLUMNS ON *.* ON CLUSTER cluster-name 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. Redis Configuration (Optional)

ClickLens supports optional Redis caching to improve performance for monitoring and table browsing features.

4.1. Benefits of Redis Caching

• Faster Response Times: Cached data reduces ClickHouse query load
• Improved User Experience: Instant data display for monitoring dashboards
• Reduced Resource Usage: Less load on ClickHouse server
• Better Scalability: Handles more concurrent users efficiently

4.2. What Gets Cached

• Table Explorer data (schemas, parts, merges, mutations)
• Monitoring metrics (system.metrics, system.asynchronous_metrics)
• Query analytics data
• Time-series chart data

4.3. Setting Up Redis

Docker Compose (recommended):

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    restart: unless-stopped

Local Development:

# Using Docker
docker run -d -p 6379:6379 redis:7-alpine
 
# Or install Redis locally
# Ubuntu/Debian
sudo apt-get install redis-server
 
# macOS
brew install redis
brew services start redis

4.4. Configuration

Add the REDIS_URL environment variable to your ClickLens configuration:

# Docker
-e REDIS_URL=redis://redis:6379
 
# Docker Compose
- REDIS_URL=redis://redis:6379
 
# Local development (.env.local)
REDIS_URL=redis://localhost:6379

Connection String Format:

• Basic: redis://localhost:6379
• With password: redis://:password@localhost:6379
• With database: redis://localhost:6379/0
• Full example: redis://:mypassword@redis.example.com:6379/1

5. 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.

5.1. System Tables by Feature

5.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>

6. 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.

7. The Dashboard

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

8. Permission System Overview

ClickLens implements a sophisticated permission derivation model that leverages ClickHouse's native RBAC system.

8.1. How Permissions Work

When you log in:

1. ClickLens authenticates against your ClickHouse server
2. Your grants are queried from system.grants (via Lens Client)
3. Grants are mapped to UI permission flags
4. The UI shows only what you have permission to access

8.2. Permission Flags

8.3. Feature Roles

ClickLens defines 6 predefined ClickHouse roles that bundle common permission sets:

9. Troubleshooting

9.1. Connection Issues

Problem: Cannot connect to ClickHouse

Solutions:

1. Verify CLICKHOUSE_HOST and CLICKHOUSE_PORT are correct
2. Ensure the HTTP interface is enabled (not just native protocol)
3. Check firewall rules
4. Verify ClickHouse is running: curl http://localhost:8123/ping

9.2. Permission Issues

Problem: Features not showing on dashboard

Solutions:

1. Check your ClickHouse grants: SHOW GRANTS FOR current_user()
2. Ensure required system tables are accessible
3. Verify the Lens service user has proper permissions
4. Check if you're using XML-configured users (see note above)

9.3. Session Issues

Problem: Frequent session expirations

Solutions:

1. Ensure SESSION_SECRET is consistent across restarts
2. Check cookie settings if behind a proxy (DISABLE_SECURE_COOKIES)
3. Verify the secret is at least 32 characters

9.4. SSL Certificate Errors

Problem: SSL certificate verification failed

Solutions:

1. Set CLICKHOUSE_VERIFY=false for self-signed certificates
2. Or install the CA certificate in the container
3. Ensure CLICKHOUSE_SECURE=true if using HTTPS

9.5. Redis Connection Issues

Problem: Redis caching not working

Solutions:

1. Verify Redis is running: redis-cli ping should return PONG
2. Check REDIS_URL environment variable is correct
3. Ensure Redis is accessible from ClickLens container (network connectivity)
4. Verify Redis port (default 6379) is not blocked by firewall
5. Check Redis logs for connection errors

10. Next Steps

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