ClickHouse Standalone

This guide will take you through the process of setting up your first standalone (also known as single-node) ClickHouse cluster using ClusterControl. By following this tutorial, you’ll have a fully functional (but non-replicated) database node that you can monitor, manage, back up, and later scale if your requirements change.

ClickHouse is a column-oriented database management system (DBMS) for online analytical processing (OLAP). Applications and clients connect to a ClickHouse server and communicate using SQL over the native (TCP) protocol or the HTTP interface.

A standalone ClickHouse node is the simplest deployment option, but it isn’t recommended for production workloads or day-to-day operations in medium- to large-scale organisations. Use it in production only for low-stakes workloads where downtime and potential data loss are acceptable.

Note

Even when you deploy a single ClickHouse node, ClusterControl configures an embedded ClickHouse Keeper (a one-node Raft ensemble) on the same host so that replicated table engines and distributed DDL still work if you later scale out. You do not need to deploy a separate Keeper node for a standalone deployment. ClusterControl also deploys ClickHouse in TLS-only mode, so the plaintext native (9000) and HTTP (8123) ports are disabled and clients connect over the secure ports.

Prerequisites

Before proceeding, ensure you have:

ClusterControl installed and running. If not, follow the instructions in Quickstart or use the Installer Script.
At least two hosts (bare-metal or virtual machines):
- One for the ClusterControl server.
- One for the ClickHouse single node or server. See Operating System for supported distributions.
SSH access to all servers.
Internet access on the database host to install the required packages from the ClickHouse repositories.
Network Time Protocol (NTP) configured and running on both hosts to keep their clocks synchronized.

Architecture

Below is a simplified diagram of the final architecture for a single-node deployment:

flowchart TD
    A{{**Users/<br>clients/<br>apps**}} --> |SQL over TLS<br>native 9440 / HTTPS 8443| B
    E[/**ClusterControl<br>192.168.40.5**/] -.- |monitors/manages| B
    subgraph standalone["ClickHouse Standalone (192.168.40.20)"]
        B[**ClickHouse Server**]
        B --- C[(Embedded<br>ClickHouse Keeper)]
    end

ClickHouse in ClusterControl is deployed without any external supporting load balancers. A single node runs the ClickHouse server together with an embedded ClickHouse Keeper on the same host, so it can function on its own and still be scaled out into a replicated topology later.

Step 1: Set up SSH key-based authentication

On the ClusterControl server, generate a new SSH key as the root user:
```
ssh-keygen -t rsa
```
Copy the public key to your standalone database node (replace 192.168.40.20 with your node’s IP/hostname):
```
ssh-copy-id -i /root/.ssh/id_rsa [email protected]
```
If the target node uses a custom SSH key or port, you can add options:
```
ssh-copy-id -i /root/.ssh/id_rsa -p 22 -o 'IdentityFile /root/myprivatekey.pem' [email protected]
```
For some advanced setups where the user (for example mymainacc) is only allowed non-root access with public keys, password challenge is disabled, but the user has sudo privileges, you can copy the root public key as the root OS user like this:
```
[root@ccnode ~]# ssh -i /home/mymainacc/.ssh/id_rsa [email protected] "sudo bash -c '
umask 077
mkdir -p   /root/.ssh
cat >>     /root/.ssh/authorized_keys
'" < ~/.ssh/id_rsa.pub
```
This copies your root public key to the target node you will be setting up for the single-node ClickHouse deployment.
Test passwordless SSH from the ClusterControl server:
```
ssh [email protected] "stat \$PWD/"
```
Ensure there is no password prompt. If the command returns the directory status, you're set.

Step 2: Deploy a new cluster (single node)

