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

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

Step 2: Create Your Configuration

Copy the example environment file:

cp .env.example .env

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

Generate a secure session secret with:

openssl rand -hex 32

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

Once the container has started, open:

http://localhost:3000

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"

Verify the installation:

bun --version

Step 2: Clone the Repository

git clone https://github.com/Quantrail-Data/CH-Ops.git
cd CH-Ops

Step 3: Install Dependencies

Install the project dependencies:

bun install

Step 4: Build a Standalone Binary

Build a binary for your current platform:

bun run build:binary

You can also cross-compile for specific platforms:

bun run build:binary:linux

bun run build:binary:mac

bun run build:binary:windows

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

chops-linux-x64
chops-darwin-arm64
chops-windows-x64.exe

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

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

Run CH-Ops:

./chops-linux-x64

Generate a secure session secret with:

openssl rand -hex 32

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

Open the application at:

http://localhost:3000

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

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

sudo chown -R chops:chops /opt/chops

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

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

Understanding the Service Configuration

Each setting has a specific purpose:

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

Enable CH-Ops at boot:

sudo systemctl enable chops

Start the service:

sudo systemctl start chops

Check its status:

sudo systemctl status chops

If everything is configured correctly, you should see:

Active: active (running)

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

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

You can also inspect recent logs:

sudo journalctl -u chops -n 50

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

Stop:

sudo systemctl stop chops

Restart:

sudo systemctl restart chops

Check status:

sudo systemctl status chops

View recent logs:

sudo journalctl -u chops -n 50

Follow logs in real time:

sudo journalctl -u chops -f

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

View Human-Readable Logs

sudo journalctl -u chops -f

View JSON Logs

sudo journalctl -u chops -o json | jq '.MESSAGE | fromjson'

View Only Errors

sudo journalctl -u chops -f | grep '"level":"error"'

View Logs from the Last Hour

sudo journalctl -u chops --since "1 hour ago"

Enable Debug Logging

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

LOG_LEVEL=debug

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"

Verify it:

bun --version

Step 2: Clone the Repository

git clone https://github.com/Quantrail-Data/CH-Ops.git
cd CH-Ops

Step 3: Install Dependencies

bun install

Step 4: Create Your Configuration

Copy the example configuration:

cp .env.example .env

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

Generate a secure session secret:

openssl rand -hex 32

Step 5: Run Database Migrations

Initialize the application's database schema:

bun run db:migrate

Step 6: Start CH-Ops

For development:

bun run dev

The development server will be available at:

http://localhost:5173/

For a production build:

bun run build

Then start the backend:

bun src/backend/server.js

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

• CH-Ops GitHub Repository
• CH-Ops Official Website