Getting Started with CH-UI 🚀

Welcome to CH-UI! This guide will help you get up and running quickly with our modern interface for ClickHouse databases.

Quick Start ⚡

Choose your preferred installation method:

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

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 \
  ghcr.io/caioricciuti/ch-ui:latest

services:
  ch-ui:
    image: ghcr.io/caioricciuti/ch-ui:latest
    restart: always
    ports:
      - "${CH_UI_PORT:-5521}:5521"
    environment:
      VITE_CLICKHOUSE_URL: "${CLICKHOUSE_URL}"
      VITE_CLICKHOUSE_USER: "${CLICKHOUSE_USER}"
      VITE_CLICKHOUSE_PASS: "${CLICKHOUSE_PASS}"
      # Advanced Options (Optional)
      VITE_CLICKHOUSE_USE_ADVANCED: "${CLICKHOUSE_USE_ADVANCED:-false}"
      VITE_CLICKHOUSE_CUSTOM_PATH: "${CLICKHOUSE_CUSTOM_PATH:-}"

docker-compose up -d

git clone https://github.com/caioricciuti/ch-ui.git
cd ch-ui

npm install

npm run build

npm run preview

npm run dev

System Requirements 🖥️

Prerequisites

• A running ClickHouse server (Installation Guide)
• For Docker: Docker Engine 20.10.0 or newer
• For building from source:
  • Node.js >= 20.x
  • npm >= 10.x

Configuration Options ⚙️

Environment Variables

Advanced Features (required to set custom path)

When VITE_CLICKHOUSE_USE_ADVANCED is enabled:

• VITE_CLICKHOUSE_CUSTOM_PATH is required to set a custom HTTP path for ClickHouse.
• The path should be relative to the ClickHouse server URL, without the protocol (e.g., “/path/to/clickhouse”).

Development Environment 🛠️

Local ClickHouse Instance

Run a local ClickHouse instance for development:

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

Project Structure 📁

ch-ui/
├── src/
│   ├── components/    # Reusable React components
│   ├── pages/        # Main page components
│   ├── store/        # State management (Zustand)
│   ├── lib/          # Utility functions
│   └── types/        # TypeScript definitions
├── public/           # Static assets
├── App.tsx          # Main application component
└── main.tsx         # Application entry point

Security Best Practices 🔒

For production deployments, we recommend:

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

3. Access Control

   • Use minimal privilege ClickHouse users
   • Regularly rotate credentials
   • Monitor access logs

Getting Started Guide 📚

Support & Community 👥

• Documentation: Browse our comprehensive guides
• GitHub Issues: Report bugs or request features on our GitHub repository
• Discussions: Join our community discussions

Support the Project

If you find CH-UI helpful, consider:

Next Steps 🎯

• Explore Core Concepts
• Learn about Advanced Features
• Check out our API Reference
• Join our Community