quantrailadmin1/ch-ops repository overview

⁠CHOps: ClickHouse GUI and ClickHouse Admin Tool

CHOps is a ClickHouse GUI and a ClickHouse admin tool. It manages the ClickHouse® database from one browser tab.

This ClickHouse GUI runs queries, monitors clusters, profiles queries, builds dashboards, controls access, and backs up data. It works with self-hosted, VM, Kubernetes, and managed ClickHouse®. It connects over the ClickHouse® HTTP interface and installs nothing on your database servers.

• Website: https://ch-ops.io⁠
• Source: https://github.com/Quantrail-Data/CH-Ops⁠
• Docs: https://ch-ops.io/docs⁠

⁠Image and tags

• latest : the newest release.
• 0.2.0 : an exact version. It does not move.
• 0.2 : the newest patch in the 0.2 line.
• 0 : the newest release in the 0 line.

CHOps is before version 1.0. A 0.x release can have breaking changes. Pin 0.2.0 or 0.2 for a stable deployment.

⁠Run with Docker

CHOps needs a session secret and one super-admin account. Do these steps.

# 1. Make a session secret.
export SESSION_SECRET=$(openssl rand -hex 32)

# 2. Start the container.
docker run -d --name chops -p 3000:3000 \
  -e SESSION_SECRET="$SESSION_SECRET" \
  -e SUPER_ADMIN_1=admin \
  -e SUPER_ADMIN_1_PASSWORD=change-this-password \
  -e [email protected] \
  -v chops-data:/app/data \
  quantrailadmin1/ch-ops:0.2.0

Then open http://localhost:3000⁠. Log in with the super-admin user name and password that you set.

⁠Run with Docker Compose

Make a file named docker-compose.yml. Put this content in it. Change the session secret and the admin password first.

services:
  chops:
    image: quantrailadmin1/ch-ops:0.2.0
    container_name: chops
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - SESSION_SECRET=replace-with-a-long-random-value
      - SUPER_ADMIN_1=admin
      - SUPER_ADMIN_1_PASSWORD=change-this-password
      - [email protected]
    volumes:
      - chops-data:/app/data

volumes:
  chops-data:

Start the stack:

docker compose up -d

Then open http://localhost:3000⁠. To stop CHOps, run docker compose down. Your data stays in the chops-data volume.

⁠Required configuration

The docs list all optional variables, such as SMTP for email alerts: https://ch-ops.io/docs/getting-started/configuration⁠

⁠Data and persistence

CHOps stores its own configuration in a small SQLite file under /app/data. This file holds users, dashboards, alerts, and settings. Mount a volume there, as shown above. Then this data survives a container restart.

CHOps does not store your ClickHouse® data.

⁠Update to a new version

With Docker:

docker pull quantrailadmin1/ch-ops:0.2.0
docker rm -f chops
# Then run the "docker run" command again.

With Docker Compose:

# 1. Change the image tag in docker-compose.yml.
# 2. Pull and restart:
docker compose pull
docker compose up -d

The chops-data volume keeps your settings across an update.

⁠Notes

• The open-source features need no agent on your ClickHouse® nodes.
• The container runs as a non-root user.
• CHOps serves a health check at /api/health.
• This ClickHouse admin tool is also on GitHub Container Registry: ghcr.io/quantrail-data/ch-ops.

⁠License and trademarks

CHOps is open source under the AGPL. A commercial license is available.

ClickHouse® is a registered trademark of ClickHouse, Inc. CHOps is an independent project from Quantrail. It is not affiliated with, endorsed by, or sponsored by ClickHouse, Inc. All product names and trademarks are the property of their respective owners.