Getting Started

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 (Recommended)

Simple Docker Setup

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

Docker with Environment Variables

docker run --name ch-ui -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

Docker Compose

Using Docker Compose

Here's a complete example of running both CH-UI and ClickHouse in the same Docker Compose file:

services:
  clickhouse:
    image: clickhouse/clickhouse-server
    environment:
      CLICKHOUSE_USER: default
      CLICKHOUSE_DB: my-clickhouse-db
    volumes:
      # Store data to HDD
      - ./clickhouse-data:/var/lib/clickhouse/
      # Base Clickhouse cfg
      - ./clickhouse/config.xml:/etc/clickhouse-server/config.d/config.xml
      - ./clickhouse/users.xml:/etc/clickhouse-server/users.d/users.xml
    ports:
      - "8123:8123/tcp"
      - "9000:9000/tcp"

  ch-ui:
    image: ghcr.io/caioricciuti/ch-ui:latest
    environment:
      VITE_CLICKHOUSE_URL: http://my-docker-host-ip-or-fqdn:8123
      VITE_CLICKHOUSE_USER: default
      VITE_CLICKHOUSE_PASS: ""
    ports:
      - "5521:5521/tcp"

Important Configuration Notes

1. The ClickHouse port 8123 is published to make it accessible on the Docker host
2. For VITE_CLICKHOUSE_URL, use your Docker host's IP address or FQDN instead of the internal Docker network name

For a simpler setup without ClickHouse, you can use this basic configuration:

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:-}"

Start the service:

docker-compose up -d

Build from Source

Building from Source

Clone Repository

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

Install Dependencies

npm install

Build Project

npm run build

Start Server

For production:

npm run preview

For development:

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

Variable	Description	Required	Default
VITE_CLICKHOUSE_URL	ClickHouse server URL	Yes	-
VITE_CLICKHOUSE_USER	ClickHouse username	No	""
VITE_CLICKHOUSE_PASS	ClickHouse password	No	""
VITE_CLICKHOUSE_USE_ADVANCED	Enable advanced features	No	false
VITE_CLICKHOUSE_CUSTOM_PATH	Custom HTTP path	No	-

Advanced Features

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

note

Data is persisted in .clickhouse_local_data directory.

Security Recommendations 🔒

Reverse Proxy Setup

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

Network Security

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

Access Control

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

Support the Project

If you find CH-UI helpful, consider: