README.md

CH-UI 🚀

A modern, feature-rich web interface for ClickHouse databases. CH-UI provides an intuitive platform for managing ClickHouse databases, executing queries, and visualizing metrics about your instance.

🌟 Key Features

Core Functionality

• 🔄 ClickHouse Integration: Seamless connection and interaction with ClickHouse databases
• 📝 Advanced SQL Editor:
  • Intelligent IntelliSense with autocomplete suggestions
  • Syntax highlighting
  • Query history tracking
  • Multi-tab query execution
• 📊 Dynamic Data Visualization:
  • Interactive data tables with sorting and filtering
  • Custom visualization options
  • Real-time data updates

Performance & Architecture

• ⚡ Optimized Performance:
  • IndexedDB-based caching system
  • Efficient state management
  • Responsive UI even with large datasets
• 🔒 TypeScript Implementation: Full TypeScript support for improved code quality and developer experience
• 📦 Custom Table Management: Built-in table handling without third-party dependencies

Monitoring & Analytics

• 📈 Enhanced Metrics Dashboard:
  • Query performance monitoring
  • Table statistics and insights
  • System settings overview
  • Network performance metrics
  • Resource utilization tracking

User Experience

• 🎨 Modern UI/UX:
  • Clean, intuitive interface
  • Responsive design
  • Dark/Light mode support
  • Customizable layouts

📸 Screenshots

🚀 Getting Started

Option 1: Docker (Recommended)

Simple Start

docker run -p 5521:5521 ghcr.io/caioricciuti/ch-ui:latest

Using Docker Compose

Create a docker-compose.yml:

services:
  ch-ui:
    image: ghcr.io/caioricciuti/ch-ui:latest
    restart: always
    ports:
      - "5521:5521"
    environment:
      VITE_CLICKHOUSE_URL: "http://your-clickhouse-server:8123"
      VITE_CLICKHOUSE_USER: "your-username"
      VITE_CLICKHOUSE_PASS: "your-password"

Then run:

docker-compose up -d

Environment Variables

Variable	Description	Required	Default
VITE_CLICKHOUSE_URL	ClickHouse server URL	Yes	-
VITE_CLICKHOUSE_USER	ClickHouse username	Yes	-
VITE_CLICKHOUSE_PASS	ClickHouse password	No	""
VITE_CLICKHOUSE_USE_ADVANCED	Enable advanced ClickHouse features (e.g., custom settings, system tables access)	No	false
VITE_CLICKHOUSE_CUSTOM_PATH	Custom path for ClickHouse HTTP interface	No	-

Advanced Docker Configuration

services:
  ch-ui:
    image: ghcr.io/caioricciuti/ch-ui:latest
    restart: always
    ports:
      - "5521:5521"
    environment:
      VITE_CLICKHOUSE_URL: "http://your-clickhouse-server:8123"
      VITE_CLICKHOUSE_USER: "your-username"
      VITE_CLICKHOUSE_PASS: "your-password"
      # Advanced Options
      VITE_CLICKHOUSE_USE_ADVANCED: "true"  # Enable advanced features
      VITE_CLICKHOUSE_CUSTOM_PATH: "/custom/path"  # Optional: Custom HTTP path

Or using Docker run with advanced options:

docker run -p 5521:5521 \
  -e VITE_CLICKHOUSE_URL=http://your-clickhouse-server:8123 \
  -e VITE_CLICKHOUSE_USER=your-username \
  -e VITE_CLICKHOUSE_PASS=your-password \
  -e VITE_CLICKHOUSE_USE_ADVANCED=true \
  -e VITE_CLICKHOUSE_CUSTOM_PATH=/custom/path \
  ghcr.io/caioricciuti/ch-ui:latest

Option 2: Build from Source

Prerequisites

• Node.js >= 20.x
• npm >= 10.x

Installation Steps

# Clone the repository
git clone https://github.com/caioricciuti/ch-ui.git

# Navigate to project directory
cd ch-ui

# Install dependencies
npm install

# Build the project
npm run build

# Start for development
npm run dev

# Start for production
npm run preview

🧪 Development Environment

Local ClickHouse Instance

For development purposes, you can run a local ClickHouse instance using Docker:

# Start ClickHouse
docker-compose -f docker-compose-dev.yml up -d

# Stop ClickHouse
docker-compose -f docker-compose-dev.yml down

Default credentials:

• URL: http://localhost:8123
• Username: dev
• Password: dev

Data is persisted in .clickhouse_local_data directory.

🔒 Security Recommendations

Production Deployment

When deploying CH-UI in a production environment, consider the following security measures:

1. Reverse Proxy Setup

   • Use Nginx/Apache as a reverse proxy
   • Enable HTTPS
   • Implement authentication

2. Network Security

   • Run on a private network when possible
   • Use VPN for remote access
   • Implement IP whitelisting

Example Nginx Configuration with Basic Auth

server {
    listen 80;
    server_name your-domain.com;

    location / {
        auth_basic "Restricted Access";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        proxy_pass http://localhost:5521;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

📚 Documentation

For detailed documentation, visit our official documentation.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

❤️ Sponsors

Iberodata - Empowering businesses with data-driven solutions

☕ Support the Project

If you find CH-UI helpful, consider supporting its development:

Your support helps maintain and improve CH-UI! ✨

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.