# Deploy ClickHouse with the clickhouse template

Source: https://docs.quake.ai/resources/deployments/deploy-clickhouse-template
Markdown: https://docs.quake.ai/resources/deployments/deploy-clickhouse-template.md

---

# Deploy ClickHouse with the clickhouse template

Stand up [ClickHouse](https://clickhouse.com), a fast analytical column store, on a single Quake AI instance using the [validated OpenTofu template](/docs/platform/validation#how-infrastructure-templates-are-checked) `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.

<PricingCompanion
  components={[
    { kind: "template", slug: "clickhouse", required: true },
  ]}
/>

## 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](/docs/tools/openstack-cli).
- 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](/resources/iac-templates/clickhouse).
- 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:

```bash
cp terraform.tfvars.example terraform.tfvars
```

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

Initialize, plan, and apply:

```bash
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`:

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

Confirm the container is running:

```bash
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:

```bash
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](/resources/iac-templates/clickhouse)
- [self-managed PostgreSQL template](/resources/iac-templates/self-managed-postgres)
- [Security hardening checklist](/docs/security/hardening-checklist)

## Clean up

```bash
tofu destroy
```

Export any datasets you want to keep before you destroy.