Open a web browser and go to the ClusterControl server’s IP or hostname.
On the ClusterControl dashboard, click Deploy a cluster (top-right) → Create a database cluster. This opens the Deploy cluster wizard.
Select ClickHouse from the Database dropdown. Specify the version you want to deploy by clicking the Version dropdown (for example, 24.8 or 25.3). Click Continue.
In the Deploy ClickHouse cluster wizard, configure the database cluster as below:
(1) Cluster details(2) SSH configuration(3) Node configuration(4) Add nodes(5) Preview
- Name: For example, ClickHouse-standalone-node.
- Tags: (Optional) e.g., standalone, production, dc1.
- SSH user: root
- SSH user key path: /root/.ssh/id_rsa (ClusterControl will also autofill this field)
- SSH port: 22 (default port)
- SSH sudo password: (leave blank if you rely on key-based auth)
- SSH sudo / OS elevation command: Choose either sudo (default), doas, or pbrun
- Install software: On (default)
- Disable firewall: Checked (default)
- Disable SELinux/AppArmor: Checked (default)
- Server port: 9440 (default). This is the ClickHouse native (secure TCP) port.
- Keeper port: 9281 (default). This is the embedded ClickHouse Keeper port.
- Admin user: admin (default)
- Admin password: Password to be assigned to the database admin user (minimum 6 characters)
- Data directory: /var/lib/clickhouse (default)
- ClickHouse node: Fill in the IP/hostname or FQDN of the node (for example, 192.168.40.20) and press Enter.
- Wait until the node turns green. If a red warning appears, inspect the error and fix it before continuing.
- Leave the node list at a single entry to keep this a standalone deployment.
- Review your configuration. You can go back and adjust any previous section if necessary. The deployment settings are kept until you exit the wizard.
Click Finish to start deployment.
ClusterControl will now install and configure the standalone ClickHouse node (with an embedded Keeper) on 192.168.40.20. You can track progress in the Activity Center → Jobs. After a few minutes, your new single-node cluster will appear on the Home page.

Step 3: Monitor your cluster

Once deployed, you’ll see:

Cluster health: The Home page provides the cluster state. Even though it’s a single node, it’s treated as a "cluster" of size one.
Node health: Hover over the honeycomb diagram or check the Nodes tab. You can also see more detailed histograms under ClusterControl GUI → Clusters → choose the cluster → Dashboards.
Recent alarms: Any triggered alarms will appear if there are configuration or resource issues.
Automatic recovery status: If enabled, ClusterControl can attempt to restart a crashed ClickHouse server automatically.
Topology viewer: You’ll see a very simple topology with only one node.

Step 4: Import data

You can import data into the standalone server in a variety of ways. All examples connect over the secure native port (9440) using TLS, since ClusterControl deploys ClickHouse TLS-only.

Using clickhouse-clientBulk import from a CSV fileUsing the HTTPS interface

Create a table and insert rows interactively or from a script. Replace the host, user, and password with your own:

clickhouse-client --host 192.168.40.20 --port 9440 --secure \
    --user admin --password 'myPassw0rd' \
    --query "CREATE TABLE default.trips (id UInt64, city String, fare Float64) ENGINE = MergeTree ORDER BY id"

If you deployed with a self-signed certificate, add --accept-invalid-certificate (or point --config-file at a client config that trusts the ClusterControl CA).

Stream a local CSV file into an existing table using the native client:

clickhouse-client --host 192.168.40.20 --port 9440 --secure \
    --user admin --password 'myPassw0rd' \
    --query "INSERT INTO default.trips FORMAT CSV" < trips.csv

For very large files, ClickHouse also reads compressed input directly. For example, pipe a gzip-compressed file through zcat into the same command.

You can also insert or query over the HTTP(S) interface on port 8443. For example, to run a query with curl:

curl --cacert /etc/clickhouse-server/certs/ca.crt \
    -u admin:myPassw0rd \
    'https://192.168.40.20:8443/?query=INSERT%20INTO%20default.trips%20FORMAT%20CSV' \
    --data-binary @trips.csv

Use -k in place of --cacert ... if you are testing with a self-signed certificate and accept the security trade-off.

Step 5: Connect to the database

Your application or client will connect directly to the standalone server over TLS:

Host: 192.168.40.20
Native (secure TCP) port: 9440
HTTPS port: 8443
User/Password: The admin credentials specified during deployment. You can also inspect the file /etc/cmon.d/cmon_$CID.cnf, where $CID is the cluster ID of your ClickHouse deployment.

No load balancer or additional ports are involved. A quick connectivity test with the native client:

clickhouse-client --host 192.168.40.20 --port 9440 --secure \
    --user admin --password 'myPassw0rd' \
    --query "SELECT version()"

Step 6: Enable automatic backups

Even a single-node, standalone ClickHouse cluster needs reliable backups, and ClusterControl makes it easy to schedule them automatically. ClickHouse backups in ClusterControl use the native BACKUP SQL command, which writes a consistent copy to the local backups disk (typically /var/lib/clickhouse/backups/) or to S3-compatible object storage.

