Getting Started 🚀

Let’s get you up and running with CH-UI in no time.

Prerequisites

A running ClickHouse server instance. If you don’t have one, follow the ClickHouse Official Installation Guide.

🐳 Using Docker

Deploy CH-UI quickly using Docker:

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

Using Environment Variables with Docker

CH-UI supports setting ClickHouse connection details using environment variables:

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

Using docker-compose

Create a docker-compose.yml file (or use the one provided in the repository):

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

Then run:

docker-compose up # use -d to run in detached mode

💻 Building from Source

Clone the repository:

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

Install dependencies:
```
cd ch-ui
npm install
```
Build the project:
```
npm run build
```
Preview the build:
```
npm run preview
```
Or run in debug mode:
```
npm run dev
```

Using docker-compose to run a localhost clickhouse (only for development)

The following command will run a clickhouse database with a connection to http://localhost:8123 and a user dev with password dev. The data will be persisted in this directory: .clickhouse_local_data

docker-compose -f docker-compose-dev.yml up -d

Use the following command to turn down, don’t forget to remove .clickhouse_local_data if you want to save some space in your HD but then all data will be erased.

docker-compose -f docker-compose-dev.yml down

Project Structure

/src: Main source directory
- /components: Reusable React components
- /pages: Main page components (Home, Metrics, Settings)
- /store: State management with Zustand
- /lib: Utility functions
- /types: TypeScript type definitions
App.tsx: Main application component
main.tsx: Application entry point

Features

ClickHouse Integration: Seamlessly interact with ClickHouse databases.
Dynamic UI Components: Advanced UI for enhanced data interaction.
Responsive Tab Management: Create and manage query tabs and table tabs.
Performance Optimizations: Efficient state management and optimized database interactions.
TypeScript Refactor: Improved code quality and developer experience.
Enhanced Metrics: Redesigned metrics dashboard with new insights.
Custom Table Management: Internally handled tables for better control.
SQL Editor IntelliSense: Autocomplete suggestions and syntax highlighting.
Intuitive Data Explorer: Redesigned interface for easier navigation.
Fresh New Design: Modern, clean UI for improved usability.

Security Recommendations

For production use, consider implementing these security measures:

Use a reverse proxy with authentication (e.g., Nginx with basic auth).
Enable HTTPS to encrypt all traffic.
Implement IP whitelisting if possible.
Keep all components up to date.
Configure a firewall to restrict incoming connections.

Refer to the full README for detailed security configuration examples.

Next Steps

Connect to your ClickHouse server through the Settings page.
Explore databases and tables using the Database Explorer.
Write and execute SQL queries in the SQL Editor.
Organize your work using Workspace Tabs.

For more detailed information on each feature, please refer to the respective sections in this documentation.

Contributing

If you want to contribute to CH-UI, please read our contributing guide.

Support

Financial support:
Contribute: Find a bug or suggest a feature. All lines of code are welcome!
Spread the word: Star the project on GitHub or share it with your network.

Your support helps keep the project running and improving. Thank you!

Start Here Core Concepts