DEV Community

Cover image for Install CH-Ops in 10 Minutes: Docker, Binary, or Source
Kanishga Subramani
Kanishga Subramani

Posted on

Install CH-Ops in 10 Minutes: Docker, Binary, or Source

#clickhouse #analytics #devops #database

Getting started with a new database operations tool shouldn't take hours of setup.

CH-Ops gives you three installation options depending on how you prefer to work:

  • Docker — the fastest way to get started.
  • Standalone Binary — ideal for production deployments.
  • Build from Source — perfect if you want to contribute or customize the application.

In this guide, you'll learn how to install CH-Ops using all three approaches, configure it, run it as a Linux service, troubleshoot startup issues, and connect it to your ClickHouse® deployment.

What Is CH-Ops?

CH-Ops is a browser-based operations platform for ClickHouse®. Instead of relying entirely on the command line or HTTP API, it provides a visual interface for managing your ClickHouse deployment.

It provides functionality for:

  • Running SQL queries
  • Monitoring cluster health
  • Managing users
  • Managing backups
  • Configuring alerts
  • Exploring dashboards
  • Managing ClickHouse clusters

CH-Ops stores its own configuration in a local SQLite database. It does not modify your ClickHouse data unless you explicitly execute queries against your cluster.

Choose Your Installation Method

Method Best For Approximate Setup Time
Docker Fastest setup, testing, local development ~5 minutes
Standalone Binary Production deployments ~5 minutes
Build from Source Development and customization ~10 minutes

Let's look at each option.

Option 1: Install with Docker

If you already have Docker installed, this is the quickest way to run CH-Ops.

Step 1: Clone the Repository

Clone the CH-Ops repository:

git clone https://github.com/Quantrail-Data/CH-Ops.git
cd CH-Ops
Enter fullscreen mode Exit fullscreen mode

Step 2: Create Your Configuration

Copy the example environment file:

cp .env.example .env
Enter fullscreen mode Exit fullscreen mode

Update the required values in .env:

SUPER_ADMIN_1=admin
SUPER_ADMIN_1_PASSWORD=your_secure_password_here
SUPER_ADMIN_1_EMAIL=you@example.com
SESSION_SECRET=paste_a_random_string_here
Enter fullscreen mode Exit fullscreen mode

Generate a secure session secret with:

openssl rand -hex 32
Enter fullscreen mode Exit fullscreen mode

Make sure the required environment variables are configured before starting the application.

Step 3: Start CH-Ops

Start CH-Ops using Docker Compose:

docker compose up -d --build
Enter fullscreen mode Exit fullscreen mode

Once the container has started, open:

http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

You should now see the CH-Ops login page.

That's it.

Why Docker?

Docker is a convenient option because it provides:

  • Minimal setup
  • No need to install Bun separately
  • Persistent SQLite storage
  • Easy upgrades
  • A consistent runtime environment
  • A quick way to test CH-Ops

Remember to configure all required environment variables before starting the container.

Option 2: Install Using the Standalone Binary

A standalone binary is a good choice when you want to deploy CH-Ops directly on a server without running it through a development environment.

CH-Ops can be packaged as a single executable with the application and its dependencies included.

Prebuilt binaries can be provided for platforms such as:

  • Linux
  • macOS
  • Windows

If you need to build the binary yourself, follow the steps below.

Step 1: Install Bun

CH-Ops is built using Bun.

Install the required Bun version:

curl -fsSL https://bun.com/install | bash -s "bun-v1.3.13"
Enter fullscreen mode Exit fullscreen mode

Verify the installation:

bun --version
Enter fullscreen mode Exit fullscreen mode

Step 2: Clone the Repository 

git clone https://github.com/Quantrail-Data/CH-Ops.git
cd CH-Ops
Enter fullscreen mode Exit fullscreen mode

Step 3: Install Dependencies

Install the project dependencies:

bun install
Enter fullscreen mode Exit fullscreen mode

Step 4: Build a Standalone Binary

Build a binary for your current platform:

bun run build:binary
Enter fullscreen mode Exit fullscreen mode

You can also cross-compile for specific platforms:

bun run build:binary:linux
Enter fullscreen mode Exit fullscreen mode 
bun run build:binary:mac
Enter fullscreen mode Exit fullscreen mode 
bun run build:binary:windows
Enter fullscreen mode Exit fullscreen mode

Depending on the target, the generated files can look like:

chops-linux-x64
chops-darwin-arm64
chops-windows-x64.exe
Enter fullscreen mode Exit fullscreen mode

During the build process, the Vite build compiles the React frontend into static assets under dist/. Bun then packages the backend, dependencies, and frontend assets into the standalone executable.

Run the Binary

For Linux, make the binary executable:

chmod +x chops-linux-x64
Enter fullscreen mode Exit fullscreen mode

Then configure the required environment variables:

