00 Setup

Install the required tools, create a ClickHouse Cloud account, clone the repository, and verify the workshop artifacts.

Starting point

You need a terminal, a machine that can run Docker, and about 15 minutes. Choose whether the Elasticsearch source stack will run locally or on EC2 before you begin module 01.

Step 1 — Install the toolchain

Requirement	Version or note
Docker Engine and Compose	Docker 24 or newer; Compose 2.20 or newer
Available memory	16 GB minimum; 32 GB recommended
Disk	At least 5 GB free
`curl` and `jq`	Used by validation scripts
ClickHouse CLI	Used for DDL, dictionaries, and validation
Terraform	1.5 or newer, only for the EC2 source option
AWS account and EC2 key pair	Only for the EC2 source option

Install the ClickHouse CLI and create a ClickHouse Cloud trial account before module 03.

Step 2 — Clone the artifacts

git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
git switch build-workshop-v1
cd workshops/elasticsearch_migration_lab

The hosted playbook contains the instructions and answer keys. This directory contains only the files you run or edit: Docker Compose, Terraform, collector configs, SQL, dashboards, validation scripts, and design worksheets. Part 4 is completed interactively in the playbook.

Step 3 — Verify the checkout

test -f part1/docker/docker-compose.source.yml
test -f part2/exercises/worksheet.md
test -f part3/clickhouse/schema.sql
docker --version
docker compose version
jq --version

If you will use the EC2 option, also run:

terraform version
aws sts get-caller-identity

Architecture checkpoints

The workshop moves through four deliberate states:

Source: Filebeat and the OTel Demo collector feed Elasticsearch and Elastic APM.
Target provisioned: ClickHouse tables, dictionaries, and materialized views exist but receive no data.
Parallel run: both collectors dual-write to Elasticsearch and ClickHouse for parity checks.
Cutover: collectors write only to ClickHouse and HyperDX becomes the observability UI.

How to verify you are done

The three test -f commands exit successfully.
Docker and Compose print versions at or above the stated minimums.
You can sign in to ClickHouse Cloud.
If using EC2, Terraform and AWS identity checks succeed.

Continue to 01 Build the source environment.