Deploy ClickHouse with the clickhouse template

Stand up ClickHouse, a fast analytical column store, on a single Quake AI instance using the validated OpenTofu template clickhouse. You apply the template, read the bootstrap credentials, connect with the HTTP interface, create a database and table, and run an analytical query.

ClickHouse is the query layer for large analytical datasets. You run it yourself; this is a self-hosted tool you operate, not a managed warehouse.

Prerequisites#

You need:

• OpenTofu 1.6.0 or later (or Terraform 1.6.0 or later) installed locally.
• Your OpenStack credentials sourced into the shell (source openrc.sh). See the OpenStack CLI guide.
• An SSH keypair that already exists in your project. Record its name for the key_name variable.
• A copy of the clickhouse template directory from the template reference page.
• Your workstation's public IP address. Find it with curl -sS https://api.ipify.org.

Step 1: Set the variables and apply the template#

Copy the template's example variables file and set your key and workstation IP:

cp terraform.tfvars.example terraform.tfvars

key_name             = "YOUR_KEY_NAME"
client_allowed_cidr  = "YOUR_IP/32"

Initialize, plan, and apply:

tofu init
tofu plan
tofu apply

Record floating_ip and http_url from tofu output.

Step 2: Read the bootstrap credentials#

ClickHouse does not ship a default password. cloud-init writes credentials to /opt/clickhouse/.bootstrap-user:

ssh ubuntu@YOUR_FLOATING_IP "sudo cat /opt/clickhouse/.bootstrap-user"

Confirm the container is running:

ssh ubuntu@YOUR_FLOATING_IP "sudo docker ps --filter name=clickhouse"

Step 3: Create a database and run a query#

Replace YOUR_PASSWORD with the password from step 2:

curl "http://YOUR_FLOATING_IP:8123/?user=default&password=YOUR_PASSWORD" \
  --data-binary "CREATE DATABASE IF NOT EXISTS demo"

curl "http://YOUR_FLOATING_IP:8123/?user=default&password=YOUR_PASSWORD" \
  --data-binary "
CREATE TABLE IF NOT EXISTS demo.events (
  event_date Date,
  event_name String,
  count UInt32
) ENGINE = MergeTree()
ORDER BY (event_date, event_name);

INSERT INTO demo.events VALUES
  ('2026-07-01', 'page_view', 120),
  ('2026-07-01', 'signup', 8),
  ('2026-07-02', 'page_view', 95),
  ('2026-07-02', 'signup', 12)
"

curl "http://YOUR_FLOATING_IP:8123/?user=default&password=YOUR_PASSWORD" \
  --data-binary "
SELECT event_name, sum(count) AS total
FROM demo.events
GROUP BY event_name
ORDER BY total DESC
FORMAT PrettyCompact
"

What you built#

• Applied the clickhouse template to provision network, security group, data volume, instance, and floating IP
• Read bootstrap credentials and connected over the HTTP interface
• Created a database, loaded sample data, and ran an aggregation query

Scope of this deployment#

This template runs a single-VM ClickHouse host, not a managed warehouse. The instance is CPU-only and runs in one region. You operate the instance, Docker, ClickHouse, and the data volume yourself.

Next steps#

• ClickHouse template
• self-managed PostgreSQL template
• Security hardening checklist

Clean up#

tofu destroy

Export any datasets you want to keep before you destroy.