export SUPER_ADMIN_1=admin
export SUPER_ADMIN_1_PASSWORD=your_secure_password
export SUPER_ADMIN_1_EMAIL=you@example.com
export SESSION_SECRET=your_secure_session_secret
Enter fullscreen mode Exit fullscreen mode

Run CH-Ops:

./chops-linux-x64
Enter fullscreen mode Exit fullscreen mode

Generate a secure session secret with:

openssl rand -hex 32
Enter fullscreen mode Exit fullscreen mode

CH-Ops automatically creates its internal SQLite database when it starts.

Open the application at:

http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

You can now sign in using your configured administrator credentials.

Why Choose the Binary?

A standalone binary is useful when you want:

  • A single executable
  • Minimal runtime dependencies
  • Easy server deployment
  • Simple distribution
  • A production-oriented installation

If you need to customize the application or contribute code, building directly from source is the better option.

Running CH-Ops as a Linux systemd Service

When deploying CH-Ops on a Linux server, manually starting the application after every reboot isn't ideal.

Instead, you can run CH-Ops as a systemd service.

systemd is the default service manager on many modern Linux distributions. It can:

  • Start CH-Ops automatically during boot
  • Restart the application if it crashes
  • Run it under a dedicated user
  • Manage permissions
  • Centralize application logs through journald

Step 1: Create a Dedicated Service User

For security, avoid running CH-Ops as root.

Create a dedicated system user:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin chops
Enter fullscreen mode Exit fullscreen mode

Then give the service user ownership of the CH-Ops installation:

sudo chown -R chops:chops /opt/chops
Enter fullscreen mode Exit fullscreen mode

The chops account exists only to run the application and cannot be used for interactive login.

Step 2: Create the systemd Service File

Create a service definition:

sudo nano /etc/systemd/system/chops.service
Enter fullscreen mode Exit fullscreen mode

Add:

[Unit]
Description=CH-Ops - ClickHouse Administration Dashboard
Documentation=https://github.com/Quantrail-Data/CH-Ops
After=network.target

[Service]
Type=simple
User=chops
Group=chops
WorkingDirectory=/opt/chops

ExecStart=/opt/chops/chops

Restart=on-failure
RestartSec=5

EnvironmentFile=/opt/chops/.env

NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/chops/data
PrivateTmp=true

StandardOutput=journal
StandardError=journal
SyslogIdentifier=chops

[Install]
WantedBy=multi-user.target
Enter fullscreen mode Exit fullscreen mode

Understanding the Service Configuration

Each setting has a specific purpose:

Setting Purpose
After=network.target Starts CH-Ops after networking is available
User=chops Runs the application as a dedicated non-root user
Restart=on-failure Automatically restarts CH-Ops if it crashes
RestartSec=5 Waits five seconds before restarting
EnvironmentFile Loads configuration from .env
NoNewPrivileges=true Prevents the process from gaining additional privileges
ProtectSystem=strict Makes most of the filesystem read-only
ReadWritePaths=/opt/chops/data Allows CH-Ops to write to its data directory
PrivateTmp=true Provides an isolated temporary directory

These settings help reduce the potential impact of accidental changes or application vulnerabilities while keeping the service manageable.

Step 3: Enable and Start the Service

Reload systemd:

sudo systemctl daemon-reload
Enter fullscreen mode Exit fullscreen mode

Enable CH-Ops at boot:

sudo systemctl enable chops
Enter fullscreen mode Exit fullscreen mode

Start the service:

sudo systemctl start chops
Enter fullscreen mode Exit fullscreen mode

Check its status:

sudo systemctl status chops
Enter fullscreen mode Exit fullscreen mode

If everything is configured correctly, you should see:

Active: active (running)
Enter fullscreen mode Exit fullscreen mode

Troubleshooting Startup Issues

If CH-Ops fails to start, the system journal is usually the first place to look.

Follow the service logs in real time:

sudo journalctl -u chops -f
Enter fullscreen mode Exit fullscreen mode

This lets you see startup errors and configuration problems as they happen.

You can also inspect recent logs:

sudo journalctl -u chops -n 50
Enter fullscreen mode Exit fullscreen mode

Common systemd Commands

Once CH-Ops is running as a systemd service, these are the commands you'll use most often.

Start:

sudo systemctl start chops
Enter fullscreen mode Exit fullscreen mode

Stop:

sudo systemctl stop chops
Enter fullscreen mode Exit fullscreen mode

Restart:

sudo systemctl restart chops
Enter fullscreen mode Exit fullscreen mode

Check status:

sudo systemctl status chops
Enter fullscreen mode Exit fullscreen mode

View recent logs:

sudo journalctl -u chops -n 50
Enter fullscreen mode Exit fullscreen mode

Follow logs in real time:

sudo journalctl -u chops -f
Enter fullscreen mode Exit fullscreen mode

Logging in CH-Ops

CH-Ops writes structured JSON logs to standard output.

When running under systemd, these logs are automatically captured by journald.