Go to ClusterControl GUI → choose the cluster → Backups.
Click Create Backup → Schedule a Backup. The Create a backup schedule wizard will open. Configure your backup as below:
(1) Configuration(2) Advanced settings(3) Schedule(4) Preview
- Schedule name: Daily ClickHouse standalone backup
- Cluster: (defaults to your ClickHouse standalone cluster)
- Backup method: Choose between Clickhouse native (full) and Clickhouse native (incr) (incremental)
- Backup node: (defaults to your single node)
- Upload backup to cloud: Off (turn On to store the backup on S3-compatible object storage)
- Retention: On (default)
- Retention [textfield]: 4 (set to your desired number of days to retain backups)
- Set backup schedule: Simple
- Every: day at 02:00
- Timezone: select your local timezone
- Verify all settings. You can go back to adjust if needed.
Click Create to schedule it.

ClusterControl will now automatically perform your backups. All successful backups are listed on the Backups → All Backups page, where you can review the backup logs, size, and restore from them in the future if necessary for disaster recovery.

Note

Controller storage is not supported for ClickHouse native backups. Backups are stored on the local ClickHouse backups disk by default, or on S3-compatible object storage when you enable Upload backup to cloud.

Step 7: Configure alerts

To keep track of any issues or incidents in your cluster, it's important to set up alerting. ClusterControl supports sending alarms and alerts to email, web hooks, and third-party notification services like Slack or Telegram. In this example, we are going to use email.

Firstly, configure the mail server. Go to ClusterControl GUI → Settings → You don't have a mail server configured. Configure now → SMTP Server. Fill in all the necessary information about the SMTP server. You can also opt for Sendmail; however, a mail transfer agent (sendmail, postfix, or exim) must be installed on the ClusterControl server.

Once configured, we can configure the alert and recipients as below:

Go to ClusterControl GUI → choose the cluster → Settings → Email Notifications.
Select a user group (your group) from the User group dropdown.
Select your email address from the Users in the selected group dropdown.
Click Enable.
Set the Digest delivery time for when you want a digested (summarized events) email sent to you every day.
Set all Critical events to "Deliver" (default), all Warning events to "Digest", and you may ignore the Info events.

This ensures timely notifications when something goes wrong.

Tip

You can also configure alarms to be sent to third-party notification systems (Slack, Telegram), incident management systems (PagerDuty, ServiceNow, OpsGenie), or web hooks. See Integration → Notification Services.

Step 8: Manage your node

ClusterControl provides monitoring for your cluster and a system overview that displays workloads based on metrics. Once your ClickHouse cluster is deployed, agents using Prometheus exporters are deployed to gather metrics and provide more granular monitoring of your cluster and system workload for your standalone node.

Apart from the monitoring, you can manage your node with the available options for this cluster:

Database node management: Perform start/stop/restart node, reboot host. These features are available at ClusterControl GUI → choose the cluster → Nodes → Actions.
Configuration management: Perform database configuration changes. This feature is available at ClusterControl GUI → choose the cluster → Manage → Configuration.
Backup management: Create, schedule, and restore backups, store them in an off-cluster storage location such as AWS S3 or any S3-compatible storage, and set a retention period for your backups. These features are available at ClusterControl GUI → choose the cluster → Backups → Actions and ClusterControl GUI → choose the cluster → Backups → More.
Maintenance management: Activate, deactivate, remark, and schedule maintenance mode for all nodes. This feature is available at ClusterControl GUI → choose the cluster → Nodes → Actions → Schedule maintenance.
SSH console: Access your nodes directly from the ClusterControl GUI via web SSH console. This feature is available at ClusterControl GUI → choose the cluster → Nodes → Actions → SSH Console.

Conclusion

You have now deployed, monitored, and managed a standalone ClickHouse server using ClusterControl. A single-node deployment runs the ClickHouse server together with an embedded Keeper, so it works on its own and can be scaled out into a replicated topology later. A single node has no redundancy, but it still gives you what you need to run analytics workloads. As you operate it, keep the following in mind:

Keep your backups current and up to date.
Monitor performance and resource usage.
Secure your node by restricting access and using strong passwords.
Expand to a multi-node, replicated topology if your needs grow.

From here, ClusterControl handles the day-to-day operations such as backups, alerts, and scaling, so you can focus on your data.