A log entry can contain information such as:

  • Timestamp
  • Log level
  • HTTP method
  • Request path
  • Response status
  • Request duration
  • User
  • Execution context

For example:

{
  "ts": "2026-05-18T10:30:00.000Z",
  "level": "info",
  "msg": "GET /api/alerts/rules 200 12ms",
  "ctx": {
    "method": "GET",
    "path": "/api/alerts/rules",
    "status": 200,
    "duration": 12,
    "user": "admin",
    "ip": "::1"
  }
}
Enter fullscreen mode Exit fullscreen mode

View Human-Readable Logs 

sudo journalctl -u chops -f
Enter fullscreen mode Exit fullscreen mode

View JSON Logs 

sudo journalctl -u chops -o json | jq '.MESSAGE | fromjson'
Enter fullscreen mode Exit fullscreen mode

View Only Errors 

sudo journalctl -u chops -f | grep '"level":"error"'
Enter fullscreen mode Exit fullscreen mode

View Logs from the Last Hour 

sudo journalctl -u chops --since "1 hour ago"
Enter fullscreen mode Exit fullscreen mode

Enable Debug Logging

For more detailed diagnostic information during development, add the following to .env:

LOG_LEVEL=debug
Enter fullscreen mode Exit fullscreen mode

Supported log levels include:

  • debug
  • info — default
  • warn
  • error

CH-Ops can log API requests, scheduler activity, server startup events, and application errors while avoiding sensitive information such as passwords, authentication tokens, and request bodies.

Option 3: Build CH-Ops from Source

If you're developing new functionality, customizing CH-Ops, or contributing to the project, building from source gives you complete control.

Step 1: Install Bun

Install the required Bun version:

curl -fsSL https://bun.com/install | bash -s "bun-v1.3.13"
Enter fullscreen mode Exit fullscreen mode

Verify it:

bun --version
Enter fullscreen mode Exit fullscreen mode

Step 2: Clone the Repository 

git clone https://github.com/Quantrail-Data/CH-Ops.git
cd CH-Ops
Enter fullscreen mode Exit fullscreen mode

Step 3: Install Dependencies 

bun install
Enter fullscreen mode Exit fullscreen mode

Step 4: Create Your Configuration

Copy the example configuration:

cp .env.example .env
Enter fullscreen mode Exit fullscreen mode

Configure the required administrator and session variables:

SUPER_ADMIN_1=admin
SUPER_ADMIN_1_PASSWORD=your_secure_password
SUPER_ADMIN_1_EMAIL=you@example.com
SESSION_SECRET=your_secure_session_secret
Enter fullscreen mode Exit fullscreen mode

Generate a secure session secret:

openssl rand -hex 32
Enter fullscreen mode Exit fullscreen mode

Step 5: Run Database Migrations

Initialize the application's database schema:

bun run db:migrate
Enter fullscreen mode Exit fullscreen mode

Step 6: Start CH-Ops

For development:

bun run dev
Enter fullscreen mode Exit fullscreen mode

The development server will be available at:

http://localhost:5173/
Enter fullscreen mode Exit fullscreen mode

For a production build:

bun run build
Enter fullscreen mode Exit fullscreen mode

Then start the backend:

bun src/backend/server.js
Enter fullscreen mode Exit fullscreen mode

First Login

Once CH-Ops is running, open the application in your browser.

Sign in using the Super Admin credentials configured in your environment.

After logging in:

  1. Navigate to Administration → Cluster Management.
  2. Add your ClickHouse® server.
  3. Test the connection.
  4. Save the configuration.
  5. Start exploring the available management and monitoring features.

Once your ClickHouse cluster is connected, you can use CH-Ops for tasks such as:

  • Querying your database
  • Monitoring cluster activity
  • Managing users
  • Managing backups
  • Configuring alerts
  • Exploring dashboards

Which Installation Method Should You Choose?

The right installation method depends on what you're trying to accomplish.

Choose Docker

Use Docker when you want:

  • The fastest setup
  • Local testing
  • Development environments
  • A consistent deployment environment

Choose the Standalone Binary

Use the standalone binary when you want:

  • A production-oriented deployment
  • A single executable
  • Minimal runtime dependencies
  • Simple server installation

Choose Build from Source

Build from source when you want:

  • To contribute to CH-Ops
  • To customize the application
  • To develop new features
  • Full control over the build process

All three approaches ultimately provide the same CH-Ops experience. The main difference is how you install and operate the application.

Conclusion

Installing a ClickHouse® operations platform doesn't have to be complicated.

With CH-Ops, you can choose the installation approach that matches your workflow:

Docker for a quick start, standalone binaries for production-oriented deployments, or source builds for development and customization.

Once CH-Ops is running, connect your ClickHouse® cluster, sign in with your administrator account, and start managing your database through a browser-based interface.

For the fastest way to get started, Docker is a good first choice. For a Linux production server, a standalone binary combined with systemd provides a straightforward deployment model.

References

Top comments (0)